一句话结论：RT-Thread 的系统层设计，本质是用「优先级 + 阻塞 + 对象容器」把 CPU 与共享资源按截止时间分配出去。 它比 FreeRTOS 多了一套内核对象容器与自动初始化框架，让「模块注册」变成编译期行为，代价是初始化顺序必须显式设计。 线上故障最集中的三处：栈容量不足、中断里用了非 xxx_isr 的 API、拿信号量当互斥量导致优先级反转。管住这三处，系统稳定性解决八成。

这份文档解决什么

本文只覆盖 RT-Thread 系统层面：内核启动链路、线程与调度、IPC 选型、内存三方案、定时器、rtconfig.h 配置、FinSH / ulog 等系统组件、低功耗、健壮性设计与调试手段。 凡涉及具体外设的实现（SPI / I2C / UART / 定时器 / PIN 设备驱动、文件系统 DFS、网络协议栈的驱动适配）均归 BSP 与设备驱动文档，本文只在必要处说明「线程侧该如何与它协作」。

使用约定

• API 与宏以 RT-Thread 4.x / 5.x 为准，目标以 Cortex-M3/M4/M33 为主；RISC-V 与 M0/M0+ 的差异在对应小节单独标注。
• 代码示例只保留系统层逻辑，凡涉及具体寄存器与外设的部分统一写成 /* BSP 提供 */ 注释。
• 标 红线 的条目为强制约束，标 警惕 的为高频踩坑点，标 建议 的为经验推荐值。
• 文中出现的默认数值（栈大小、优先级、阈值）均以官方 rtconfig.h 模板与内核源码为参考；不同 BSP 与版本可能微调，落地前请以工程内的 rtconfig.h 与内核源码为准。
• 芯片参数、时钟频率、外设行为一律以官方 datasheet 与 RT-Thread 官方文档 / 源码为准。

1 · 系统架构与内核对象模型

这一章解决「系统切成几块、每块放什么、内核对象是怎么被管起来的」。RT-Thread 与 FreeRTOS 最大的结构性差异就在对象模型上，理解了它，后面的 list_sem / ps 为什么能列出所有对象就自然清楚了。

1.1 四层分层模型

RT-Thread 是类 UNIX 风格的分层 RTOS：内核提供线程、IPC、内存、定时器，组件层提供 FinSH / ulog / POSIX / 软件包，BSP 层提供设备驱动与 libcpu 移植。分层的核心目的与 FreeRTOS 一致——让内核源码保持零修改，业务与内核之间只通过 rtconfig.h 与 API 交互。

• ① 应用业务层：业务线程、状态机、消息处理。每个线程只做一类事，通过 IPC 交互，不直接读写别人的全局变量。
• ② 系统组件层：FinSH、ulog、POSIX、libc、软件包。它们运行在内核之上、与业务平级，靠自动初始化宏挂进系统。
• ③ 内核层：rt-thread/src 下的调度器、IPC、内存、定时器与对象容器。红线 不修改任何内核源文件，只通过 rtconfig.h 配置。
• ④ BSP / 驱动层：libcpu 移植（PendSV / SysTick / 上下文栈帧）、设备模型与外设驱动。本指南不涉及。

1.2 内核对象容器 rt_object

这是 RT-Thread 的标志性设计：所有内核对象（线程、信号量、互斥量、事件集、邮箱、消息队列、内存池、定时器、设备…）都从一个公共基类 struct rt_object 派生，并被挂进一张按类型分类的对象容器表（rt_object_container[]）。

struct rt_object {
    char       name[RT_NAME_MAX];   /* 对象名，调试与 FinSH 列出时用 */
    rt_uint8_t type;                /* 对象类型：Thread / Semaphore / Mutex / ... */
    rt_uint8_t flag;                /* 标志位：静态对象 / 动态对象 */
    rt_list_t  list;                /* 挂在容器链表上的节点 */
};
/* 派生方式：把 rt_object parent 作为第一个成员，即可安全强转 */
struct rt_thread {
    struct rt_object parent;        /* 必须是第一个成员 */
    /* ... 栈指针、优先级、状态、链表 ... */
};

1.3 与 FreeRTOS 的架构差异

如果团队里有 FreeRTOS 背景，下表能快速对齐心智模型。完整对照见附录 D。

1.4 线程划分原则

线程划分是最重要也最不可逆的一步。经验准则：线程不宜过多，每个线程单一职责，按时间特性而非按功能模块拆。

