从一次HardFault定位到栈溢出：FreeRTOS任务栈水位检测与溢出钩子的实战配置

一、事故现场：莫名其妙的HardFault

某项目在连续运行数小时后偶发死机，调试器停在HardFault_Handler。查看寄存器：

  • LR = 0xFFFFFFFD，说明异常发生在中断返回后，使用的是PSP（任务栈指针）
  • SCB->CFSR 的 IMPRECISERR 与 STKERR 位被置起
  • 反汇编定位到某任务函数内部，局部变量数组越界写

结论很典型：任务栈溢出。任务栈写穿后破坏了相邻内存（可能是另一个任务的TCB或栈），最终触发总线错误。这类问题偶发、难复现，必须靠机制而非运气来发现。

二、原理：FreeRTOS如何检测栈溢出

FreeRTOS提供两级防线：

  1. 编译期钩子检测：configCHECK_FOR_STACK_OVERFLOW
    • 设为1：任务切换时检查栈指针是否越界（快，但只能发现“已经溢出到栈外”的情况）
    • 设为2：任务创建时在栈顶填充魔术字0xA5A5A5A5，切换时检查栈末尾若干字节是否被改写（更灵敏，推荐）
  2. 运行时水位检测：uxTaskGetStackHighWaterMark()
    • 返回任务生命周期内栈剩余的最小值（单位：字），用于评估栈余量、指导栈大小调整

注意：水位值反映的是历史最小值，只能在调试阶段用于评估，不能替代溢出钩子。

三、配置步骤

1. FreeRTOSConfig.h 关键配置

#define configCHECK_FOR_STACK_OVERFLOW      2
#define configUSE_MALLOC_FAILED_HOOK        1
#define INCLUDE_uxTaskGetStackHighWaterMark 1
#define configUSE_TRACE_FACILITY            1   /* 便于遍历任务 */

2. 实现溢出钩子

#include "FreeRTOS.h"
#include "task.h"

void vApplicationStackOverflowHook(TaskHandle_t xTask, char *pcTaskName)
{
    (void)xTask;
    taskDISABLE_INTERRUPTS();
    /* 此处可点亮故障灯、记录任务名到备份寄存器或Flash */
    volatile char *name = pcTaskName;
    (void)name;
    for (;;) { }
}

钩子在任务上下文被调用，此时系统已不可信，只做最小化记录后停机，不要调用printf等重入函数。

3. 栈水位监控任务

void vStackMonitorTask(void *pv)
{
    (void)pv;
    TaskStatus_t *pxStatus;
    UBaseType_t uxCount = uxTaskGetNumberOfTasks();
    pxStatus = pvPortMalloc(uxCount * sizeof(TaskStatus_t));
    if (pxStatus == NULL) { vTaskDelete(NULL); }

    for (;;) {
        uxCount = uxTaskGetSystemState(pxStatus, uxCount, NULL);
        for (UBaseType_t i = 0; i < uxCount; i++) {
            /* 高水位值越小，说明栈余量越少 */
            if (pxStatus[i].usStackHighWaterMark < 32) {
                /* 余量不足32字，记录告警：任务名+余量 */
                log_warn(pxStatus[i].pcTaskName,
                         pxStatus[i].usStackHighWaterMark);
            }
        }
        vTaskDelay(pdMS_TO_TICKS(5000));
    }
}

4. 栈大小估算方法

  • 先用较大栈（如1024字）跑完整业务场景
  • 读取uxTaskGetStackHighWaterMark，得到最小余量M
  • 实际需求 ≈ 原栈大小 − M，再留30%~50%余量作为最终值
  • 中断嵌套深度、浮点上下文（若开启FPU）会额外消耗栈，需一并计入

四、完整示例：带水位打印的任务

static void vWorkerTask(void *pv)
{
    uint8_t buf[256];
    for (;;) {
        memset(buf, 0, sizeof(buf));
        /* 业务处理 */
        vTaskDelay(pdMS_TO_TICKS(100));
    }
}

void app_start(void)
{
    xTaskCreate(vWorkerTask, "worker", 512, NULL, 3, NULL);
    xTaskCreate(vStackMonitorTask, "mon", 256, NULL, 1, NULL);
    vTaskStartScheduler();
}

调试时在监控任务中打印各任务水位，确认余量充足后再量产。

五、注意事项

  • 钩子函数中禁止使用阻塞API、动态内存与不可重入函数
  • configCHECK_FOR_STACK_OVERFLOW=2 会带来少量切换开销，量产可保留，代价可接受
  • 中断服务程序使用主栈（MSP），主栈溢出不会触发任务钩子，需单独估算_Min_Stack_Size
  • 开启FPU时，任务切换会保存S0-S15等寄存器，栈需求显著增加
  • 水位值单位是字（4字节），不是字节，换算时勿混淆
  • 建议在CI或出厂自检中周期性检查水位，形成长期监控

栈溢出是嵌入式系统最隐蔽的故障源之一。把检测机制配置到位、把水位数据纳入日常观测，才能让HardFault从“玄学”变成“可定位的工程问题”。