Translation pending. This page is currently available in Chinese.
CMSIS-RTOS2 第三方 ABI 兼容层(personality)¶
实时子系统架构与微内核机制分工参见 A20OS 实时执行模型与系统架构。本文是 CMSIS-RTOS2 人格层实现、API 支持矩阵与静态裁剪参考。
CMSIS-RTOS2 是 Arm 定义的**独立第三方 ABI**(source-level:头文件 + 库 + 语义),不是 A20OS Native ABI 的一部分,也不是第三种 syscall ABI。A20OS 在 user/cmsis_rtos2/ 以用户态人格库实现它;Native ABI 只为“固定优先级 personality”增加了一小组通用调度原语(两个新 syscall + 两个既有接口的扩展),其中不包含任何 CMSIS 类型或 CMSIS 编号。
在 Native/MCU 后端下,CMSIS 线程不是“分时调度器上的一层线程库”:它们就是内核的 SCHED_FIFO 任务,具备固定优先级抢占、优先级继承和真正的 osKernelLock。时间粒度仍是内核 tick;具体保证与边界见下文“实时性模型”。
定位:第三方 ABI,不是 Native ABI¶
| Linux ABI / Native ABI | CMSIS-RTOS2 | |
|---|---|---|
| 归属 | A20OS 内核接口 | Arm 规范,A20OS 以人格库提供 |
| 形态 | syscall 编号 + 线格式 + 语义 | C 头文件 + 库 + 语义(source-level ABI) |
| 调用方式 | ecall/svc/int 陷入内核 |
普通函数调用,库内部再发起 syscall |
| 可移植性 | 预编译二进制可换内核 | 源码级可移植,必须链接实现 |
| 标准来源 | Linux / A20OS 自有规范 | Arm CMSIS 规范(事实标准,非 ISO) |
因此它**不能**被当作 Native ABI 的扩展章节;本文放在 docs/zh/rtos/,Native ABI 文档只保留那些通用调度原语的 ABI 定义。
实现 CMSIS-RTOS2 实际用到的 Native ABI 表面:
| Native ABI 项 | 类型 | 用途 |
|---|---|---|
thread_create 的 sched 追加字段 |
既有 syscall 的 E-APPEND 扩展 | 在 publish 前设置 CMSIS 优先级/策略 |
task_set_sched 的 A20_SCHED_DONATE / UNDONATE |
既有 syscall 的新 flags | 内核 RT 优先级继承 |
task_get_sched |
既有 syscall | osThreadGetPriority 读取有效优先级 |
sched_lock(0x0219) |
新 syscall | osKernelLock 的 per-task 调度器锁 |
task_self(0x021A) |
新 syscall | 初始线程安装自己的 handle,作为 PI 目标 |
这些原语是通用的:它们不依赖 cmsis_os2.h,也不进入 Native ABI 的 CMSIS 专属编号;未来其他 RTOS personality 可以复用同一组调度原语。
分层¶
应用(现有 CMSIS-RTOS2 源码,不修改)
│ osThreadNew / osSemaphoreAcquire / osTimerStart / ...
▼
user/cmsis_rtos2 ← 本文
│ 后端契约(os_impl.h):
│ thread / clock / alloc / kernel-lock / blocking-queue
▼
Linux ABI(pthread + futex) 或 Native ABI(thread/sched/futex/atomic/vm_alloc)
▼
A20OS 内核机制(调度、futex、VM、定时器)
对象语义(互斥锁归属与递归、信号量计数、队列、事件标志、内存池、软件定时器)全部在可移植核心里实现。后端只提供四类原语,因此换 ABI 不需要改任何 os*函数:
- 线程:创建/退出/join/detach/yield/睡眠/优先级/亲和性/调度器锁;
- 时钟:单调纳秒;
- 分配器;
- 阻塞队列:互斥 + 定时等待(对象状态就由它保护)。
API 覆盖¶
| 对象 | 接口 |
|---|---|
| Kernel | initialize/start/state/info/version、tick 与系统定时器时钟、lock/unlock/restore、suspend/resume、osDelay、osDelayUntil |
| Thread | create/exit/join/detach/terminate/suspend/resume、优先级、名称、状态、count/enumerate、亲和性、栈大小/剩余 |
| Thread flags | set/get/clear/wait(any/all/no-clear、超时) |
| Timer | once/periodic、start/stop/is-running/delete,回调在专用服务线程执行 |
| Mutex | 归属、递归、定时获取、删除 |
| Semaphore | 计数、上限、定时获取、get-count |
| Event flags | set/clear/get/wait(any/all/no-clear) |
| Message queue | 按 msg_prio 排序(数值大者先出,同优先级 FIFO)、阻塞 put/get、capacity/space/reset |
| Memory pool | 固定块、阻塞分配、双重释放检测 |
线程还提供 osThreadGetAffinity(Native 直接复用 task_get_sched 返回的内核有效亲和性掩码)和 osThreadGetStackSpace(对 Native 自有栈与满足 PTHREAD_STACK_MIN 的调用方栈做高水位扫描;初始线程和无栈元数据的 pthread 默认栈返回 0)。栈高水位在目标线程阻塞或结束后稳定,运行中查询是 best-effort。
osThreadSuspend/Resume 在 Native/MCU 后端是内核级跨线程操作:目标在下一次 syscall/IRQ 返回安全点停止,阻塞中的目标由唤醒路径直接发布 STOPPED;不是用户态 futex gate。osKernelSuspend 在单核 MCU 上通过调度器锁 + one-shot 定时器 + WFI 进入低功耗,返回实际睡眠 tick;SMP 和 hosted 后端返回 0,不进入低功耗。
控制块支持 cb_mem/cb_size 静态放置;线程支持 stack_mem/stack_size。库自有的小栈(<32 KiB)来自共享 a20_malloc 池,大栈使用独立页对齐区域并在 join/detach 时通过 vm_unmap 归还,避免把 MCU 的小堆切碎。
执行、抢占、tick、PI、osKernelLock 的完整语义在独立页面:
- 执行模型:线程→内核 RT 任务的映射、优先级表、publish 前设置、syscall/IRQ 返回点抢占、broadcast wake、tick、
osKernelLock、保证/不保证; - 同步与优先级继承:mutex/semaphore/event/queue/pool、
wait_owner链、内核捐赠/恢复、超时、已知边界; - 中断与 ISR 模型:为什么用户态不能直接执行 ISR、4.4 厂商 dispatcher、临界区、移植厂商 IRQ。
简表:
| 属性 | Native/MCU 后端 |
|---|---|
| 调度类 | SCHED_FIFO,CMSIS 优先级 1..55 直接等于内核 RT 优先级 |
| 挂起/恢复 | 内核 suspend_pending + 安全点 STOPPED;Native 跨线程 |
| 低功耗 | 单核 MCU 调度器锁 + WFI;SMP/hosted 返回 0 |
| 创建 | thread_create sched 字段在 publish 前应用 |
| 抢占 | syscall / IRQ 返回 safe point,不等 tick |
| 唤醒 | broadcast + RT 队列选最高 |
| PI | 内核 proc_sched_rt_donate/restore,人格层遍历 wait_owner 链 |
osKernelLock |
内核 per-task sched_lock_depth |
| tick | Hi3861 100 Hz / QEMU 1 kHz;OS_NATIVE_TICK_HZ 必须匹配 ARCH_TIMER_FREQ |
| RT 带宽 | hosted 95%/秒;MCU 构建关闭 |
POSIX 后端不在实时保证范围内。
裁剪¶
user/cmsis_rtos2/cmsis_rtos2.toml 是唯一事实来源,声明每个 profile 保留哪些对象族、需要哪些 Native syscall。tools/cmsis_trim.py 用同一份声明做三件事:
# 1. 生成特性头和 syscall 表子集
python3 tools/cmsis_trim.py emit --profile mcu --out build/trim-mcu
# 2. 校验内核 ELF:不得链接 profile 之外的 sys_a20_*,也不得缺少声明项
python3 tools/cmsis_trim.py check --profile mcu --elf build/kernel.elf
# 3. 查看 profile
python3 tools/cmsis_trim.py list --profile mcu
生成物:
cmsis_config.h:OS_CFG_*宏,决定哪些对象族进入库;syscall_table_<profile>.def:主表kernel/abi/native/syscall_table.def的子集。构建时用-DA20_NATIVE_SYSCALL_TABLE='"syscall_table_<profile>.def"'覆盖主表即可,调度器对未命中的编号本来就返回-NOT_SUPPORTED,不需要第二套分发器。
| Profile | 对象族 | syscall 数 |
|---|---|---|
full |
全部 | 主表全部 |
mcu |
thread、mutex、semaphore、timer、event flags、message queue、suspend/resume、idle、vm_unmap | 19 |
mcu-min |
thread、semaphore、timer(不含 join/terminate/priority 的最小集合) | 9 |
被裁掉的对象族仍保留入口(返回 osErrorResource),因此"链接兼容、镜像裁剪":
- 不对头文件分叉;
- 不会因为少一个对象族而让应用链接失败;
- 不会把未使用的内核 syscall 带进镜像。
在 riscv32imc/ilp32、-Os、-ffunction-sections(链接 GC 前)下测得库 text:full 12.5 KiB、mcu 11.8 KiB、mcu-min 10.6 KiB。
check 是裁剪的闭环:它读 ELF 的 sys_a20_* 符号集合,与 manifest 比较,多一个或少一个都失败。因此"镜像里只有声明的 syscall"由构建检查保证,而不是靠代码评审。
验证¶
make -C user/cmsis_rtos2 test # POSIX + Native 两个后端
make -C user/cmsis_rtos2 freestanding PROFILE=mcu-min CC_RISCV32=<prefix>
python3 -m unittest tools.tests.test_cmsis_trim # manifest/生成器/校验器
同一套行为用例跑两遍:
- POSIX 后端:pthread + condvar;
- Native 后端:后端本身(futex 队列、线程簿记、栈归属)运行在
tests/native_platform_host.c提供的宿主实现上,平台调用用 pthread 和 Linux futex 实现。
Native 运行结束会输出 osn-used:...。单元测试另外把src/native_platform_a20.c 里的 a20_* 调用集合与 mcu profile 的 syscall 清单逐项比对,因此"后端实际用到的 syscall"和"manifest 声明的 syscall"不会漂移。
用例覆盖线程与 join、信号量、递归互斥(4 个竞争者)、事件/线程标志、队列满/空/reset、内存池容量与双重释放、周期与单次软件定时器。宿主用例验证对象语义;优先级、PI、osKernelLock 的调度语义由 QEMU MCU 的 4.5 实验验证,因为宿主 pthread 不保证 RT 策略。
osThreadJoin 在 Native 后端使用线程控制块里的 exit_word(futex 唤醒)等待,而不是内核 task_wait:A20 的 wait4 模型描述的是进程子任务,兄弟线程不是可等待子任务。该决定删除了 task_wait 这个 syscall,manifest、生成的分发表和内核镜像随之一起缩小。
在 RV32 M 态镜像里运行¶
QEMU 板 qemu-virt-riscv32-mcu 与 Hi3861 使用同一条路径:
- 用户实验链接成 ET_DYN 静态 PIE,只允许
R_RISCV_RELATIVE; kernel/arch/riscv32/mcu/program.c校验并装载 ELF,登记a20_flat_space_t(text/stack),mret到 U-mode;ecall进入 M 态riscv_mcu_syscall(),按syscall_table_mcu.def(由本 manifest 生成)分发;- 每个线程首次运行
arch_flat_program_enter(),把自己的内核栈顶写入mscratch,从 U 态陷入时硬件栈切换回该内核栈; - 实验输出写入栈上的 run record,由内核 launcher 排空并打印,用户程序不需要非 CMSIS 的控制台 API。
实验镜像、4.1–4.9 的预期输出、Hi3861 烧录和负向对照见 实验 4.1–4.9。4.4 的厂商 dispatcher 模型见 中断与 ISR 模型;厂商接口位于独立目录,不进入标准 CMSIS 库:
user/cmsis_rtos2/ 标准 CMSIS-RTOS2(不出现 hi_*/IoT*)
user/port/hi3861_hal/ 厂商扩展(hi_irq_* / IoTGpio* / IoTPwm*)
kernel/arch/riscv32/mcu/vendor_hi.c
厂商 syscall 区间 0x7F00..,不进标准分发表
验收¶
# 宿主对象语义(POSIX + Native 后端)
make -C user/cmsis_rtos2 test
# RV32 M 态 4.1–4.9
tools/a20 test qemu-riscv32-mcu
# 裁剪闭环
python3 tools/cmsis_trim.py check --profile mcu --elf <kernel.elf>
调度语义的预期输出与失败语义见 实验 4.1–4.9。
Hi3861 构建已编入同一套 flat-program 基础设施与 syscall 子集;实验镜像默认不在实板启动,确认 U-mode 后用tools/a20 package hi3861 -- HI3861_LITEOS_DEMO=1 构建、用同样的 make 参数烧录即可。烧录只写 kernel A,不带参数重新构建会回到纯 shell 镜像。