# mkrtos-lite

**Repository Path**: IsYourGod/mkrtos-lite

## Basic Information

- **Project Name**: mkrtos-lite
- **Description**: MKRTOS-Lite 是一个面向 ARM Cortex-M/A/RISC-V 系列 MCU/MPU的轻量级实时操作系统。它提供 POSIX 兼容的多线程编程接口、文件系统、设备驱动框架和 OTA 固件升级能力，支持多进程（MPU保护），适用于对稳定性、安全性要求较高的工业控制、物联网等嵌入式场景。
- **Primary Language**: C
- **License**: GPL-2.0
- **Default Branch**: master
- **Homepage**: http://www.atshining.com
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 1
- **Created**: 2026-06-12
- **Last Updated**: 2026-06-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MKRTOS-Lite

> MKRTOS-Lite 轻量级实时操作系统（RTOS）

[![License](https://img.shields.io/badge/license-GPL%20v2-blue.svg)](LICENSE)
[![Build](https://img.shields.io/badge/build-CMake%2BKconfig-orange.svg)]()

## 项目简介

MKRTOS-Lite 是一个面向 ARM Cortex-M/A/RISC-V 系列 MCU/MPU的轻量级实时操作系统。它提供 POSIX 兼容的多线程编程接口、文件系统、设备驱动框架和 OTA 固件升级能力，支持多进程（MPU保护），适用于对稳定性、安全性要求较高的工业控制、物联网等嵌入式场景。

### 核心特性

- **多任务调度**：基于优先级的位图调度器，支持同优先级时间片轮转，最大 32 个优先级
- **丰富的同步原语**：互斥锁（支持优先级继承、递归/错误检查类型）、信号量、消息队列、条件变量、读写锁
- **POSIX 线程**：用户态 pthread 库，支持 create/join/detach/cancel/cleanup/TLS/barrier 等
- **高精度定时器**：64 位纳秒精度软件定时器，支持周期模式和 tickless 空闲
- **虚拟文件系统 (VFS)**：支持 devfs、ramfs、LittleFS 和 AppFS（面向 NOR Flash 的 XIP 文件系统）
- **设备驱动框架**：块设备、字符设备、GPIO、SPI、I2C、显示、输入子系统，链表 mutex 保护
- **两级启动引导**：boot_sel (4KB) + bootstrap (A/B 双槽 12KB)，支持安全 OTA 升级
- **固件升级**：A/B 分区交替升级，三级恢复策略（kernel_bak → kernel_golden → UART XMODEM）
- **MPU 内存保护**：基于 ARMv7-M MPU 的任务隔离，MPU 感知的内存分配器
- **共享内存**：POSIX shm_open/shm_unlink 跨进程共享内存
- **命名同步对象**：跨进程的命名互斥锁、信号量、消息队列、条件变量、读写锁
- **内核日志**：异步环形缓冲区日志，支持写入 SPI Flash 持久化
- **工作队列**：延迟/异步工作项执行，支持 ISR 安全提交
- **交互式 Shell**：支持 `ps`/`top` 等命令


## 软件架构

```
┌──────────────────────────────────────────────────┐
│                    用户空间                        │
│  ┌──────────┐ ┌──────────┐ ┌──────────────────┐  │
│  │  App A   │ │  App B   │ │  test.elf (PIE)  │  │
│  │ (XIP)   │ │  (动态)  │ │  (pthread/libc)  │  │
│  └──────────┘ └──────────┘ └──────────────────┘  │
│  ┌──────────────────────────────────────────────┐ │
│  │  libc.a (musl: string/ctype/stdlib/math/     │ │
│  │  malloc(TLSF)/stdio/pthread/syscall)         │ │
│  └──────────────────────────────────────────────┘ │
├──────────────────── SVC #128 ────────────────────┤
│                    内核空间                        │
│  ┌─────────┐ ┌─────────┐ ┌────────────────────┐  │
│  │ syscall │ │  VFS    │ │ device drivers     │  │
│  │ dispatch│ │ devfs   │ │ blkdev/chardev     │  │
│  │ (72+)   │ │ ramfs   │ │ GPIO/SPI/I2C       │  │
│  │         │ │ littlefs│ │ disp/input/console │  │
│  │         │ │ appfs   │ │ uart/rtc/flash     │  │
│  └─────────┘ └─────────┘ └────────────────────┘  │
│  ┌──────────────────────────────────────────────┐ │
│  │  scheduler (prio bitmap + RR)                │ │
│  │  thread / task / mutex(PI) / sem / mq       │ │
│  │  condvar / rwlock / timer(ns) / workqueue   │ │
│  │  spinlock / cpulock / irq / kmem / shm      │ │
│  └──────────────────────────────────────────────┘ │
├────────────────── Hardware ──────────────────────┤
│  ARM Cortex-M3/M4/M33 (MPU / SysTick / NVIC)     │
└──────────────────────────────────────────────────┘
```

## 目录结构

```
mkrtos-lite/
├── mkrtos_boot/        # 两级启动引导 (boot_sel + bootstrap A/B)
│   ├── src/            # boot_sel.c, upgrade_boot.c, recovery.c
│   ├── inc/            # boot_info, upgrade_flags 公共头文件
│   └── bsp/            # STM32F205RFT6 BSP (启动/时钟/Flash写入/SPI读取)
├── mkrtos_knl/         # 内核
│   ├── src/knl/        # 内核核心 (调度/线程/任务/同步原语/驱动框架等 40+ 文件)
│   ├── src/fs/         # 文件系统 (VFS/devfs/ramfs/LittleFS/AppFS)
│   ├── src/drv/        # 设备驱动 (UART/SPI Flash/GPIO/I2C/触摸屏/OLED/Ymodem)
│   ├── src/lib/        # 内核库 (string/ctype/queue/xprintf)
│   ├── arch/cortex-m/  # Cortex-M 架构移植 (PendSV/SVC/SysTick/MPU)
│   ├── inc/knl/        # 内核公共 API 头文件 (46 个)
│   ├── inc/fs/         # VFS 头文件
│   └── test/           # 内核测试套件 (32 个测试模块)
├── mkrtos_user/        # 用户空间运行时
│   ├── src/crt/        # C 运行时 (start.S/reloc.c/errno.c)
│   ├── src/pthread/    # POSIX 线程库 (create/join/mutex/cond/rwlock/key/cancel/barrier)
│   ├── src/malloc/     # TLSF 内存分配器
│   ├── src/string/     # 字符串库 (musl, 48 个函数)
│   ├── src/math/       # 数学库 (musl, ~150 个函数)
│   └── test/           # 用户态测试套件 (22 个测试模块)
├── mkrtos_bsp/         # 芯片支持包 (STM32F10x/F2xx/F4xx 标准外设库)
├── mkrtos_tool/        # 宿主机工具
│   ├── appfs_pack/     # AppFS 镜像打包工具
│   ├── kconfig/        # Kconfig 配置系统 (源自 Zephyr)
│   ├── partition_gen/  # 分区表代码生成器
│   └── upgrade_pack/   # OTA 升级包生成工具
├── mkrtos_cmake/       # CMake 构建模块 (源自 Zephyr)
├── mkrtos_configs/     # 板级配置文件 (defconfig + 分区表 CSV)
├── mkrtos_img/         # 预构建镜像和打包脚本
├── docs/               # 设计文档 (11 篇)
├── CMakeLists.txt      # 顶层构建文件
├── Kconfig             # 顶层配置入口
└── LICENSE             # GPL v2
```

## 快速开始

### 环境要求

- **操作系统**：Ubuntu 18.04+ (推荐)
- **交叉编译器**：`gcc-arm-none-eabi-5_4-2016q3` 或更新版本
- **CMake** >= 3.13
- **Ninja** (推荐构建工具)
- **Python** >= 3.6 (Kconfig 工具链)
- **QEMU** >= 10.0 (模拟运行，支持 `netduino2` 机器)[定制版下载](https://gitee.com/IsYourGod/mkrtos-lite)


### 配置交叉编译器

```bash
export TOOLCHAIN=/path/to/gcc-arm-none-eabi/bin/
export TOOLCHAIN_LIB=/path/to/gcc-arm-none-eabi/lib/gcc/arm-none-eabi/5.4.1/armv7-m
export CROSS_COMPILE_NAME=arm-none-eabi-
```

### 构建

```bash
mkrtos_script/build_netduino2.sh
```

构建产物位于 `build/output/`：
- `kernel.img` — 完整 Flash 镜像 (boot_sel + bootstrap ×2 + kernel + appfs)
- `mkrtos.bin` — 内核二进制
- `appfs.img` — AppFS 文件系统镜像
- `test.bin` — 用户态测试应用

### QEMU 模拟运行

```bash
mkrtos_script/run_m3.sh
```

### GDB 调试

```bash
mkrtos_script/debug_m3.sh
```

## 配置系统

项目使用 Kconfig 配置系统 (源自 Zephyr 项目)，支持：

```bash
# 终端菜单配置
ninja menuconfig

# 图形界面配置
ninja guiconfig

# 生成默认配置
ninja netduino2_defconfig
```

### 主要配置项

| 类别 | 配置项 | 默认值 | 说明 |
|------|--------|--------|------|
| 调度 | `SYS_SCHE_HZ` | 1000 | 系统 tick 频率 |
| 调度 | `PRIO_MAX` | 32 | 最大优先级数 |
| 调度 | `TIME_SLICE_TICKS` | 10 | 时间片长度 (tick) |
| 同步 | `MUTEX` / `SEMAPHORE` / `MESSAGE_QUEUE` | y | 同步原语开关 |
| 同步 | `CONDVAR` / `RWLOCK` | y | 条件变量/读写锁开关 |
| 文件系统 | `VFS` / `VFS_DEVFS` / `VFS_RAMFS` | y | VFS 子系统 |
| 文件系统 | `VFS_LITTLEFS` / `VFS_APPFS` | n | 持久化文件系统 |
| 驱动 | `SPI` / `I2C` / `GPIO` / `DISP` / `INPUT` | n | 外设子系统开关 |
| 升级 | `UPGRADE` | n | OTA 固件升级 |
| Shell | `SHELL` | y | 命令行 Shell |
| 测试 | `KNL_TEST` | y | 内核测试套件 |

## 编程接口

### 线程

```c
// 创建并运行线程
thread_t *th = thread_create_run(4096, 10, my_entry, arg);

// 修改优先级
thread_change_self_prio(15);

// 获取当前线程
thread_t *cur = thread_get_current();
```

### 互斥锁 (支持优先级继承)

```c
mutex_t *mtx = mutex_create();
mutex_lock(mtx);
// 临界区
mutex_unlock(mtx);
mutex_destroy(mtx);
```

### 信号量

```c
semaphore_t *sem = sem_create(0, 10);  // 初值 0，最大 10
sem_post(sem);                          // 释放
sem_wait_timeout(sem, 1000);            // 超时等待 1000ms
```

### 消息队列

```c
message_queue_t *mq = mq_create(16, sizeof(my_msg_t));
mq_send(mq, &msg);
mq_recv(mq, &buf);
```

### 高精度定时器

```c
timer_t timer;
timer_init(&timer, my_callback, arg);
timer_start(&timer, 1000000);           // 1ms = 1,000,000ns
timer_start_periodic(&timer, 10000000); // 周期 10ms
```

### 文件 I/O (POSIX 风格)

```c
int fd = open("/dev/console", O_RDWR);
write(fd, "hello\n", 6);
close(fd);

// 文件系统
int fd = open("/ram/test.txt", O_CREAT | O_RDWR);
write(fd, data, len);
lseek(fd, 0, SEEK_SET);
read(fd, buf, len);
```

### pthread (用户态)

```c
pthread_t thread;
pthread_create(&thread, NULL, thread_func, arg);
pthread_join(thread, NULL);

pthread_mutex_t mtx = PTHREAD_MUTEX_INITIALIZER;
pthread_mutex_lock(&mtx);
pthread_mutex_unlock(&mtx);

pthread_cond_t cond = PTHREAD_COND_INITIALIZER;
pthread_cond_wait(&cond, &mtx);
pthread_cond_signal(&cond);
```

### 共享内存

```c
int fd = shm_open("my_shm", 4096);
void *ptr = shm_getptr(fd);
size_t size = shm_getsize(fd);
```

## 系统调用

内核提供 72+ 个系统调用 (通过 SVC #128)：

| 类别 | 系统调用 |
|------|----------|
| 文件 I/O | open, close, read, write, lseek, ioctl, stat, fstat, mkdir, rmdir, unlink, rename |
| 线程 | thread_create, thread_exit, thread_join, thread_detach, thread_self, thread_cancel, thread_set_prio |
| 同步 | mutex_create/lock/trylock/unlock/destroy, sem_create/wait/post/destroy, condvar_create/wait/signal/broadcast, rwlock_create/read_lock/write_lock/unlock |
| IPC | sync_create_named, sync_open_named, mq_send/recv, shm_open/unlink |
| 时间 | sleep_ns, clock_gettime/settime, timer_create/settime/gettime/delete |
| 其他 | poll, klog_write, reboot, TLS 操作 |

## 测试

项目包含两层测试体系：

### 内核测试 (`mkrtos_knl/test/`)

覆盖 32 个模块：线程、互斥锁、信号量、消息队列、条件变量、读写锁、定时器、POSIX 定时器、等待队列、工作队列、内存分配器 (mm_chain/mpu_mem)、字符设备、块设备、VFS、LittleFS、AppFS、内核日志、GPIO、SPI、I2C、显示、输入、RTC、共享内存、poll、Ymodem、触摸绘制、升级、mkfs。

### 用户态测试 (`mkrtos_user/test/`)

22 个测试套件覆盖：pthread 生命周期、文件系统 syscall、设备驱动 syscall、边界条件、同步原语、条件变量、读写锁、poll、RTC、POSIX 定时器、共享内存、libc 字符串/字符分类/标准库/内存分配/格式化输出/数学函数。

## 设计文档

| 文档 | 内容 |
|------|------|
| [vfs.md](docs/vfs.md) | VFS 设计：挂载架构、路径解析、文件描述符表 |
| [appfs.md](docs/appfs.md) | AppFS：面向 NOR Flash 的平面文件系统，支持 XIP |
| [upgrade_design.md](docs/upgrade_design.md) | OTA 升级：A/B 分区交替、三级恢复策略 |
| [pthread-design.md](docs/pthread-design.md) | pthread 实现：三层架构、TLS、取消机制 |
| [timer.md](docs/timer.md) | 高精度定时器：纳秒精度、周期模式、tickless 集成 |
| [message_queue.md](docs/message_queue.md) | 消息队列：环形 FIFO、零头部开销 |
| [wait.md](docs/wait.md) | 等待队列：超时、条件等待、异常唤醒 |
| [workqueue.md](docs/workqueue.md) | 工作队列：延迟执行、ISR 安全提交 |
| [blkdev_framework_plan.md](docs/blkdev_framework_plan.md) | 块设备框架：统一接口、分区支持 |
| [mpu_mem.md](docs/mpu_mem.md) | MPU 内存分配器：子区域禁用、区域数优先 |
| [no_hz.md](docs/no_hz.md) | Tickless 空闲：动态 SysTick、低功耗设计 |

## 目标
- 短期目标：Cortex-M系列处理器
- 长期目标：支持更多处理器架构，如：Cortex-A,RISC-V

## 技术栈与致谢

MKRTOS-Lite 使用了以下开源项目：

- **Kconfig 配置系统**：源自 [Zephyr RTOS](https://github.com/zephyrproject-rtos/zephyr)
- **CMake 构建模块**：源自 [Zephyr RTOS](https://github.com/zephyrproject-rtos/zephyr)
- **musl libc**：部分 C 库函数源自 [musl](https://musl.libc.org/)
- **LittleFS**：嵌入式文件系统，源自 [littlefs](https://github.com/littlefs-project/littlefs)
- **CmBacktrace**：Cortex-M 故障诊断库，源自 [CmBacktrace](https://github.com/armink/CmBacktrace)
- **Letter Shell**：嵌入式命令行，源自 [letter-shell](https://github.com/NevermindZZT/letter-shell)
- **TLSF**：实时内存分配器

## 许可证

本项目采用 [GNU General Public License v2](LICENSE) 许可证。

## 交流与贡献

- QQ 群：419833232
- 欢迎提交 Pull Request 和 Issue
- 贡献者需将代码授权给项目使用