1. 先按时间特性切：硬周期（采样、控制）与突发（通信、按键）必须分开；周期不同就不是一个线程。
2. 再按功能独立性切：两个功能无共享状态、可独立测试，就可以分开。
3. 高优先级线程必须短：只做「取数据 → 判条件 → 投递消息 / 置事件」，耗时活交给低优先级线程。
4. 禁止一个大 while(1) 塞满所有业务：那等于把裸机超级循环搬进 RTOS，抢占优势全部失效。
5. 同优先级可合并：时间特性相同、逻辑耦合紧密的，合并比拆开更省栈、更少同步。
6. 一次性创建，运行期不删：见 3.1 与 3.6，这是量产项目的默认姿态。

1.5 优先级分档方法论

优先级的本质是截止时间（deadline）的紧急程度，不是功能的重要程度。日志很重要，但可以晚 100 ms 写，优先级就该低。

• 速率单调（Rate Monotonic, RM）：周期越短，优先级越高。一批纯周期线程的理论最优静态分配。
• 截止时间优先（Deadline Monotonic）：按「从触发到必须完成的时限」排序，比 RM 更通用，适合混合突发线程的场景。
• 留出空档：不要 0/1/2/3 连续排满，给每档之间留 2~3 级空位，方便后期插入新线程而不用整体重排。

警惕 时间片轮转不会给低优先级线程公平份额：只要高优先级线程一直就绪，低优先级线程就一直得不到运行（饿死）。因此高优先级线程里绝不能有忙等循环。

2 · 启动流程与自动初始化

RT-Thread 把「模块注册」做成了编译期行为：INIT_APP_EXPORT(fn) 一行就把函数挂进启动链。便利背后是硬约束——依赖关系必须由等级显式表达，顺序错了就是随机死机。

2.1 rtthread_startup 全链路

上电后，RT-Thread 通过 ARM 编译器的 $Sub$$main 机制，在用户 main() 之前插入 rtthread_startup()。完整链路如下：

int rtthread_startup(void)
{
    rt_hw_interrupt_disable();          /* 1. 关中断，启动期不允许打扰 */

    rt_hw_board_init();                 /* 2. BSP：时钟、中断、堆地址、串口、SysTick */

    rt_show_version();                  /* 3. 打印版本号（RT_DEBUG 下） */

    rt_system_heap_init(HEAP_BEGIN, HEAP_END);  /* 4. 初始化系统堆 */

    rt_scheduler_init();                /* 5. 调度器数据结构 */
    rt_system_timer_init();             /* 6. 定时器链表（HARD 模式） */
    rt_thread_idle_init();              /* 7. 空闲线程（最低优先级） */

    rt_hw_spin_lock_init();             /* SMP 下才需要 */

    rt_system_scheduler_start();        /* 8. 之后：自动初始化 + main 线程 → 启动调度 */
    return 0;
}

2.2 $Sub$$main 与 main 线程

很多初学者的疑问是「我的 main() 去哪了」。答案是：你的 main() 变成了 main 线程的入口函数。

/* libcpu / components 中的钩子（ARMCC / GCC 均支持） */
extern int $Super$$main(void);
int $Sub$$main(void)
{
    rtthread_startup();                 /* 1. 先把内核跑起来 */
    return $Super$$main();              /* 2. 再进入用户 main —— 此时它已是 main 线程 */
}

2.3 自动初始化六等级

RT-Thread 用链接器段排序实现自动初始化：宏把函数指针放进指定的段，启动时按段顺序依次调用。等级从低到高：

/* 典型业务模块注册方式 */
static int app_msg_center_init(void)
{
    msg_center_init();                  /* 建消息队列 */
    rt_thread_create("msg", ...);       /* 建业务线程 */
    return RT_EOK;
}
INIT_APP_EXPORT(app_msg_center_init);   /* 挂到等级 6 */

/* 需要参数的初始化（5.x 支持传参） */
INIT_APP_EXPORT_WITH_PARAM(fn, param);

2.4 组件依赖顺序设计

等级只解决「大类」的顺序，模块之间的细粒度依赖需要自己设计。三步法：

1. 画依赖表：列出每个模块「初始化时依赖谁」。例：日志模块依赖 ulog 后端；业务线程依赖消息队列；协议栈依赖 UART 设备 + 消息队列。
2. 映射等级：被依赖者等级必须严格小于依赖者。同等级内的先后不可依赖（链接顺序不确定）。
3. 加运行时守卫：跨等级边界的调用点加 RT_ASSERT(handle != RT_NULL)，顺序错了立刻暴露，而不是跑飞。

2.5 启动期典型故障

3 · 线程管理

线程创建只是一次函数调用，但栈给多大、静态还是动态、删不删，决定了半年后会不会在客户现场死机。

3.1 静态 init / 动态 create

RT-Thread 为每个内核对象都提供了静态与动态两套 API，命名规律统一：rt_xxx_init/detach（静态）与 rt_xxx_create/delete（动态）。

