一句话结论：RTOS 系统层设计的本质，是用「优先级 + 阻塞」把 CPU 时间按截止时间分配出去。 绝大多数线上故障不来自内核，而来自三类人为错误：栈 / 堆容量不足、在 ISR 里调了非 FromISR 的 API、多个 Mutex 的加锁顺序不一致。 把这三件事管住，系统稳定性就解决了八成。

这份文档解决什么

本文只讲 FreeRTOS 系统层面：任务如何划分、优先级如何分配、同步原语怎么选型、堆与栈怎么规划、配置项怎么取舍、低功耗与看门狗怎么做、出问题怎么定位。 所有涉及具体外设的驱动实现（SPI / I2C / UART / 定时器 / 电源模式）都归 BSP 文档，本文只在必要处说明「任务侧该如何与它协作」。

使用约定

• 本文所有 API 以 FreeRTOS Kernel V10.x / V11.x 为准，Cortex-M3/M4/M33 为主要目标；M0/M0+ 无 BASEPRI，临界区行为见 10.3。
• 代码示例只保留系统层逻辑，凡涉及具体寄存器的部分统一写成 /* BSP 提供 */ 注释。
• 标 红线 的条目为强制约束，标 警惕 的为高频踩坑点。
• 涉及具体芯片参数、时钟频率、外设行为的数值，一律以官方 datasheet 与 FreeRTOS 官方参考手册为准。

1 · 系统架构与分层设计

这一章解决「系统应该切成几块、每块放什么」的问题。分层与任务划分一旦定错，后面所有调试都是在补窟窿。

1.1 四层分层模型

纯 RTOS 系统层面的代码只占中间两层。分层的目的不是好看，而是让内核源码保持零修改——一旦在产品里改了内核，后续升级与问题定位都会失控。

• ① 应用任务层：业务逻辑。每个任务只做一件事，通过消息与其他任务交互，不直接读别人的全局变量。
• ② RTOS 同步封装层：把队列 / 信号量 / 事件组的创建、收发、超时、错误处理封装成统一接口，业务侧只见封装不见内核对象。好处是：换 RTOS、加日志、加统计只改一处。
• ③ 内核层：FreeRTOS/Source 官方源码，只通过 FreeRTOSConfig.h 配置，红线 不修改任何内核源文件。
• ④ 移植层：portable/[compiler]/[arch] 与 heap_x.c。选官方现成的，除非做深度定制（MPU / SMP / 非标准编译器）。
• 驱动 / BSP 层：本指南不涉及。它与任务层的接口约定见 4.2 与 12.3。

1.2 任务划分原则

任务划分是最重要的一步。经验准则是：任务不宜过多，每个任务单一职责。

1. 先按时间特性切：硬周期（采样、控制）与突发（通信、按键）必须分开；周期不同就不是一个任务。
2. 再按功能独立性切：两个功能之间没有共享状态、可独立测试，就可以分开。
3. 高优先级任务必须短：只做「取数据 → 判条件 → 投递消息 / 置标志」，耗时活交给低优先级任务。
4. 不要做成一个大循环：一个 while(1) 里 switch 十几个状态，等于把裸机超级循环搬进 RTOS，抢占优势全部失效。
5. 同优先级可合并：时间特性相同、逻辑耦合紧密的功能，合并成一个任务比拆开更省栈、更少同步。

1.3 优先级分配方法论

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

两种可落地的分配方法：

• 速率单调（Rate Monotonic, RM）：周期越短，优先级越高。适用于一批纯周期任务，是理论最优的静态优先级分配。
• 截止时间优先（Deadline Monotonic）：按「从触发到必须完成的时限」排序，比 RM 更通用，适合混合了突发任务的场景。

按这两条规则排完之后，套用图 2 的八档表即可。

1.4 从裸机超级循环迁移

绝大多数项目是从裸机迁移来的，直接照搬结构会导致「RTOS 用了，但没完全用」。迁移路径如下：

