# MoonDeadline RTOS 项目申报书

**项目名称：MoonDeadline RTOS——面向 Cortex-M3 的 MoonBit 有界抢占式实时内核**

版本：0.4.0；本轮更新日期：2026-11-06；GitHub：btlqql；主要语言：MoonBit；许可证：Apache-2.0。参赛身份沿用本人原报名信息。

- 项目仓库：[https://github.com/btlqql/moon-deadline](https://github.com/btlqql/moon-deadline)
- 公共模块：[https://mooncakes.io/docs/btlqql/moon_deadline@0.4.0](https://mooncakes.io/docs/btlqql/moon_deadline@0.4.0)
- 一页说明：[proposal-summary.md](proposal-summary.md)

## 一、项目摘要

MoonDeadline RTOS 以 MoonBit 实现固定容量的实时任务调度与同步通信核心，提供 Cortex-M3 裸机执行端口。任务从独立 PSP 栈运行，SysTick 驱动时钟与超时，PendSV 保存并恢复任务现场；内核支持固定优先级抢占、同优先级轮转、延时等待、信号量、带传递式优先级继承的互斥锁，以及有界消息队列。

本次更新针对初审提出的“旧作品限于离线分析，缺少 RTOS 执行系统 MVP”进行了实质修改。除可复用核心包外，已完成 MoonBit 实际任务体、ARM ELF 固件、平台胶水、五组裸机运行场景、两组故障注入、复现脚本与公共 CI。程序在 QEMU `mps2-an385` 模拟的 Cortex-M3 上从复位入口执行，**没有实体开发板测试**。

## 二、需求与实际使用场景

MoonBit 嵌入式原型需要同时解决任务执行、定时抢占、阻塞恢复和共享资源通信。单独给出调度公式或在主机循环中切换任务编号，不能证明目标架构的栈和寄存器现场得到正确恢复。本项目将可测试的 MoonBit 语义核心与明确平台的异常执行路径连接，供嵌入式教学、任务原型和端口验证复用。

已交付场景包括：周期中断唤醒采集任务，经队列将整数消息交给处理和消费任务；高、中、低优先级任务争用资源时，通过优先级继承使持锁任务及时获得 CPU；多个持续计算任务轮转时，短延时高优先级任务准时于指定 tick 恢复；队列满、接收超时和中断事件同 tick 到达时，保持消息与令牌不丢失、不重复消费。

采集源为定时中断和合成整数数据，尚无真实传感器、外部驱动或生产用户使用记录。项目实用范围是可复现的软件与目标架构执行原型，不以合成案例代表工业部署。

## 三、完整处理链与功能范围

处理链：MoonBit 内核及任务源码 → 原生后端生成 C → ARM GCC 交叉编译 → Cortex-M3 ELF → QEMU 复位入口 → SVC 启动任务 → SysTick/PendSV 抢占与恢复 → UART 输出断言和运行记录 → 脚本核查退出状态与证据。

| 组件 | 已实现能力 | 源码 |
|---|---|---|
| 任务与调度 | 就绪/运行/阻塞/退出、固定优先级抢占、同级轮转、idle、延时唤醒 | `rtos/kernel.mbt` |
| 同步 | 有界信号量、非递归互斥锁、传递式优先级继承、等待环拒绝、超时/退出后撤销继承 | `rtos/sync.mbt` |
| 通信 | FIFO 整数消息、阻塞发送/接收、背压、超时移除、非阻塞 ISR 发送 | `rtos/queue.mbt` |
| 实际任务体 | 抢占验证、资源竞争、采集处理消费流水线和压力任务 | `firmware/application.mbt` |
| 硬件端口 | 复位、向量表、PSP 独立栈、SVC/PendSV、SysTick、UART、临界区 | `ports/cortex-m3/` |
| 受限内存适配 | 启动 arena、常驻资源、调度启动后禁止分配/释放 | `ports/cortex-m3/runtime.c` |
| 复现与验证 | 构建、运行、故障注入、UART/ELF 哈希证据收集与公共 CI | `scripts/rtos.py`、`scripts/report_rtos.py` |

固定容量为 16 任务槽、32 级优先级、8 信号量、8 互斥锁、4 队列，每队列最多 16 个 32 位整数。示例根据场景启用 3–5 个任务，含 idle。数字越小优先级越高。timeout=-1 为无限等待，0 为轮询，正数为相对 tick；最大等待及单次时间推进为 1,000,000 tick。

## 四、技术深度与关键工程处理

**真实抢占与上下文恢复。** Cortex-M3 硬件保存异常帧，PendSV 保存 R4–R11 和 PSP，再调用 MoonBit 选择下一任务；C 中没有另一套调度算法。三个忙任务不主动调用 yield，仍能被定时中断轮转。寄存器 canary、独立栈范围及底部哨兵用于检查上下文恢复。

**传递式优先级继承。** 锁等待者的有效优先级传播给持有者，最长按固定 16 任务容量求有界固定点；支持嵌套资源导致的继承链。超时、解锁和任务退出后重新计算，防止遗留提升。非递归锁拒绝自身获取及循环等待；拥有者退出时将锁移交给等待者。

**通信与竞争语义。** 队列接收腾出位置时，将一个阻塞发送者的保留消息恰好补入一次。发送超时或任务退出后不残留待发消息。中断通知为非阻塞操作；同 SysTick 先处理超时、再投递事件，已超时等待者不吞掉新消息或令牌。所有内核入口通过 IRQ mask 串行化。

**时钟回绕与内存约束。** tick 采用 32 位回绕语义、Int64 计算，超时在半回绕范围内判定。内核资源只在启动时创建并保持常驻，运行阶段不使用可增长集合、临时字符串、闭包或其他堆对象；分配路径在冻结后显式拒绝。该适配器支持本项目任务子集，不是通用 MoonBit 运行时。

## 五、差异化、独立工作与来源

本轮对照了 [MoonBit OS 提案](https://github.com/moonbitlang/core/issues/3322) 及其指向的 [一多 OS 当前说明](https://github.com/liaoran123/yiduo/blob/main/README.md)。后者当前侧重 Wasm/WASI、WIT 组件组合与运行时编排。本项目交付 Cortex-M3 裸机异常执行、有界固定资源、优先级继承和 ISR 消息，不宣称首个 MoonBit OS，也不以历史提案代替对方当前状态。

与作业车间排程 moonbitJobShop、网络演算 moon-netcalculus 的对象与运行模型不同。调度、锁继承和环形队列本身是成熟方法；本项目独立价值是 MoonBit 核心与目标架构执行端口、明确内存约束和可复查的行为证据。没有复制或包装 FreeRTOS 内核。公开检索不能保证覆盖所有参赛作品，因此不作“绝无重复”承诺。完整对照见 [ECOSYSTEM.md](ECOSYSTEM.md)。

项目采用 AI 辅助开发；算法与硬件机制按公开定义独立实现，工具链、官方 ABI 头、QEMU 和 libgcc 归属见 [THIRD_PARTY.md](../THIRD_PARTY.md)。编译器生成 C 不计为原创算法行数。

## 六、可复现运行结果

```sh
python scripts/rtos.py --scenario 1
python scripts/rtos.py --scenario 2
python scripts/rtos.py --scenario 3
python scripts/rtos.py --scenario 4
python scripts/rtos.py --scenario 5
python scripts/rtos.py --fault stack
python scripts/rtos.py --fault allocation
```

| 场景 | 核查结果 |
|---|---|
| 抢占与同级轮转 | 高任务在 tick 5 恢复；三个忙任务的 R4–R11 和局部值检查通过，46 次任务身份切换 |
| 优先级反转 | 低任务继承优先级后于 tick 5 解锁，高任务同 tick 获锁；随后低任务恢复基础优先级 |
| 消息流水线 | 两队列串联三条业务任务，20 条消息顺序及处理值逐项核对，140 次任务断言通过 |
| 超时竞争 | 信号量超时、同 tick 中断令牌、满队列发送超时及接收超时后消息保留均通过 |
| 压力 | 150,010 tick、150,012 次任务身份切换，寄存器/栈检查与任务完成检查通过 |
| 负例 | 栈损坏触发 PANIC 72；运行期分配触发 PANIC 81，均非零退出且被测试脚本识别为预期拒绝 |

五组正例均实际从复位执行并返回 `RTOS_PASS`、退出码 0。19 次启动分配使用 1,488 字节，启动后次数不变；总 RAM 还包含固定 64 KiB 任务栈、64 KiB 启动 arena 预留、64 KiB trace 和其他数据，不能把 1,488 字节宣传为内核总内存。

16 条 MoonBit 测试包含 8 条原分析器测试与 8 条新 RTOS 测试；新增覆盖 4,096 次 FIFO 混合操作参考核对、继承链、等待环、时钟回绕、退出清理和容量边界。另有 48 组分析器独立模型核对。公共 CI 在 JS/Wasm/Wasm-GC/native 四后端运行，并独立重新编译执行全部裸机场景。基线运行链接、原始 UART、工具版本和 ELF SHA256 见 [VALIDATION.md](VALIDATION.md)。

## 七、实用边界与运行成本

当前平台为单核 Cortex-M3/QEMU MPS2 AN385，无 FPU/MPU，任务为特权模式。任务栈固定 4 KiB，端口只在启动时创建任务；核心槽复用不等于通用运行期创建任务。调度采用固定容量扫描；没有实际板上最坏执行时间和中断延迟证明。

栈哨兵在切换时检测，不能替代内存隔离；固定 trace 内部最多 4,096 条、导出前 256 条，另记录丢弃数，压力结果不冒称全量 trace。QEMU `icount` 加速推进虚拟时间，不作为实体 MCU 性能或墙钟耐久测试。

未提供实体板、通用驱动、文件系统、网络、动态堆、外部中断嵌套验证、硬实时保证、安全认证或生产部署。旧离线分析 API 在根包兼容保留，但没有将其理想模型响应界当成新内核的实测 WCET。

## 八、公开交付与比赛要求对应

沿用原仓库、保留 0.3.0 历史，以同一作品实质更新申报；核心、端口和样例不拆分成多个参赛项目。原有 12 条提交及本轮新增均保留真实时间和文件变化，仓库总数已超过 10；具体公开计数见 [提交历史](https://github.com/btlqql/moon-deadline/commits/main/)。不以空提交、改时间或数量替代贡献质量。

官方十一月页面要求 MoonBit 为主、公开开发记录、README/示例/必要测试、本期实质新增、合规开源和 AI 可解释，本次证据对应见 [REVIEW.md](REVIEW.md)。官网与本项目初审回执的适用范围分别记录；回执允许在 2026-11-30 前修改报名信息。

MoonCakes 交付可复用核心，GitHub 交付完整固件、端口、构建脚本、MD 申报书和运行证据。包发布与源码公开不自动修改比赛报名表，也不代表已重新通过初审。若评委要求实体开发板运行，该条件当前未满足；本次材料如实提供 QEMU 目标架构执行证据。