Mastering the FreeRTOS Real Time Kernel · 中文版 /12 故障排查

12 · 原书 382–394 页故障排查

Trouble Shooting

12.1本章引言与范围

本章列出 FreeRTOS 新手最常遇到的问题。首先聚焦多年来被证明最常引发支持请求的三类问题:不正确的中断优先级赋值、栈溢出,以及对 printf() 的不当使用;随后以 FAQ 形式简要介绍其他常见错误、可能成因与解决办法。

定义 configASSERT() 能在错误发生现场立即捕获并识别许多最常见的错误来源,从而提升开发效率;强烈建议在开发或调试 FreeRTOS 应用期间定义它。configASSERT() 见 11.2 节。

12.2中断优先级

这是支持请求的头号原因;在大多数移植中,定义 configASSERT() 会立即捕获该错误。

若所用 FreeRTOS 移植支持中断嵌套,且某个中断的服务例程调用了 FreeRTOS API,则该中断的优先级必须设置为不高于 configMAX_SYSCALL_INTERRUPT_PRIORITY(见 6.8 节《中断嵌套》)。未做到这一点会导致临界区失效,进而造成间歇性故障。

在以下特性的处理器上运行 FreeRTOS 时需特别留意:

在部分 FreeRTOS 移植中,configMAX_SYSCALL_INTERRUPT_PRIORITY 另有别名 configMAX_API_CALL_INTERRUPT_PRIORITY。

12.3栈溢出

栈溢出是第二常见的支持请求来源。FreeRTOS 提供若干特性辅助捕获和调试栈相关问题¹。

12.3.1uxTaskGetStackHighWaterMark() API 函数

每个任务维护自己的栈,栈总大小在任务创建时指定。uxTaskGetStackHighWaterMark() 用于查询任务距离栈空间溢出有多近;该值称为栈“高水位线”。

UBaseType_t uxTaskGetStackHighWaterMark( TaskHandle_t xTask );
清单 173 · uxTaskGetStackHighWaterMark() API 原型
参数 / 返回值说明
xTask要查询栈高水位线的任务(目标任务)句柄;获取任务句柄的方式见 xTaskCreate() 的 pxCreatedTask 参数。任务可通过传入 NULL 代替有效句柄来查询自身栈高水位线。
返回值任务执行与中断处理过程中,栈用量时增时减。本函数返回任务自开始执行以来剩余栈空间的最小值,即栈用量达到最大(最深)时仍未使用的栈量。高水位线越接近 0,任务越接近栈溢出。

¹ 这些特性在 FreeRTOS Windows 移植中不可用。

12.3.2运行时栈检查:概览

FreeRTOS 包含两种可选的运行时栈检查机制,由 FreeRTOSConfig.h 中的编译期配置常量 configCHECK_FOR_STACK_OVERFLOW 控制。两种方法都会增大上下文切换耗时。

栈溢出钩子(栈溢出回调)是内核检测到栈溢出时调用的函数。使用栈溢出钩子需:

void vApplicationStackOverflowHook( TaskHandle_t *pxTask, signed char *pcTaskName );
清单 174 · 栈溢出钩子函数原型

提供栈溢出钩子是为了便于捕获和调试栈错误;但栈溢出一旦发生,实际上没有真正可靠的恢复手段。函数参数把发生栈溢出任务的句柄和名称传入钩子。

栈溢出钩子在中断上下文中被调用。部分微控制器在检测到非法内存访问时会产生故障异常,故障可能在内核有机会调用栈溢出钩子之前就已触发。

12.3.3运行时栈检查:方法 1

当 configCHECK_FOR_STACK_OVERFLOW 设为 1 时选用方法 1。

任务每次被换出时,其完整执行上下文都会保存到自身栈上;栈用量很可能就在此时达到峰值。设为 1 时,内核在上下文保存后检查栈指针是否仍落在有效栈空间内;若发现栈指针超出有效范围,则调用栈溢出钩子。

方法 1 执行快,但可能漏掉两次上下文切换之间发生的栈溢出。

12.3.4运行时栈检查:方法 2

方法 2 在方法 1 已有检查之上再做额外检查;当 configCHECK_FOR_STACK_OVERFLOW 设为 2 时选用。

任务创建时,其栈被填充一个已知模式。方法 2 检测任务栈空间最后有效的 20 字节,验证该模式未被覆盖;若这 20 字节中有任何一字节偏离预期值,则调用栈溢出钩子。

方法 2 不如方法 1 快,但因只检查 20 字节,仍然相对较快。它很可能捕获所有栈溢出;但仍有可能(概率极低)漏掉个别溢出。

12.4printf() 与 sprintf() 的不当使用

对 printf() 的不当使用是常见错误来源;开发者往往在不知情的情况下又加入更多 printf() 调用辅助调试,反而使问题恶化。

许多交叉编译器厂商会提供适合小型嵌入式系统的 printf() 实现。即便如此,该实现也可能不是线程安全的,通常不适合在中断服务例程内使用,且根据输出去向不同,执行耗时可能相对较长。