/* ====== 动态：内核从堆里分配 TCB 与栈 ====== */
rt_thread_t rt_thread_create(const char *name,
                             void (*entry)(void *parameter),
                             void       *parameter,
                             rt_uint32_t stack_size,   /* 单位：字节 */
                             rt_uint8_t  priority,     /* 0 最高 */
                             rt_uint32_t tick);        /* 时间片长度（Tick 数） */
rt_err_t    rt_thread_delete(rt_thread_t thread);

/* ====== 静态：TCB 与栈由调用者提供 ====== */
rt_err_t rt_thread_init(struct rt_thread *thread,
                        const char       *name,
                        void (*entry)(void *parameter),
                        void             *parameter,
                        void             *stack_start,
                        rt_uint32_t       stack_size,
                        rt_uint8_t        priority,
                        rt_uint32_t       tick);
rt_err_t rt_thread_detach(rt_thread_t thread);

/* 静态线程：量产项目的默认写法（编译期即可从 map 文件看到占用，无堆碎片） */
#define THREAD_SAMPLE_PRIO      12
#define THREAD_SAMPLE_STACK     1024      /* 字节 */
#define THREAD_SAMPLE_TIMESLICE 10

static struct rt_thread  g_tSample;                        /* TCB：全局 / static */
ALIGN(RT_ALIGN_SIZE)
static rt_uint8_t        g_tSampleStack[THREAD_SAMPLE_STACK]; /* 栈：全局 / static */
static rt_thread_t       g_hSample = RT_NULL;

static void sample_entry(void *parameter)
{
    for (;;) {
        /* 业务代码，禁止 return */
    }
}

int sample_thread_init(void)
{
    rt_err_t err = rt_thread_init(&g_tSample, "sample",
                                  sample_entry, RT_NULL,
                                  &g_tSampleStack[0], sizeof(g_tSampleStack),
                                  THREAD_SAMPLE_PRIO, THREAD_SAMPLE_TIMESLICE);
    if (err != RT_EOK) return err;
    g_hSample = &g_tSample;
    return rt_thread_startup(g_hSample) == RT_EOK ? 0 : -1;   /* init 之后必须 startup */
}
INIT_APP_EXPORT(sample_thread_init);

警惕 不推荐在运行期频繁创建 / 删除线程。反复从堆里切块与回收会留下无法合并的碎片；需要「临时干活」的场景，改成常驻线程 + 消息队列唤醒（阻塞时不占 CPU），或用静态线程池。

3.2 线程状态机

RT-Thread 的状态枚举与 FreeRTOS 有一个关键区别：阻塞与挂起共用一个状态。

• INIT：已创建但尚未 startup（静态 init 后的状态）。
• READY：在就绪表中等待被调度。
• RUNNING：占用 CPU，同一时刻单核上只有一个。
• SUSPEND：等待 IPC / 延时，或被 rt_thread_suspend() 显式挂起。前者会被事件自动唤醒，后者只能靠 rt_thread_resume()。
• CLOSE：已退出，等待回收（动态线程由空闲线程回收 TCB 与栈）。

3.3 栈大小估算与水位

栈必须留余量，因为最坏路径往往不在正常测试里出现（最深调用链 + 最坏中断嵌套 + printf 同时发生）。

1. 先给宽松值：例如 1024 字节，先跑起来。
2. 跑满所有路径：异常分支、错误打印、最坏中断并发、参数边界。
3. 读水位：FinSH 执行 ps，看 sp 列显示的使用百分比；或用下方代码自算。
4. 反推配置值：已用 = stack_size − 剩余；目标 stack_size ≈ 已用 × 1.3，且剩余 ≥ 25%。
5. 回归锁死：写成具名宏（如 THREAD_SAMPLE_STACK 1024），并在监控线程里周期性检查，低于阈值上报。

/* 自算栈使用（成员名以所用版本内核源码为准） */
static rt_size_t stack_used(rt_thread_t th)
{
    if (th == RT_NULL) return 0;
    /* sp 指向当前栈顶；栈区间 [stack_addr, stack_addr + stack_size) */
    return (rt_size_t)((char *)th->stack_addr + th->stack_size - (char *)th->sp);
}

/* 开启 RT_USING_OVERFLOW_CHECK 后，内核提供栈溢出检查接口 */
#ifdef RT_USING_OVERFLOW_CHECK
    if (rt_thread_stack_check(th) != RT_EOK) { fault_record("STACK_OVERFLOW", th->name); }
#endif

3.4 常用 API 与规则

固定周期线程的正确写法。RT-Thread 内核没有与 vTaskDelayUntil 完全等价的通用 API（部分版本提供 rt_thread_periodic_delay()，以所用内核源码为准），推荐用绝对时刻补偿自行实现，避免周期漂移：

