如果你的 FreeRTOS 项目最近开始出现那种“跑着跑着就 HardFault”的毛病，或者某些全局变量在运行几个小时后莫名变成 0xFFFFFFFF，而你又实在找不到规律——别急着怀疑硬件、别急着怀疑编译器优化。十次里有八次，问题都出在某个任务的栈上。这个系列写到第七篇，前面我们已经把任务、队列、信号量、软件定时器这些基础 API 都过了一遍，这篇就来处理一个真正让嵌入式开发头皮发麻的问题：任务栈溢出，以及 FreeRTOS 为此提供的一整套检测和运行期监控 API。把这一套东西玩明白，你再看那些“灵异 Bug”，其实都是可以量化、可以提前堵死的。

1. FreeRTOS 任务栈：每一根都是有边界的钢丝

1.1 一个任务一份栈，参数里的 usStackDepth 是多少个“字”

很多刚接触 FreeRTOS 的朋友都会在一个地方栽跟头：xTaskCreate()最后一个参数叫usStackDepth，它表示栈的深度，但单位不是字节，而是“字”。在 Cortex-M 系列上，一个字是 4 字节。也就是说，你填 128，实际分配的是 512 字节；你填 256，实际分配的是 1KB。

BaseType_t xTaskCreate( TaskFunction_t pxTaskCode, // 任务函数 const char *pcName, // 任务名，仅用于调试 uint16_t usStackDepth, // 栈深度，单位是字，不是字节！ void *pvParameters, // 传给任务函数的参数 UBaseType_t uxPriority, // 任务优先级 TaskHandle_t *pxCreatedTask // 任务句柄 );

这个“字”的概念来自 FreeRTOS 最初的设计——它用StackType_t这个类型来表示栈元素，在 8 位、16 位、32 位平台上这个类型的宽度不同。所以同样的数值 128，在 STM32 上是 512 字节，在老的 AVR 移植版本上可能只是 256 字节。写代码时心里要始终绷着一根弦：一看到usStackDepth，先想一下当前平台的字长，再决定填多少。

xTaskCreateStatic()静态创建任务时也一样，下面的数组长度写的也是“字”：

StackType_t xTaskStack[512]; // 512 字，即 2KB（32位平台） StaticTask_t xTaskBuffer; xTaskHandle = xTaskCreateStatic(vMyTask, "myTask", 512, NULL, 2, xTaskStack, &xTaskBuffer);

很多人把 512 当成 512 字节用，结果任务一跑起来就悄悄越界，数据早被写花了，但当时一切看起来都正常。

1.2 溢出后的典型现场：为什么变量会莫名被改

任务栈溢出最坑的地方在于：它不一定会立刻崩。Cortex-M 的栈是向下增长的，栈指针 SP 越来越小。当一个任务把栈用过头，它会往低地址方向写数据，而那个低地址区域往往放着别的任务的控制块、任务栈、或者是 RTOS 内核的链表节点。

于是你看到的现场通常是这样的：

• 某个全局变量运行几个小时后变成 0xFFFFFFFF，但没有任何代码显式写过它。
• 一个任务明明没被创建过，却出现在 vTaskList 的输出里，或者某个句柄变成了野指针。
• 偶尔触发 HardFault，但是 fault 现场里看 PC 指针，指向的却是完全不相关的代码。
• 有时甚至完全正常，只有开启某个调试打印功能后开始频繁死机——因为那条打印路径临时多吃了几十字节的栈，成了压垮骆驼的最后一根稻草。

这些现象的共性就是“随机性”。传统调试手段在这种问题面前几乎失效，因为你没法回答一个最基本的问题：到底是哪个任务吃了栈？

1.3 移植 LVGL、lwIP 这类重量级库时，栈问题会特别显眼

我这两年帮人调过的 FreeRTOS 项目里，栈溢出聊到最多的场景就两个：一个是往里面移植 LVGL，另一个是接 lwIP 的 socket 接口。原因很直接——这两类库的函数调用层级深、局部变量大。

LVGL 的刷新任务里，一帧图像的数据往往要经过多层函数传递，中间临时缓冲区可能几百字节起步。lwIP 的协议栈任务更是重灾区，TCP 重传、分片重组时，函数栈的瞬时占用比其他任何任务都高。如果你拿默认的configMINIMAL_STACK_SIZE（通常只有 128 字，也就 512 字节）去跑这些东西，几乎必炸。

所以在涉及这类库的移植时，我一般会先把任务栈给得比较宽裕，然后跑一段时间看高水位线，再逐步往回收。这个流程后面会详细说。

2. 打开 configCHECK_FOR_STACK_OVERFLOW：让系统自己当哨兵

2.1 两档检测策略，代价差多少

FreeRTOS 从很早就提供了一套运行时的栈溢出检测机制，开关就一个宏：configCHECK_FOR_STACK_OVERFLOW，写在 FreeRTOSConfig.h 里。它的取值有三个：

方法一的原理很简单：每个任务都记录了自己的栈底地址。每次任务切换时，FreeRTOS 检查当前将要退出或被切换的任务的 SP 是否仍然落在合法区间内。如果 SP 已经越界，说明这个任务在运行期间把栈用穿了。这个方法实现很轻量，但有个盲区——如果任务在运行中临时越界写了几个字节，然后又弹回了合法区间（这种情况在局部变量使用瞬间峰值时完全可能发生），下一次切换检查时 SP 表面是正常的，但数据已经被污染了。

方法二则更进一步。任务创建时，FreeRTOS 会把任务栈的底部（远离栈顶的一端）一小段区域填上固定的特征值，之后每次任务切换时再去检查这段特征值有没有被改写。一旦被改写，说明栈确实向下溢出去过了。这相当于在栈底埋了个“压敏地雷”，比单纯看 SP 位置靠谱得多。

2.2 vApplicationStackOverflowHook 的正确姿势

无论选择方法一还是方法二，只要configCHECK_FOR_STACK_OVERFLOW非零，你就必须自己实现一个钩子函数：

void vApplicationStackOverflowHook(TaskHandle_t xTask, char *pcTaskName);

当 FreeRTOS 检测到溢出时，会带着出问题任务的句柄和名字调用这个函数。这是你最接近“案发现场”的时刻，务必把信息留下来：

char g_overflow_task_name[configMAX_TASK_NAME_LEN + 1]; void vApplicationStackOverflowHook(TaskHandle_t xTask, char *pcTaskName) { // 只做最轻量的事：把名字保存到全局变量，然后停在这里 if (pcTaskName != NULL) { strncpy(g_overflow_task_name, pcTaskName, configMAX_TASK_NAME_LEN); g_overflow_task_name[configMAX_TASK_NAME_LEN] = '\0'; } __asm volatile ("bkpt #0"); // 在这里打一个软件断点 }

这里有个很容易犯的错误：有人喜欢在钩子里printf或者做复位操作。我建议不要在钩子里调用任何可能阻塞、可能调度、可能再吃栈的 FreeRTOS API，也不要开串口打印。理由很简单：栈已经溢出了，你现在运行的每一行代码用的都是同一根危险的绳子，再调用一个打印函数，它自带几十上百字节的栈需求，极可能又炸一次，连钩子都跑不完。

稳妥的做法就是用全局变量保存信息，然后用调试器去看，或者点亮一个故障灯。如果一定要打印，也要做到“极简”——用寄存器操作直接写串口，不经过库函数。

2.3 开机多久能抓到？检测的局限要心里有数

configCHECK_FOR_STACK_OVERFLOW不是万能的，我列几个真实的局限：

第一，它只在任务切换的瞬间检查。如果某个任务在长时间占用 CPU 的过程中把栈踩穿，在切换出去之前这段污染可能已经扩散到别的任务，检测出来时是“谁踩的”可能已经说不清了。第二，方法二的特征值区域有限，如果越界只发生在特征值区域之上一点点，它同样发现不了。第三，开启检测会增加上下文切换的开销，对实时性要求极高的系统要评估一下。第四，钩子函数本身运行在中断或特殊上下文里，任何 FreeRTOS 的 API 调用都有风险。

所以我的真实经验是：configCHECK_FOR_STACK_OVERFLOW适合放在开发调试阶段常开，产品发布前可以根据情况关闭以换取一点性能。开发期它帮我省下的排查时间，远远超过它带来的那点切换开销。

3. uxTaskGetStackHighWaterMark：量化每个任务的“余粮”

3.1 接口签名、字节还是字、在哪调用

栈溢出检测是“事后诸葛亮”，而uxTaskGetStackHighWaterMark系列是“事前预防”。它做的是记录任务栈从创建到现在，曾经出现过的最小剩余量——也就是所谓的高水位线。剩余量越小，说明离崩越近；水位线越高，说明栈余粮越足。

UBaseType_t uxTaskGetStackHighWaterMark(TaskHandle_t xTask); UBaseType_t uxTaskGetStackHighWaterMark2(TaskHandle_t xTask);

调用时传NULL表示查询当前任务自己。要启用这两个接口，FreeRTOSConfig.h 里需要：

#define INCLUDE_uxTaskGetStackHighWaterMark 1

版本差异这里要特别提醒：老接口uxTaskGetStackHighWaterMark在不同移植板上返回的单位不统一，有的移植按字返回，有的按字节返回，历史上坑了不少人。FreeRTOS 后来加了uxTaskGetStackHighWaterMark2，明确按字节返回。如果的版本较新，直接用带 2 的版本，省得再做单位换算。

在 32 位 Cortex-M 上，如果只能用老接口，换算方法是：

UBaseType_t uxWords = uxTaskGetStackHighWaterMark(NULL); uint32_t uxBytes = uxWords * sizeof(StackType_t); // 乘以 4

3.2 用高水位线反推任务栈大小的实战流程

拿到高水位线后，真正的价值在于“反推”。我的做法是这么一套流程：

第一步，先把任务栈初始给大，比如根据任务复杂度给 512 字或 1024 字。第二步，让系统跑实际业务，而且要把所有异常分支都触发一遍——比如 TCP 断线重连、LCD 刷新高峰、错误处理打印路径。第三步，用调试任务周期性打印每个任务的高水位线。第四步，看最小值。比如某个任务跑了三天，高水位线最小值是 120 字节，那么考虑留 50% 的余量，任务栈可以压到 256 字节左右。

这个过程一定要用真实场景跑出来的数据说话，而不是拍脑袋定栈大小。

LVGL 类的 GUI 任务我见过高水位线在 800 字节附近的，lwIP 的协议栈任务水位线在几百字节到 1KB 之间波动，普通 LED 闪烁类任务可能 64 字都绰绰有余。差异极大，不测真的没法知道。

3.3 为什么“现在没溢出”不等于“永远不溢出”

高水位线有一个天然缺陷：它记录的是“历史最小剩余”，但是不会告诉你“峰值栈需求”是什么时候发生的、由哪条路径引起的。也就是说，如果你在测试阶段没有跑到某个极端代码路径，高水位线就不会体现那条路径的峰值消耗，等上线后用户触发了那个分支，栈才会暴露问题。

这块的经验是：栈大小余量要给够，尤其注意打印类、字符串处理类、浮点格式化类代码路径。printf、sprintf在 many 嵌入式工具链里是栈消耗大户，一次格式化可能吃掉一两百字节。所以我在做栈规划时，会把“最深层调用 + 最重的打印路径”单独拎出来测试，故意在最关键时刻触发一次错误打印，看水位线是不是突然掉了一大截。

4. 堆内存也要盯着：xPortGetFreeHeapSize 系列 API

4.1 三个堆 API 的分工与适用堆方案

任务栈不炸了，堆内存还会炸。FreeRTOS 提供几个查询堆状态的 API，虽然功能简单，但在实战里特别管用：

size_t xPortGetFreeHeapSize(void); size_t xPortGetMinimumEverFreeHeapSize(void);

xPortGetFreeHeapSize()返回当前剩余堆字节数；xPortGetMinimumEverFreeHeapSize()返回从启动到现在的历史最小剩余堆字节数。后者一旦明显偏低，说明系统在某个时段出现过“内存饥荒”。

但这两个函数不是所有 heap 实现都有。FreeRTOS 的内存管理方案有 heap_1 到 heap_5 五种，各有侧重。我自己的习惯是：产品上用 heap_4，它支持释放和内存块合并，能有效缓解碎片问题，而且这两个查询接口它都支持。heap_2 虽然支持释放，但不做相邻块合并，碎片化严重时接口意义有限。heap_3 只是包装了 C 库的 malloc，查询接口行为依赖于编译器的 malloc 实现，就不太可控了。

4.2 碎片化的观察方法与最小余量记录

堆碎片是个隐蔽问题：系统刚启动时剩余堆 20KB，跑了一天，仍然“够用”，但如果频繁地创建又删除大小不一的动态对象，空闲块会被切成很多细小的碎片，最后剩出一堆“大块拼不出来”的小块。此时xPortGetFreeHeapSize()看起来还剩几千字节，但一次 2KB 的分配却会失败。

碎片问题怎么观察？我常用的办法是周期性记录两个值：当前的xPortGetFreeHeapSize()和历史最小的xPortGetMinimumEverFreeHeapSize()。如果两者差距长期很大，说明堆里散落的小碎片不少。另外一个辅助手段是故意多次动态创建删除某个任务或队列，然后观察剩余堆是否持续下降——连续升降多次堆水位不停往下掉，基本就是碎片在作怪。

4.3 给调试任务写一个“体检循环”

把这些堆查询 API 和高水位线接口放一起，就能做一个很实用的系统体检任务：

void vDebugMonitorTask(void *pvParameters) { uint32_t ulLoop = 0; for (;;) { char pcInfo[64]; snprintf(pcInfo, sizeof(pcInfo), "[%lu] heapFree=%u heapMin=%u\r\n", (unsigned long)ulLoop++, (unsigned int)xPortGetFreeHeapSize(), (unsigned int)xPortGetMinimumEverFreeHeapSize()); // 这里把 pcInfo 通过串口/日志系统输出 // 再按需打印各任务高水位线 vTaskDelay(pdMS_TO_TICKS(5000)); } }

这个任务独立跑，栈给足（因为snprintf相对安全，但字符串中间变量也吃栈），把数据定时发出来，长期开着。真出问题时，翻日志找最早出现的“heapMin 逼近 0”或者某个任务水位线骤降的时间点，往往就是根因出现的时间窗口。

5. vTaskList 与 vTaskGetRunTimeStats：运行时的全景视图

5.1 需要同时打开的三个配置宏

除了栈和堆，我还经常用 FreeRTOS 提供的两个“格式化输出”接口：vTaskList()用于列出所有任务的状态、优先级、栈水位；vTaskGetRunTimeStats()用于统计各任务占用 CPU 的时间百分比。

这两个功能属于 FreeRTOS 的 trace facility，默认是关的。要用，必须同时打开下面几个配置宏：

#define configUSE_TRACE_FACILITY 1 #define configUSE_STATS_FORMATTING_FUNCTIONS 1 #define INCLUDE_uxTaskGetStackHighWaterMark 1

注意，vTaskGetRunTimeStats()还需要额外的运行时间统计配置：

#define configGENERATE_RUN_TIME_STATS 1

然后还要提供两个宏：一个负责初始化计时源，一个负责读取计数值。后面专门说。

5.2 输出表格的正确读法

vTaskList()的使用很简单，但也容易翻车。它需要一个足够大的缓冲区来存放格式化结果，而这个缓冲区如果定义在某个任务的局部变量里，就会临时占用那个任务的栈空间。任务太多、缓冲区太小，会直接把栈挤爆——没错，一个用来查栈溢出的 API，本身的错误使用方式就是制造栈溢出。

char pcBuffer[1024]; // 这个数组存放在调用任务的栈里 vTaskList(pcBuffer); // 新版本签名可能带长度参数，按你的版本填 UART_SendString(pcBuffer);

输出格式大致如下：

Name State Priority Stack Task# vDebugTask R 2 92 1 vUartTask B 3 136 2

State 列里 R 表示运行中，B 表示阻塞，S 表示挂起，D 表示已删除。Stack 列是当前高水位（通常按字节显示）。看这张表，你能一眼发现谁的水位线偏低，谁的状态不符合预期。

vTaskGetRunTimeStats()输出则是每个任务运行时间占总时间的百分比，格式类似vUartTask 12.5%。这个数据的价值在于判断任务负载是否均衡：某个任务占了 90% 的 CPU，那它自己再吃点栈、再偶尔卡一下，整个系统的实时性都会跟着遭殃。

5.3 运行时间统计的计时源：DWT 还是硬件定时器

vTaskGetRunTimeStats()需要知道“时间流逝了多少”，否则算不出百分比。常见的做法有两种。

第一种：用内核的 tick 计数，简单但分辨率太低，tick 频率 1000Hz 时，一个只需要 0.4ms 的任务可能统计不到，导致百分比失真。第二种：用硬件自由计数器，Cortex-M 上有现成的 DWT 周期计数器，分辨率就是 CPU 主频分之一，高得多：

#define configGENERATE_RUN_TIME_STATS 1 #define portCONFIGURE_TIMER_FOR_RUN_TIME_STATS() \ do { \ CoreDebug->DEMCR |= CoreDebug_DEMCR_TRCENA_Msk; \ DWT->CYCCNT = 0; \ DWT->CTRL |= DWT_CTRL_CYCCNTENA_Msk; \ } while (0) #define portGET_RUN_TIME_COUNTER_VALUE() (DWT->CYCCNT)

用 DWT 的好处是不占额外定时器资源，坏处是和 CPU 频率绑定，跑在不同主频上时计数值含义不同，但它只是用于百分比统计，这个影响可以忽略。如果你手头的定时器资源富余，用 TIM2 之类的 32 位定时器做自由计数也很方便，记得选择计数频率足够高的源，否则分辨率太低看不出微小的任务占用差异。

数据有了，怎么读？我一般会开一次统计，让系统在典型负载下跑 30 分钟，同时打印 CPU 占用分布。如果某个任务的百分比长期异常高，再结合它的高水位线一起看，就能锁定很多问题。

6. 一次真实的栈溢出排查：从 HardFault 到根因

6.1 现场情况：跑 3 小时才崩，且毫无规律

去年有个项目，四层板，STM32F407，跑了 FreeRTOS + lwIP 的 TCP 服务。现象是设备运行 3 到 8 小时后随机 HardFault，重启后又能正常一段时间。更诡异的是，抓到的 HardFault 现场 PC 值每次都指向不同的地方，有时在协议栈函数里，有时在任务切换代码里，有时甚至在中断处理里。所有任务创建代码都检查过返回值，没有失败；全局变量丢了，但没看出赋值关系。

这种问题用常规手段根本没法定位，因为它的根源不在“发生 HardFault 的那一刻”，而在几个毫秒之前——某个任务把栈踩穿，破坏了相邻内存，等内核访问到被破坏的区域时才触发异常。

6.2 三步定位的完整链路

我当时的处理路径，基本就是这篇文章前面三节讲的东西：

第一步，打开configCHECK_FOR_STACK_OVERFLOW，设为 2。这步的价值是：让系统在问题发生的最早时刻捕捉一次栈溢出，而不是等它演化成 HardFault。我实现了极简的钩子函数，把出问题任务的名字存到全局数组里，然后进入断点。

第二步，设备再次崩溃后，通过调试器查看g_overflow_task_name，锁定了 TCP 协议栈任务。这个结果其实有点出乎意料——这个任务我当初给了 1024 字的栈，理论上是够的。但高水位线数据一拉出来就明白了：正常情况下水位线剩余 500 多字节，一旦 TCP 进入某个特定状态机，瞬时要拼装一个很大的报文，函数调用栈瞬间吃掉近 900 字节，直接踩穿底部。

第三步，用xPortGetFreeHeapSize()和xPortGetMinimumEverFreeHeapSize()再确认了一下堆状态。果然，虽然没到 0，但历史最低值缺口明显，说明 lwIP 的动态内存管理在某些路径下也偏紧。这也侧面印证了问题出在协议栈任务的压力峰值上，而不是单纯某一个任务写错了数组。

6.3 修复后的验证与我的例行做法

修复方案并不复杂：把这个任务栈从 1024 字加到了 1536 字，同时把 lwIP 的收发缓冲区相关配置稍微调大了一点。然后我没有立刻发布，而是让设备带着configCHECK_FOR_STACK_OVERFLOW = 2和调试监控任务连续跑了三天，期间反复触发 TCP 重连、并发连接、大数据块传输。三天后台式机的日志里没有出现任何溢出钩子触发记录，高水位线始终在 400 字节以上，HardFault 也没有再出现。

从那次之后，我给每个 FreeRTOS 项目的代码里都固定放一个“体检任务”，开着高水位和堆余量上报。哪怕发布版本里这些功能被关掉，开发阶段也一定会带着它们跑满整个测试周期。

这套东西用下来，我的体会是：栈溢出和堆耗尽这类问题，本质上不是“靠运气躲”的，而是“靠数据防”的。FreeRTOS 把检测接口都给你准备好了，你不提前埋好哨兵，就只能等 Bug 上了线，用一次 HardFault 来提醒你当初少写了一个宏。