嵌入式 Linux 与 RTOS / 系统课时

用断言尽早暴露配置错误

用断言尽早暴露配置错误

FreeRTOS 的很多错误在真正崩溃前就已经违反了内核或移植层的前置条件。配置好 configASSERT,可以在错误刚发生时保留文件和行号,把无效优先级、中断优先级和 API 误用从随机故障变成可定位的现场。

学习目标

  • 配置 configASSERT,让断言失败进入统一故障处理入口
  • 识别任务优先级、中断配置和 API 前置条件相关的典型断言
  • 为开发版和发布版设计不同的断言处理策略,而不是直接关闭检查

把 configASSERT 变成统一故障入口

configASSERT 不是一个固定函数,而是由应用在 FreeRTOSConfig.h 中定义的宏。FreeRTOS 内核及部分移植层会在关键前置条件不成立时调用它,因此是否定义这个宏,直接决定了很多非法状态能否在现场被截住。

一个实用的开发版做法是只记录文件和行号,然后停在一个容易被调试器捕获的位置。处理函数应尽量少依赖 RTOS API,因为断言可能发生在任务上下文,也可能发生在中断路径中。

片段示例(需放入现有 FreeRTOS 工程,其中宏位于 FreeRTOSConfig.h,函数实现放在普通 C 源文件中):

c
/* FreeRTOSConfig.h */
void vAssertCalled(const char *pcFile, int iLine);

#define configASSERT(x) \
    do { \
        if ((x) == 0) { \
            vAssertCalled(__FILE__, __LINE__); \
        } \
    } while (0)

/* assert_hook.c */
volatile const char *g_pcAssertFile = 0;
volatile int g_iAssertLine = 0;

void vAssertCalled(const char *pcFile, int iLine)
{
    /* 先保存最小现场,避免在未知上下文中调用阻塞式日志 API。 */
    g_pcAssertFile = pcFile;
    g_iAssertLine = iLine;

    for (;;) {
        /* 开发环境可在此下断点;平台需要时再加入专用停机指令。 */
    }
}

这段配置生效后,只要内核或应用执行到失败的 configASSERT,就会保存来源位置并进入 vAssertCalled()。如果芯片需要真正冻结整个系统,应在平台层补充与该端口匹配的关中断、断点或复位机制,不要把不可移植的指令塞进通用代码。

让错误在最接近根因的位置停下

断言最有价值的地方,是把“后来某处内存异常”提前变成“这里的调用条件不成立”。常见检查点包括:

问题 断言能帮助发现什么
任务优先级非法 创建任务时使用超出 configMAX_PRIORITIES 范围的优先级
Cortex-M 中断优先级错误 调用 FreeRTOS FromISR API 的中断优先级高于允许调用系统 API 的边界
无效句柄或参数 某些内核 API 收到不符合前置条件的对象或参数
移植层约束被破坏 中断优先级位数、临界区或调度相关配置与端口要求冲突

以 Cortex-M 为例,优先级数值越小通常代表硬件紧迫性越高。会调用 FreeRTOS FromISR API 的中断,不能配置成比 configMAX_SYSCALL_INTERRUPT_PRIORITY 所代表边界更高的硬件紧迫级别,否则部分端口会通过断言尽早报告问题。

主动验证断言链路

仅仅定义宏还不够,开发阶段应主动触发一次断言,确认文件、行号和停机路径确实可见。下面的验证程序需要放入一个已经完成芯片移植、能够启动 FreeRTOS 调度器的工程中。

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

static void vAssertProbe(void *pvParameters)
{
    (void) pvParameters;

    /* 故意制造失败,用于确认 configASSERT 的处理链路。 */
    configASSERT(0);

    vTaskDelete(NULL);
}

int main(void)
{
    BaseType_t xResult = xTaskCreate(
        vAssertProbe,
        "assert-probe",
        configMINIMAL_STACK_SIZE,
        NULL,
        tskIDLE_PRIORITY,
        NULL
    );

    configASSERT(xResult == pdPASS);
    vTaskStartScheduler();

    for (;;) {
    }
}

预期结果

text
g_pcAssertFile = "<PATH>/main.c"
g_iAssertLine = <LINE>
程序停留在 vAssertCalled() 的循环中

<PATH> 和 <LINE> 取决于实际工程路径及源码位置。调试器能够看到这两个变量,就说明从断言触发到现场保存的基本链路已经打通。

发布版仍然保留检查能力

开发版通常希望断言立即停止,并尽可能保留文件和行号;发布版则更关心系统能否留下可追踪的故障证据并进入受控恢复。两者目标不同,但不等于发布版应该把 configASSERT 整体删除。

发布构建可以把处理函数收缩成很短的故障路径:记录模块号、行号或压缩后的故障码到掉电保持区、备份寄存器或专用诊断缓冲区,再交给看门狗或平台复位函数恢复。具体持久化和复位 API 与芯片相关,应放在板级故障处理层实现。

断言的价值在于让错误离根因更近。开发阶段保留强检查和可调试现场,发布阶段改为最小、确定、可记录的故障处理,比完全关闭断言更容易定位那些只在真实负载和中断组合下出现的问题。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

用断言尽早暴露配置错误

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通