FreeRTOS 栈溢出检测实战：从”莫名其妙死机”到高水位线监控，一次内存踩踏的排查记

上周被一个现场问题折磨了整整三天：一台部署在客户车间的采集网关，平时运行得好好的，隔三五天会毫无征兆地重启一次。没有日志、没有 HardFault 记录，看门狗也没有触发复位（设备是自己重启的）。客户觉得”偶尔死机可以接受”，但我睡不着——偶发问题背后一定是确定性的 bug，只是触发条件没凑齐。

最后抓到凶手：一个解析上报 JSON 的任务，栈开小了 256 字。遇到一条嵌套特别深的报文，递归解析直接把栈打穿，踩坏了相邻任务 TCB 里的内容，调度器在任务切换时带着脏数据飞了。这篇文章把整个排查过程和 FreeRTOS 栈溢出的检测体系整理出来，希望能帮你少熬几个夜。

一、栈溢出为什么这么难查

先说清楚它的”狡猾”之处。Cortex-M 的任务栈是从高地址向低地址生长的，而 FreeRTOS 的任务栈是从堆里分配的一块连续内存，堆里各个任务的栈紧挨着。栈溢出时，压栈数据会越过栈底边界，写到相邻的内存里去——可能是下一个任务的栈，也可能是 TCB，甚至是你以为”永远不该变”的全局变量。

这就导致三个典型的”伪症状”：

• 别的任务莫名出错：被踩的倒霉蛋不是肇事者，你顺着报错的任务查，方向就全错了。
• HardFault 但寄存器指向莫名其妙的地方：PC 或 LR 被踩脏后，异常现场完全不可信。
• 一切看起来正常，只是数据偶尔不对：踩的是数据区时最恶心，bug 潜伏期最长。

我的经验法则：凡是”偶发、无法复现、换一块板子就好/更坏”的问题，先怀疑栈溢出和内存越界，再怀疑别的。查这类问题的性价比排序里，栈检查永远是第一位，因为它是 FreeRTOS 内置的，打开一个宏就行。

二、第一道防线：configCHECK_FOR_STACK_OVERFLOW

FreeRTOS 自带两种栈溢出检测方式，由 FreeRTOSConfig.h 里的 configCHECK_FOR_STACK_OVERFLOW 控制：

// FreeRTOSConfig.h
#define configCHECK_FOR_STACK_OVERFLOW    2   // 0=关闭, 1=方式一, 2=方式一+方式二

方式一（值 1）：任务切换时检查栈指针是否越过了栈边界。开销极小，但只能抓”正在发生”的溢出——如果溢出后栈指针又缩回去了（比如函数返回后），就漏检。

方式二（值 2）：在方式一基础上，创建任务时把栈全部填充为 0xA5 模式，任务切换时检查栈末尾 16 字节是否还保持着填充模式。能抓到”曾经溢出过又退回来”的情况，代价是每次上下文切换多一点检查时间。绝大多数场景直接上 2，这点开销在 168MHz 的 MCU 上完全可以忽略。

光开检测不够，溢出发生了你得知道是谁干的。配套的钩子函数必须实现，否则链接都过不了（或者静默进不了钩子）：

volatile TaskHandle_t xOverflowTask = NULL;

void vApplicationStackOverflowHook(TaskHandle_t xTask, char *pcTaskName)
{
    // 中断里别干复杂的事，先把现场钉死
    xOverflowTask = xTask;
    taskDISABLE_INTERRUPTS();

    // 有条件的话：往非易失存储写一条故障记录（任务名+时间戳）
    // 调试期最简单粗暴：断在这里，用调试器看调用栈
    for (;;);
}

那天我正是靠这个钩子抓到现场：pcTaskName 指向 "json_parse"，铁证如山。注意钩子里绝对不能调用任何 FreeRTOS API（很多 API 不可重入），最安全的做法是死循环等调试器，量产环境则写故障日志后触发系统复位。

三、量化评估：栈高水位线（High Water Mark）

钩子只能告诉你”溢出了”，不能告诉你”还差多少”。日常健康度监控要靠高水位线 API——它统计栈内还剩多少 0xA5 填充没被覆盖，也就是历史最深用栈距栈顶还剩多少：

void vStackMonitorTask(void *pvParameters)
{
    const TickType_t xInterval = pdMS_TO_TICKS(30000);  // 30 秒采样一次

    for (;;) {
        vTaskDelay(xInterval);

        TaskHandle_t xHandles[8];
        char acNames[8][configMAX_TASK_NAME_LEN];
        UBaseType_t uxCount = uxTaskGetNumberOfTasks();

        // 遍历所有任务，逐个报水位（单位：字，Cortex-M 上 1 字 = 4 字节）
        for (UBaseType_t i = 0; i < uxCount && i < 8; i++) {
            TaskHandle_t xH = xTaskGetHandle(pcTaskNames[i]);
            if (xH == NULL) continue;

            UBaseType_t uxWords = uxTaskGetStackHighWaterMark(xH);
            // 剩余不足 64 字（256 字节）就告警
            if (uxWords < 64) {
                LOG_WARN("stack low: %s, free=%u words",
                         pcTaskNames[i], uxWords);
            }
        }
    }
}

更省事的办法是 vTaskList()，一张表打出所有任务的名称、状态、优先级、剩余栈和任务号：

char acBuf[512];
vTaskList(acBuf);
printf("%s\r\n", acBuf);
/* 输出示例：
json_parse    X    2    71    4    Ready
sensor_poll   R    1    310   3    Running
mqtt_task     B    3    188   5    Blocked
...
第四列就是剩余栈（字），71 * 4 = 284 字节，危险！
*/

