# SuperOS

**Repository Path**: supowang/superos

## Basic Information

- **Project Name**: SuperOS
- **Description**: 参考主流RTOS的实现思想，从0-1构建的RTOS，供自己学习
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2026-04-05
- **Last Updated**: 2026-04-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# SuperOS

**SuperOS** 是一个原创的轻量级实时操作系统 (RTOS) 内核，面向资源受限的嵌入式系统设计。

## 特性

- **抢占式多任务调度**：基于优先级位图的 O(1) 调度算法，支持同优先级时间片轮转
- **任务管理**：创建、删除、挂起/恢复（嵌套计数）、优先级变更、时间片、任务信息查询
- **同步机制**：
  - 计数/二值信号量（含 post\_all 广播、set 直接设置、pend\_abort）
  - 互斥锁（优先级继承链传递 + 天花板协议 + 递归锁 + MutexGrp 多锁管理 + 直接移交）
  - 事件标志组（AND/OR 等待 + 自动清除）
  - 条件变量（原子释放锁 + 等待，防 lost-wakeup）
- **通信机制**：
  - 消息队列（FIFO/LIFO、阻塞发送/接收、peek）
  - 邮箱（单指针消息、覆盖写入）
  - 管道（字节流、分段 memcpy 环形缓冲）
  - 流缓冲区（trigger\_level 触发唤醒）
  - 消息缓冲区（4 字节长度头 + 变长消息体）
- **任务通知**：轻量级直达任务通信（set-bits / increment / overwrite / set-if-empty）
- **工作队列**：即时/延迟提交、系统默认工作队列、drain 排空
- **多对象等待**：同时等待多个信号量/队列/邮箱/事件
- **任务内建信号量/消息队列**：每任务零开销同步/通信（含溢出保护）
- **任务寄存器 / TLS**：每任务私有存储槽位
- **软件定时器**：单次/周期，按绝对到期时间排序链表，独立定时器任务驱动
- **内存管理**：
  - 固定块内存池（O(1) 分配/释放、对齐校验、范围校验、double-free 检测）
  - TLSF 动态堆（O(1) 分配/释放、哨兵消除 NULL 分支、多池支持、realloc 主动分裂）
  - calloc 溢出检查、heap\_check 完整性校验
- **时间管理**：排序延时链表（O(1) tick 处理）、相对/绝对延时、ms/tick 转换、HMSM 延时
- **中断管理**：中断嵌套计数、ISR 安全检查、延迟调度
- **CPU 利用率统计**：空闲计数法全局 CPU 使用率 + 每任务 run\_cycles 统计
- **完整钩子系统**：idle / tick / task\_create / task\_delete / task\_switch / error / malloc\_fail / stack\_overflow
- **运行时栈溢出检测**：上下文切换时自动检测（栈底魔数 + SP 范围）+ 栈水位查询
- **内核对象调试跟踪**：全局对象注册表、按类型遍历、dump 输出
- **多架构支持**：ARM Cortex-M（M0/M0+/M3/M4/M7/M23/M33）× ARMCC6 + GCC、RISC-V（Bumblebee）、Linux 模拟

## 项目结构