警惕 迁移期最常见的失败模式：把裸机的巨型 while(1) 原封不动塞进一个高优先级任务。 结果所有逻辑仍然串行执行，还额外引入了栈溢出与优先级问题。正确顺序是「先拆时间特性，再拆功能」。

2 · 调度机制与任务状态机

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

2.1 抢占式调度与时间片轮转

• 抢占式（configUSE_PREEMPTION = 1）：只要更高优先级任务进入就绪态，当前任务立刻被抢占。这是实时性的基础。
• 时间片轮转（configUSE_TIME_SLICING = 1）：同优先级的多个就绪任务按 Tick 平分 CPU。注意它只在同优先级之间生效。
• 合作式（configUSE_PREEMPTION = 0）：只在任务主动让出或阻塞时切换。产品项目几乎不用，除非有极端的确定性要求。

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

2.2 任务状态机与状态迁移

FreeRTOS 任务有四个稳定状态：Running、Ready、Blocked、Suspended。真正影响实时性的是 Blocked——它是任务「让出 CPU 但仍在等待」的方式。

• Blocked 是好事：任务在等队列 / 信号量 / 事件 / 延时，不占 CPU，事件一到立刻回 Ready。
• Suspended 要慎用：它对调度器不可见，vTaskSuspend(NULL) 自己挂起自己后，若没有别的任务来 resume，就是永久卡死。
• Deleted 后的资源回收由空闲任务完成，因此不能饿死 IDLE（不要写优先级高于 IDLE 的无限循环任务）。

2.3 Cortex-M 上下文切换过程

Cortex-M 上的切换由两个异常协作完成：SysTick 负责判定「该不该切」，PendSV 负责真正执行切换。 PendSV 被设为最低优先级，保证所有其他中断处理完后再切换，避免中断响应被拖慢。系统启动时由 SVC 拉起第一个任务。

2.4 系统节拍与上下文切换开销

configTICK_RATE_HZ 决定时间粒度与开销：

3 · 任务管理

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

3.1 任务创建：动态与静态

动态创建原型：

BaseType_t xTaskCreate(TaskFunction_t pxTaskCode,
                       const char * const pcName,          /* 任务名，调试用，长度见 configMAX_TASK_NAME_LEN */
                       const configSTACK_DEPTH_TYPE usStackDepth,  /* 单位 word，不是字节 */
                       void * const pvParameters,          /* 传给任务的参数 */
                       UBaseType_t uxPriority,             /* 0 ~ configMAX_PRIORITIES-1 */
                       TaskHandle_t * const pxCreatedTask);/* 句柄，可为 NULL */

静态创建（推荐用于量产产品）：

/* 栈与 TCB 由编译器静态分配，不占堆，不产生碎片 */
static StackType_t  g_taskCtrlStack[CTRL_STACK_WORDS];   /* 例如 512 → 2 KB */
static StaticTask_t g_taskCtrlTCB;

TaskHandle_t g_hTaskCtrl;

void task_ctrl_create(void)
{
    g_hTaskCtrl = xTaskCreateStatic(
                        task_ctrl_entry,     /* 任务函数 */
                        "ctrl",              /* 名字 */
                        CTRL_STACK_WORDS,    /* 栈深度（word） */
                        NULL,                /* 参数 */
                        TASK_PRIO_CTRL,      /* 优先级 */
                        g_taskCtrlStack,     /* 栈缓冲区 */
                        &g_taskCtrlTCB);     /* TCB 缓冲区 */
    configASSERT(g_hTaskCtrl != NULL);       /* 静态创建只要参数合法就不会失败，仍建议断言 */
}

3.2 栈深度单位与栈大小估算

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

一个可套用的估算过程：

1. 先给一个宽松值：例如 512 word（2 KB），先跑起来。
2. 跑满所有路径：包括异常分支、错误打印、最坏中断并发、参数边界。
3. 读水位：uxTaskGetStackHighWaterMark(NULL)，得到历史最小剩余（单位 word）。
4. 反推配置值：已用 = 配置值 − 水位；目标 配置值 ≈ 已用 × 1.3，且水位 ≥ 25%。
5. 回归锁死：把最终值写成宏（如 #define CTRL_STACK_WORDS 384），并在监控任务里周期性检查水位，低于阈值上报。