我踩过一个认知坑：uxTaskGetStackHighWaterMark 返回的是从任务创建以来的历史极值，不是当前值。所以这个 API 应该在任务”跑过最重的业务路径”之后读才有意义——刚上电就查，数据全无意义。我的做法是让监控任务在系统完成一轮完整业务（比如一条完整报文收发）之后再开始采样。

四、案发现场还原：那个 JSON 解析任务

回到本次事故。抓到肇事任务后，我做了三件事：

1. 算清楚它到底用了多少栈。 给该任务临时加大栈到 4096 字节，跑压力用例（构造 8 层嵌套的 JSON），再读高水位线：实际最深用栈约 1350 字节。原配置开的 1024 字节，缺口一目了然。

2. 分析为什么波动这么大。 JSON 递归下降解析每层嵌套要压一层栈帧（局部 buf + 解析状态 + 对齐 padding），栈深和报文复杂度正相关。栈大小必须按最坏情况开，而不是平均值——这是嵌入式和服务器编程最大的思维差异之一。

3. 重新定栈，留足余量。 最终定 2048 字节（约 1.5 倍实测峰值），并加入水位监控告警。

这次之后我把栈定级整理成了一公司内都通用的参考表：

任务类型	典型栈需求	说明
简单轮询/心跳	256~512 B	只调几个寄存器读写
带 printf 日志的任务	512~1024 B	printf 家族是栈大户，警惕浮点格式化
协议解析（JSON/XML）	1~4 KB	与嵌套深度正相关，必须用最坏报文实测
协议栈（TCP/IP + TLS）	4~8 KB	mbedTLS 握手单函数就能吃 2 KB
文件系统/复杂中间件	2~6 KB	FatFS 的 f_open 链路不浅

两条铁律：一是别照抄参考值，拿到板子上实测水位再定；二是给 USB、网络这类有”突发深路径”的任务单独留出验证用例。

五、终极方案：硬件级防护（MPU + FreeRTOS-MPU）

软件检测有个盲区：它靠任务切换时的检查，检测点是离散的。如果溢出代码在两次切换之间就破坏了关键数据并导致跑飞，可能直接 HardFault，来不及进钩子。

要做到”越界即死”，得上 MPU。FreeRTOS-MPU 版本允许给任务栈划出独立的 MPU region，越界访问立刻触发 MemManage 异常——问题在现场当场暴露，而不是三节课之后：

// 使用 FreeRTOS-MPU 时，用受限任务封装不可信的解析逻辑
static void vJsonParseTask(void *pvParameters)
{
    // 该任务内访问外设/内核对象都要显式声明，越权直接触发异常
    BaseType_t xResult = xBufferReceive(xQueue, &msg, portMAX_DELAY);
    ...
}

// 创建任务时传 portPRIVILEGE_BIT 之外的限制参数，
// 栈由 MPU 保护，溢出瞬间进 vApplicationMemFaultHook
xTaskCreateRestricted(&xTaskDef, NULL);

代价是改造不小：所有任务代码要按”特权/非特权”重新划分，内存分区要重新规划。我的建议是分级布防：

• 所有项目必开：configCHECK_FOR_STACK_OVERFLOW = 2 + 溢出钩子；
• 资源充足（M3 以上、RAM > 64KB）的项目：加水位监控告警；
• 安全相关或长期无人值守设备：上 FreeRTOS-MPU，把第三方库、解析器放进非特权任务隔离运行。

六、别忘了中断栈和链接脚本

排查过程中还顺手补了两个容易漏的洞：

中断栈（MSP）经常被无视。 FreeRTOS 的任务栈只管任务上下文，中断发生在哪一级就用 MSP。如果 ISR 里调了 printf 或者回调了任务层的深函数，烧的是主栈。startup_stm32xxx.s 里的 Stack_Size 就是它，我的习惯是中断栈给到最大任务栈的 1~1.5 倍，并且 ISR 里只做收发不做处理。

用链接脚本抓编译期问题。 GCC 下给每个函数加 -fstack-usage，编译生成 .su 文件，配合 puncover 之类的工具可以直接看到每个函数的栈帧大小，静态找出最深的调用链。这个我在另一块新板子上跑了，当场揪出一个用了 600 字节栈帧的格式化函数——上线前发现，永远好过现场救火。

七、栈健康 checklist

最后照例给出可以抄走的清单：

• ☑ configCHECK_FOR_STACK_OVERFLOW = 2，实现溢出钩子（写日志+复位，不留死循环上量产）
• ☑ 中断栈（MSP）≥ 最大任务栈 × 1.5，ISR 内不调用深层函数
• ☑ 上电自检后先跑一轮最重业务，再读 uxTaskGetStackHighWaterMark 定栈
• ☑ 栈余量告警阈值：剩余 < 栈深的 25% 告警、< 15% 强制上报
• ☑ 协议解析、TLS 握手等”深度不确定”的逻辑，用最坏输入做压测用例
• ☑ CI 里加 -fstack-usage，静态栈分析纳入每次发版
• ☑ 安全场景评估 FreeRTOS-MPU，第三方解析代码放非特权任务

那次事故的修复代码只有十几行，但从”怀疑内存坏了”到”定位到递归解析”花了三天。嵌入式的问题大多如此：元凶往往很小，难的是把怀疑范围收窄到它的那一刻。把检测体系提前建好，就是在为那一刻买保险。

下一篇计划聊聊 PCB 布局与 EMC，特别是那次调试 CAN 总线被电机驱动器干扰到怀疑人生的经历。有问题欢迎留言讨论。