```
SuperOS/
├── README.md                        # 项目说明
├── LICENSE                          # MIT 许可证
├── CMakeLists.txt                   # CMake 构建系统
├── kernel/                          # 内核源码
│   └── core/
│       ├── include/                 # 内核头文件 (29 个)
│       │   ├── spos.h               # 统一 API 头文件
│       │   ├── spos_types.h         # 基本类型、错误码、工具宏
│       │   ├── spos_config.h        # 内核默认配置（模块启用/裁剪）
│       │   ├── spos_task.h          # 任务管理 (TCB、创建/删除/挂起/恢复)
│       │   ├── spos_sched.h         # 调度器 (就绪表、位图、调度锁)
│       │   ├── spos_sem.h           # 计数/二值信号量
│       │   ├── spos_mutex.h         # 互斥锁 (优先级继承+天花板+MutexGrp)
│       │   ├── spos_event.h         # 事件标志组 (AND/OR/CLEAR)
│       │   ├── spos_queue.h         # 消息队列 (FIFO/LIFO)
│       │   ├── spos_mbox.h          # 邮箱 (单指针消息)
│       │   ├── spos_timer.h         # 软件定时器 (单次/周期)
│       │   ├── spos_time.h          # 时间管理 (延时/tick)
│       │   ├── spos_mem.h           # 内存管理 (mempool + TLSF 堆)
│       │   ├── spos_pipe.h          # 管道 (字节流)
│       │   ├── spos_stream_buf.h    # 流缓冲区 (trigger_level)
│       │   ├── spos_msg_buf.h       # 消息缓冲区 (长度头+消息体)
│       │   ├── spos_notify.h        # 任务通知
│       │   ├── spos_condvar.h       # 条件变量
│       │   ├── spos_workq.h         # 工作队列
│       │   ├── spos_pend_multi.h    # 多对象等待
│       │   ├── spos_list.h          # 侵入式双向链表
│       │   ├── spos_ringbuf.h       # 环形缓冲区 (内核内部)
│       │   ├── spos_port.h          # 架构移植接口
│       │   ├── spos_cpu.h           # CPU 抽象层
│       │   ├── spos_int.h           # 中断管理
│       │   ├── spos_hook.h          # 钩子系统
│       │   ├── spos_idle.h          # 空闲任务
│       │   ├── spos_stat.h          # 统计任务
│       │   ├── spos_kdbg.h          # 内核对象调试跟踪
│       │   └── spos_atomic.h        # 原子操作
│       └── *.c                      # 25 个内核模块实现
├── arch/                            # 架构适配层
│   ├── arm/
│   │   ├── arm-v6m/                 # Cortex-M0/M0+
│   │   │   ├── common/include/      # port_def.h, port_cpu.h
│   │   │   ├── cortex-m0/
│   │   │   │   ├── armcc/           # port_c.c, port_s.s, port_cpu.c
│   │   │   │   └── gcc/            # port_c.c, port_s.S, port_cpu.c
│   │   │   └── cortex-m0plus/
│   │   │       ├── armcc/
│   │   │       └── gcc/
│   │   ├── arm-v7m/                 # Cortex-M3/M4/M7
│   │   │   ├── common/include/
│   │   │   ├── cortex-m3/{armcc,gcc}/
│   │   │   ├── cortex-m4/{armcc,gcc}/
│   │   │   └── cortex-m7/{armcc,gcc}/
│   │   └── arm-v8m/                 # Cortex-M23/M33
│   │       ├── common/include/
│   │       ├── cortex-m23/{armcc,gcc}/
│   │       └── cortex-m33/{armcc,gcc}/
│   ├── risc-v/
│   │   └── rv32/
│   │       ├── common/include/
│   │       ├── bumblebee/gcc/
│   │       └── rv32imac/gcc/
│   └── linux/                       # Linux 模拟层
│       ├── common/include/          # port_def.h, port_cpu.h
│       └── x86_64/gcc/             # port_c.c, port_cpu.c
├── test/                            # 测试套件 (28 个模块)
│   ├── test_runner.c                # 测试主入口
│   ├── test_utils.c/h               # 测试辅助设施
│   ├── greatest.h                   # 测试框架
│   └── suites/                      # 28 个测试模块
├── examples/                        # 示例工程
│   └── hello_world.c
├── board/                           # 板级工程
│   └── SuperOS_EVB_STM32L562RET6/
│       ├── BSP/                     # 板级驱动 (CubeMX 生成)
│       ├── KEIL/                    # Keil 工程 (hello_world + test)
│       ├── GCC/                     # GCC/STM32CubeIDE 工程
│       └── SPOS_CONFIG/             # 芯片侧 spos_config.h
└── docs/                            # 文档
    ├── SuperOS_Kernel_Analysis.md   # 内核源码剖析 (30 章 + 完整源码附录)
    ├── SuperOS_API_Reference.md     # API 参考指南 (Doxygen 风格)
    ├── SuperOS_Porting_Guide_Keil.md  # Keil/ARMCC6 移植指南
    └── SuperOS_Porting_Guide_GCC.md   # GCC/arm-none-eabi 移植指南
```

## 支持的架构