3.3 栈溢出检测与栈水位

/* 栈溢出钩子：一旦触发，立刻定位到是哪个任务 */
void vApplicationStackOverflowHook(TaskHandle_t xTask, char *pcTaskName)
{
    /* 1. 点亮故障灯 / 打印任务名  2. 记录到 noinit 区供复位后读取  3. 复位 */
    (void)xTask;
    fault_record("STACK_OVERFLOW", pcTaskName);
    taskDISABLE_INTERRUPTS();
    for (;;) { /* 等待看门狗复位 */ }
}

/* 周期性检查水位（建议在监控任务里做） */
void monitor_check_stack(void)
{
    UBaseType_t left = uxTaskGetStackHighWaterMark(g_hTaskCtrl);
    if (left < CTRL_STACK_WORDS / 4) {     /* 余量不足 25% 时告警 */
        log_warn("ctrl stack low: %u words", (unsigned)left);
    }
}

3.4 任务删除与生命周期

• 任务函数不允许返回：必须是 for(;;) 结构，或者最后调用 vTaskDelete(NULL)。函数返回会跑飞（部分移植会触发断言）。
• 删除前必须自己释放资源：内核只回收 TCB 与栈（动态创建时），不会帮你关文件、释放 malloc 的内存、注销回调。
• 删除其他任务时，确保它没有持有 Mutex / 信号量，否则这些对象永久锁死。
• 动态创建的任务删除后，回收动作由空闲任务完成；如果 IDLE 长期得不到运行，内存不会释放。
• 静态创建的任务删除后，其栈与 TCB 不会自动回收复用，需要自行管理生命周期。

3.5 常用 API 与规则

vTaskDelay 与 vTaskDelayUntil 的正确用法：

void task_sample_entry(void *arg)
{
    TickType_t xLastWakeTime = xTaskGetTickCount();
    const TickType_t xPeriod = pdMS_TO_TICKS(10);      /* 10 ms 周期 */

    for (;;) {
        /* 1. 先阻塞到下一个周期点（这一步保证周期不漂移） */
        vTaskDelayUntil(&xLastWakeTime, xPeriod);

        /* 2. 再做本周期的工作 */
        sample_once();                                 /* 必须远短于 xPeriod */
    }
}

警惕 若 sample_once() 的执行时间 超过 周期，vTaskDelayUntil 会立刻返回（补不上）， 任务变成 100% 占用。监控任务应周期性检测「本周期是否超时」并上报。

3.6 任务通知 Task Notification

任务通知是最轻量的同步手段：每个任务的 TCB 里自带一个 32 位通知值与状态，不需要额外创建内核对象，速度约为二值信号量的 40% 耗时。

/* ====== 发送侧（任务或 ISR） ====== */
/* 当作轻量二值信号量：给一次通知 */
xTaskNotifyGive(g_hTaskCtrl);                 /* 任务中 */
vTaskNotifyGiveFromISR(g_hTaskCtrl, &xHigherPriorityTaskWoken);  /* ISR 中 */

/* 当作轻量事件组：按位传递 32 位值 */
xTaskNotify(g_hTaskCtrl, (1UL << 3), eSetBits);

/* ====== 接收侧 ====== */
uint32_t ulVal = ulTaskNotifyTake(pdTRUE, pdMS_TO_TICKS(100));   /* 清零后返回 */
if (ulVal == 0) { /* 超时：没有收到通知 */ }

/* 等待指定位 */
uint32_t bits = 0;
xTaskNotifyWait(0, 0xFFFFFFFF, &bits, portMAX_DELAY);

4 · 中断与任务交互