void sample_entry(void *parameter)
{
    rt_tick_t last = rt_tick_get();                       /* 基准时刻 */
    const rt_tick_t period = rt_tick_from_millisecond(10);/* 10 ms 周期 */

    for (;;) {
        rt_tick_t now  = rt_tick_get();
        rt_int32_t wait = (rt_int32_t)(last + period - now);   /* 有符号比较，可正确处理回绕 */
        if (wait > 0) {
            rt_thread_delay((rt_tick_t)wait);
            last += period;                                /* 正常：按基准推进，不累积误差 */
        } else {
            last = now;                                    /* 过载：重新对齐，并上报一次超时 */
            g_sample_overrun++;
        }
        sample_once();                                     /* 必须远短于 period */
    }
}

3.5 空闲线程与钩子

空闲线程（idle）由内核在启动阶段创建，优先级固定为 RT_THREAD_PRIORITY_MAX - 1（32 级时为 31），永远处于就绪状态，保证调度器总有线程可跑。

• 职责：回收被 delete 的线程资源（TCB / 栈）；提供空闲钩子；低功耗进入点。
• 空闲钩子：rt_thread_idle_sethook(hook)，只在 CPU 空闲时执行，可做 CPU 占用统计、进入低功耗、喂狗之外的轻量巡检。
• 红线 空闲钩子里不能阻塞：一旦钩子阻塞，资源回收与低功耗都会停摆，系统会「假死」——所有业务线程都在等，而 idle 卡住了。

static rt_uint32_t g_idle_cnt = 0;

static void idle_hook(void)
{
    g_idle_cnt++;                     /* 只做极轻量统计，禁止阻塞、禁止长耗时 */
    /* pm_enter();  —— 低功耗进入点由 BSP / PM 组件提供，本文不展开 */
}

int idle_hook_init(void)
{
    rt_thread_idle_sethook(idle_hook);
    return 0;
}
INIT_COMPONENT_EXPORT(idle_hook_init);

3.6 线程设计五原则

1. 单一职责：一个线程只处理一类业务，通过 IPC 与其他线程交互，不直接读写别人的全局变量。
2. 高优先级线程执行时间尽可能短：只做判定与投递，耗时活交给低优先级线程。
3. 禁止忙等：一切等待走阻塞 API；禁止 while(1) 空轮询。
4. 局部大数组不进栈：大于 64 B 的缓冲声明为 static / 全局，或改用内存池。
5. 一次性创建、运行期不删：系统启动后不再动态创建 / 删除线程，是最省心也最省 RAM 的架构。

static void xxx_entry(void *parameter)
{
    /* 1. 初始化本线程私有资源（失败要能安全退出或重试） */
    /* 2. 通知外界「我已就绪」（可选：发一个信号量 / 事件） */
    for (;;) {
        /* 3. 阻塞等待事件（带超时） */
        /* 4. 处理事件（短） */
        /* 5. 异常自恢复（超时 / 失败计数，超过阈值复位或降级） */
    }
    /* 永不 return */
}

4 · 调度机制

理解调度器怎么切线程，才能回答「为什么我的高优先级线程会被卡住 10 ms」这类问题。

4.1 优先级就绪表与位图

RT-Thread 的调度器由一张按优先级分桶的链表数组 + 一个位图组成：

/* 概念结构（具体定义见内核源码 src/scheduler.c） */
rt_list_t  rt_thread_priority_table[RT_THREAD_PRIORITY_MAX];  /* 每级一条就绪链表 */
rt_uint32_t rt_thread_ready_priority_group;                   /* 位图：bit i = 优先级 i 有就绪线程 */

/* 取最高优先级：一次 __rt_ffs 即可，O(1) 且与线程总数无关 */
highest = __rt_ffs(rt_thread_ready_priority_group) - 1;
next    = rt_list_entry(rt_thread_priority_table[highest].next, struct rt_thread, tlist);

4.2 抢占与时间片轮转

/* rt_thread_create 的最后一个参数就是时间片长度（Tick 数） */
rt_thread_create("worker", worker_entry, RT_NULL,
                 1024,              /* 栈：字节 */
                 15,                /* 优先级：数值越小越高 */
                 20);               /* 时间片：20 个 Tick（1000 Hz 下 = 20 ms） */

警惕 两个易错点：

• 时间片只在同优先级之间生效：低优先级线程不会因为「高优先级用了太久」而得到补偿，只要高优先级一直就绪，它就一直饿死。
• 时间片长度不是周期：它是「同优先级连续占用 CPU 的最长时长」，线程阻塞时会立刻让出，不消耗完整个时间片。

4.3 调度器锁与 rt_schedule

4.4 Cortex-M 上下文切换

与 FreeRTOS 一致：Cortex-M 上的切换由 SysTick（判定该不该切）与 PendSV（真正执行切换）协作完成，PendSV 被设为最低优先级，保证所有 ISR 处理完后再切换。

4.5 优先级数量与开销