| 架构 | 芯片系列 | 编译器 | 状态 |
|------|----------|--------|------|
| ARM Cortex-M0 | STM32F0, STM32G0 | ARMCC6, GCC | ✅ |
| ARM Cortex-M0+ | STM32L0 | ARMCC6, GCC | ✅ |
| ARM Cortex-M3 | STM32F1, STM32F2, STM32L1 | ARMCC6, GCC | ✅ |
| ARM Cortex-M4F | STM32F3, STM32F4, STM32L4, STM32G4 | ARMCC6, GCC | ✅ |
| ARM Cortex-M7F | STM32F7, STM32H7 | ARMCC6, GCC | ✅ |
| ARM Cortex-M23 | STM32L5 (Baseline TrustZone) | ARMCC6, GCC | ✅ |
| ARM Cortex-M33 | STM32U5, STM32H5, STM32L5 (Mainline TrustZone) | ARMCC6, GCC | ✅ |
| RISC-V Bumblebee | GD32VF103 | GCC | ✅ |
| Linux 模拟 | x86\_64 / ARM64 | GCC / Clang | ✅ |

## 快速开始

### Linux 模拟环境

```bash
mkdir build && cd build
cmake -DSPOS_ARCH=linux ..
make
./superos_test      # 28 个测试套件全部通过
```

### ARM Cortex-M33 (Keil MDK)

参见 [Keil 移植指南](docs/SuperOS_Porting_Guide_Keil.md)。

```
打开 board/SuperOS_EVB_STM32L562RET6/KEIL/hello_world/SuperOS_EVB_STM32L562RET6.uvprojx
Build All → Download → 串口 115200 查看输出
```

### ARM Cortex-M33 (GCC)

参见 [GCC 移植指南](docs/SuperOS_Porting_Guide_GCC.md)。

```bash
mkdir build && cd build
cmake -DCMAKE_TOOLCHAIN_FILE=../cmake/arm-none-eabi.cmake \
      -DSPOS_ARCH=arm-v8m-m33 ..
make
```

### ARM Cortex-M4F (GCC)

```bash
mkdir build && cd build
cmake -DCMAKE_TOOLCHAIN_FILE=../cmake/arm-none-eabi.cmake \
      -DSPOS_ARCH=arm-v7m-m4 ..
make
```

### RISC-V Bumblebee (GD32VF103)

```bash
mkdir build && cd build
cmake -DCMAKE_TOOLCHAIN_FILE=../cmake/riscv-none-elf.cmake \
      -DSPOS_ARCH=riscv-bumblebee ..
make
```

## 内核 API 概览

详见 [SuperOS API Reference](docs/SuperOS_API_Reference.md)。

### 任务管理 (`spos_task.h`)

| API | 说明 |
|-----|------|
| `spos_task_create()` | 创建任务 |
| `spos_task_delete()` | 删除任务（自动释放持有的互斥锁） |
| `spos_task_suspend()` / `resume()` | 挂起/恢复（支持嵌套） |
| `spos_task_set_prio()` | 动态修改优先级 |
| `spos_task_yield()` | 主动让出 CPU |
| `spos_task_abort_delay()` | 取消延时（提前唤醒） |
| `spos_task_get_info()` | 获取完整任务信息 |
| `spos_task_stack_watermark()` | 栈使用高水位 |
| `spos_task_sem_pend()` / `post()` | 任务内建信号量 |
| `spos_task_q_pend()` / `post()` | 任务内建消息队列 |

### 同步原语

| 模块 | 创建 | 获取 | 释放 | 其他 |
|------|------|------|------|------|
| 信号量 | `sem_create` | `sem_pend` | `sem_post` | `post_all`, `set`, `pend_abort_all` |
| 互斥锁 | `mutex_create` | `mutex_lock` | `mutex_unlock` | 优先级继承, 天花板, 递归 |
| 事件 | `event_create` | `event_pend` | `event_post` | AND/OR/CLEAR, `pend_abort` |
| 条件变量 | `condvar_create` | `condvar_wait` | `condvar_signal` | `broadcast` |

### 通信原语

| 模块 | 发送 | 接收 | 特性 |
|------|------|------|------|
| 消息队列 | `queue_send` / `send_front` | `queue_recv` | FIFO/LIFO, `peek`, `flush` |
| 邮箱 | `mbox_post` / `post_overwrite` | `mbox_pend` | 单指针消息 |
| 管道 | `pipe_write` | `pipe_read` | 字节流, 分段 memcpy |
| 流缓冲区 | `stream_buf_send` | `stream_buf_recv` | trigger\_level |
| 消息缓冲区 | `msg_buf_send` | `msg_buf_recv` | 变长消息 |

### 内存管理 (`spos_mem.h`)