中断与任务的分界线画在哪里，决定了系统的响应延迟与可维护性。本文只讲系统层规则，具体外设 ISR 由 BSP 实现。

4.1 ISR 中的 API 规则

1. 只调用带 FromISR 后缀的 API：如 xQueueSendFromISR、xSemaphoreGiveFromISR、xTaskNotifyFromISR。
2. 绝不能在 ISR 里阻塞：任何带超时参数的 API 都不能用，portMAX_DELAY 更不行。
3. 绝不能在 ISR 里用 Mutex：Mutex 有所有权与优先级继承语义，ISR 不是任务，无法被提升优先级。
4. 处理 pxHigherPriorityTaskWoken 参数：被置位时，ISR 出口调用 portYIELD_FROM_ISR(x)。
5. 禁止在 ISR 里做堆分配 / 释放：pvPortMalloc / vPortFree 不可重入（heap_1/2/4 用临界区保护，但 ISR 中调用会破坏临界区语义）。
6. ISR 要短：经验上限是十几微秒到几十微秒；做不完的部分用延迟处理（4.2）。

void UART_IRQHandler(void)
{
    BaseType_t xHigherPriorityTaskWoken = pdFALSE;
    uint8_t byte;

    byte = uart_read_dr();                       /* BSP：清中断、读数据寄存器 */

    /* 只做搬运 + 投递，不解析、不打印 */
    if (xQueueSendFromISR(g_qUartRx, &byte, &xHigherPriorityTaskWoken) != pdPASS) {
        g_uart_rx_drop++;                        /* 队列满：记录丢弃次数，供监控上报 */
    }

    portYIELD_FROM_ISR(xHigherPriorityTaskWoken);  /* 必须：让高优先级任务立刻运行 */
}

4.2 延迟中断处理

把 ISR 里的重活搬到任务里做，是实时系统的标准做法。两种常见形态：

守护任务模板：

void task_uart_daemon_entry(void *arg)
{
    uint8_t byte;
    for (;;) {
        /* 阻塞等待，无数据时占用 0% CPU */
        if (xQueueReceive(g_qUartRx, &byte, portMAX_DELAY) == pdPASS) {
            proto_feed(&byte, 1);               /* 协议解析（耗时活在这里） */
            if (proto_frame_ready()) {
                msg_post(MSG_DST_APP, MSG_ID_UART_FRAME, proto_buf(), proto_len(), 0);
            }
        }
    }
}

4.3 中断优先级分组与 RTOS 阈值

Cortex-M 的中断优先级数值越小优先级越高，且优先级位数由芯片决定（__NVIC_PRIO_BITS，常见 4 位 → 0~15）。 FreeRTOS 用 BASEPRI 寄存器做「选择性屏蔽」：只屏蔽优先级低于阈值的中断，阈值以上（数值更小）的中断照常响应。

/* 典型 Cortex-M4（4 位优先级）配置片段，详见附录 A */
#define configPRIO_BITS               4
#define configLIBRARY_LOWEST_INTERRUPT_PRIORITY       15
#define configLIBRARY_MAX_SYSCALL_INTERRUPT_PRIORITY   5
#define configKERNEL_INTERRUPT_PRIORITY       (configLIBRARY_LOWEST_INTERRUPT_PRIORITY << (8 - configPRIO_BITS))
#define configMAX_SYSCALL_INTERRUPT_PRIORITY  (configLIBRARY_MAX_SYSCALL_INTERRUPT_PRIORITY << (8 - configPRIO_BITS))

M0 / M0+ 的特殊性

Cortex-M0 / M0+ 没有 BASEPRI 寄存器，FreeRTOS 的临界区实现是全局关中断（PRIMASK）。后果：

• 临界区期间所有中断都不响应（不像 M3/M4 只屏蔽阈值以下），关中断时长必须更严格。
• 中断里调用 FreeRTOS API 的约束依然存在，而且风险更高。
• 如果产品对中断延迟敏感，M0 上要特别注意临界区与 Tick 频率的取舍。

4.4 中断侧典型错误