若没有专为小型嵌入式系统设计的 printf() 实现、只能使用通用实现,需特别留意:

12.4.1printf-stdarg.c

许多 FreeRTOS 演示工程使用名为 printf-stdarg.c 的文件,它提供一个精简、栈占用高效的 sprintf() 实现,可替代标准库版本。多数情况下,这可为每个调用 sprintf() 及相关函数的任务分配小得多的栈。

printf-stdarg.c 还提供逐字符把 printf() 输出导向某个端口的机制;虽然速度慢,但能进一步降低栈用量。

注意:FreeRTOS 下载包中并非所有 printf-stdarg.c 副本都实现了 snprintf();未实现者会直接忽略缓冲区大小参数,因为其实现直接映射到 sprintf()。

printf-stdarg.c 为开源代码,但属第三方所有,因此单独于 FreeRTOS 授权;许可条款位于源文件顶部。

12.5其他常见错误来源

12.5.1症状:向演示工程加入一个简单任务后崩溃

创建任务需要从堆中获取内存。许多演示工程把堆尺寸设计为恰好够创建演示任务;任务创建完成后,剩余堆已不足以再添加任务、队列、事件组或信号量。

调用 vTaskStartScheduler() 时会自动创建空闲任务(可能还有 RTOS 守护任务)。vTaskStartScheduler() 仅在剩余堆内存不足以创建这些任务时才会返回;在调用 vTaskStartScheduler() 之后加一个空循环 [ for(;;); ],可让该错误更易调试。

要添加更多任务,要么增大堆尺寸,要么删除部分现有演示任务。详见 2.2 节《内存分配示例方案》。

12.5.2症状:在中断内调用 API 函数导致应用崩溃

除非 API 函数名以 ...FromISR() 结尾,否则不要在中断服务例程内调用。特别地,除非使用中断安全宏,不要在中断内创建临界区。详见 6.2 节《在 ISR 中使用 FreeRTOS API》。

在支持中断嵌套的 FreeRTOS 移植中,不要在被赋予高于 configMAX_SYSCALL_INTERRUPT_PRIORITY 的中断优先级的中断里调用任何 API 函数。详见 6.8 节《中断嵌套》。

12.5.3症状:应用有时在中断服务例程内崩溃

首先排查中断是否导致栈溢出。部分移植只检查任务内的栈溢出,不检查中断内的栈溢出。

中断的定义与使用方式在不同移植、不同编译器之间存在差异。其次要检查中断服务例程所用语法、宏和调用约定,是否与所用移植文档页所述、以及该移植配套演示工程所示完全一致。

若应用运行在用数值小的编号表示逻辑高优先级的处理器上,确保赋予每个中断的优先级已考虑这一与直觉相反的特点;若处理器把每个中断优先级默认为最大可能优先级,确保各中断优先级未留在默认值。详见 6.8 节《中断嵌套》与 12.2 节《中断优先级》。

12.5.4症状:调度器尝试启动第一个任务时崩溃

确认 FreeRTOS 中断处理程序已安装。信息见所用 FreeRTOS 移植的文档页,示例见该移植配套演示工程。

部分处理器必须先处于特权模式才能启动调度器。最简便的做法是在 main() 被调用之前的 C 启动代码中,把处理器置入特权模式。

12.5.5症状:中断被意外保持关闭,或临界区嵌套不正确

若在调度器启动之前调用 FreeRTOS API 函数,中断会被有意保持关闭,直到第一个任务开始执行才重新使能。这是为了保护系统:调度器尚未启动、可能处于不一致状态时,防止中断在系统初始化期间尝试使用 FreeRTOS API 而导致崩溃。

除通过 taskENTER_CRITICAL() 与 taskEXIT_CRITICAL() 调用外,不要用任何其他方式改动微控制器中断使能位或优先级标志。这些宏记录调用嵌套深度,确保仅当嵌套完全退出归零后才重新使能中断。注意:部分库函数自身可能会使能和关闭中断。

12.5.6症状:调度器尚未启动,应用就已崩溃

在调度器启动之前,不允许可能引发上下文切换的中断服务例程执行;尝试向队列、信号量等 FreeRTOS 对象发送或接收数据的中断服务例程同样如此。调度器启动之后才可能发生上下文切换。

许多 API 函数只能在调度器启动之后调用。在调用 vTaskStartScheduler() 之前,最好把 API 用法限制为创建任务、队列、信号量等对象,而不是使用这些对象。

12.5.7症状:调度器挂起期间或临界区内调用 API 函数导致崩溃

调度器通过调用 vTaskSuspendAll() 挂起,通过调用 xTaskResumeAll() 恢复(解除挂起);临界区通过调用 taskENTER_CRITICAL() 进入,通过 taskEXIT_CRITICAL() 退出。

不要在调度器挂起期间,或临界区内部调用 API 函数。