| API | 说明 |
|-----|------|
| `spos_mempool_create()` / `alloc()` / `free()` | 固定块内存池 |
| `spos_heap_alloc()` / `free()` / `realloc()` / `calloc()` | TLSF 动态堆 |
| `spos_heap_pool_add()` / `pool_rmv()` | 多内存池管理 |
| `spos_heap_check()` | 堆完整性校验 |
| `spos_malloc()` / `spos_free()` | 全局堆快捷接口 |

## 质量保证

### 测试

- **28 个测试套件**，覆盖所有内核模块的核心 API 和边界条件
- 支持 Linux 模拟环境运行，适合 CI

### 对标优化

| 优化方向 | 关键改进 |
|----------|---------| 
| 内存管理 | mempool 对齐/范围校验/double-free 检测 |
| 时间管理 | 排序延时链表 O(1) tick + ringbuf 分段 memcpy |
| 同步原语 | pipe/event/condvar pend 字段清理 + notify 去重 |
| 互斥锁 | MutexGrp 多锁优先级恢复 + sem\_set 安全检查 |
| 任务管理 | task\_delete 释放锁 + mutex handoff 消除竞态 + sem\_post\_all |

## 设计理念

- **原创代码**：所有内核代码均为原创设计
- **功能全面**：覆盖主流 RTOS 的全部内核功能（25+ 内核模块）
- **可移植性**：通过 `spos_port.h` 清晰的移植层接口，轻松适配新架构
- **可配置性**：通过 `spos_config.h` 裁剪内核功能，适应不同资源约束
- **确定性**：O(1) 调度算法 + O(1) TLSF 堆分配，保证实时性
- **双编译器**：ARM 全系列同时支持 Keil ARMCC6 和 GCC
- **最小资源占用**：内核 ROM < 10KB, RAM < 1KB（最小配置）

## 功能清单

| 功能模块 | 特性 |
|----------|------|
| 抢占式调度 | O(1) 位图调度 + 时间片轮转 |
| 信号量 | 计数/二值，优先级排序等待，广播释放 |
| 互斥锁 | 优先级继承 + 天花板协议 + 直接移交 + 递归锁 |
| 事件标志组 | 32 位 AND/OR 等待 + 自动清除 |
| 消息队列 | 固定大小 FIFO/LIFO + 双等待队列 |
| 邮箱 | 单指针消息传递 |
| 软件定时器 | 单次/周期，排序链表驱动 |
| 任务通知 | 5 种动作：置位/递增/覆写/条件写 |
| 流缓冲区 | 变长字节流 + trigger_level |
| 消息缓冲区 | 自动长度头 + 消息边界 |
| 多对象等待 | 同时等待多个内核对象 |
| 任务内建信号量 | 直达任务的轻量信号量 |
| 任务内建消息队列 | 直达任务的轻量消息 |
| 任务寄存器/TLS | 任务私有存储 |
| 条件变量 | 配合互斥锁，修复 lost-wakeup |
| 工作队列 | 即时提交 + 延迟提交 |
| 管道 | 有缓冲/无缓冲字节流 |
| 内存管理 | 固定块池 O(1) + TLSF 动态堆 O(1) |
| 内核对象调试 | 按类型全局链表 + 遍历 |
| 钩子系统 | 8 种回调点 |
| 栈溢出检测 | 栈底魔数 + SP 范围检查 |
| 原子操作 | 无锁整数 + 位操作 |
| CPU 统计 | 空闲计数法利用率统计 |

## 文档

| 文档 | 说明 |
|------|------|
| [SuperOS\_Kernel\_Analysis.md](docs/SuperOS_Kernel_Analysis.md) | 内核源码深度剖析（30 章 + 完整源码附录，13000+ 行） |
| [SuperOS\_API\_Reference.md](docs/SuperOS_API_Reference.md) | API 参考指南（Doxygen 风格，27 个模块） |
| [SuperOS\_Porting\_Guide\_Keil.md](docs/SuperOS_Porting_Guide_Keil.md) | Keil MDK / ARMCC6 移植指南 |
| [SuperOS\_Porting\_Guide\_GCC.md](docs/SuperOS_Porting_Guide_GCC.md) | GCC / arm-none-eabi-gcc 移植指南 |

## 许可证

MIT License - 详见 [LICENSE](LICENSE)