12 · 原书 382–394 页故障排查
12.1本章引言与范围
本章列出 FreeRTOS 新手最常遇到的问题。首先聚焦多年来被证明最常引发支持请求的三类问题:不正确的中断优先级赋值、栈溢出,以及对 printf() 的不当使用;随后以 FAQ 形式简要介绍其他常见错误、可能成因与解决办法。
定义 configASSERT() 能在错误发生现场立即捕获并识别许多最常见的错误来源,从而提升开发效率;强烈建议在开发或调试 FreeRTOS 应用期间定义它。configASSERT() 见 11.2 节。
12.2中断优先级
configASSERT() 会立即捕获该错误。若所用 FreeRTOS 移植支持中断嵌套,且某个中断的服务例程调用了 FreeRTOS API,则该中断的优先级必须设置为不高于 configMAX_SYSCALL_INTERRUPT_PRIORITY(见 6.8 节《中断嵌套》)。未做到这一点会导致临界区失效,进而造成间歇性故障。
在以下特性的处理器上运行 FreeRTOS 时需特别留意:
- 中断优先级默认取最高可能优先级(部分 ARM Cortex 处理器如此,其他处理器也可能如此)。这类处理器上,使用 FreeRTOS API 的中断优先级不能留作未初始化。
- 数值越大的优先级编号对应逻辑上越低的中断优先级,可能与直觉相反,因而容易造成混淆。ARM Cortex 处理器同样如此。
- 举例:在这类处理器上,优先级 5 执行中的中断可被优先级 4 的中断打断。因此若
configMAX_SYSCALL_INTERRUPT_PRIORITY设为 5,使用 FreeRTOS API 的中断只能赋予数值上 ≥ 5 的优先级;优先级 5、6 合法,优先级 3 则明确非法。 - 不同库实现要求以不同方式指定中断优先级。对面向 ARM Cortex 处理器的库尤其如此:中断优先级在写入硬件寄存器前要进行位偏移(移位);有的库自行完成移位,有的库则要求在把优先级传入库函数之前先完成移位。
- 同一架构的不同实现支持不同数量的中断优先级位。例如某厂商的 Cortex-M 实现 3 个优先级位,另一厂商可能实现 4 个。
- 定义中断优先级的位可拆分为抢占优先级位与子优先级位。应确保所有位都用于指定抢占优先级,不使用子优先级。
在部分 FreeRTOS 移植中,configMAX_SYSCALL_INTERRUPT_PRIORITY 另有别名 configMAX_API_CALL_INTERRUPT_PRIORITY。
12.3栈溢出
栈溢出是第二常见的支持请求来源。FreeRTOS 提供若干特性辅助捕获和调试栈相关问题¹。
12.3.1uxTaskGetStackHighWaterMark() API 函数
每个任务维护自己的栈,栈总大小在任务创建时指定。uxTaskGetStackHighWaterMark() 用于查询任务距离栈空间溢出有多近;该值称为栈“高水位线”。
UBaseType_t uxTaskGetStackHighWaterMark( TaskHandle_t xTask );
| 参数 / 返回值 | 说明 |
|---|---|
| xTask | 要查询栈高水位线的任务(目标任务)句柄;获取任务句柄的方式见 xTaskCreate() 的 pxCreatedTask 参数。任务可通过传入 NULL 代替有效句柄来查询自身栈高水位线。 |
| 返回值 | 任务执行与中断处理过程中,栈用量时增时减。本函数返回任务自开始执行以来剩余栈空间的最小值,即栈用量达到最大(最深)时仍未使用的栈量。高水位线越接近 0,任务越接近栈溢出。 |
¹ 这些特性在 FreeRTOS Windows 移植中不可用。
12.3.2运行时栈检查:概览
FreeRTOS 包含两种可选的运行时栈检查机制,由 FreeRTOSConfig.h 中的编译期配置常量 configCHECK_FOR_STACK_OVERFLOW 控制。两种方法都会增大上下文切换耗时。
栈溢出钩子(栈溢出回调)是内核检测到栈溢出时调用的函数。使用栈溢出钩子需:
- 在
FreeRTOSConfig.h中把configCHECK_FOR_STACK_OVERFLOW设为 1 或 2(见下文各小节)。 - 按清单 174 给出的确切函数名与原型实现钩子函数。
void vApplicationStackOverflowHook( TaskHandle_t *pxTask, signed char *pcTaskName );
提供栈溢出钩子是为了便于捕获和调试栈错误;但栈溢出一旦发生,实际上没有真正可靠的恢复手段。函数参数把发生栈溢出任务的句柄和名称传入钩子。
栈溢出钩子在中断上下文中被调用。部分微控制器在检测到非法内存访问时会产生故障异常,故障可能在内核有机会调用栈溢出钩子之前就已触发。
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() 实现、只能使用通用实现,需特别留意:
- 仅包含一次对
printf()或sprintf()的调用,就可能大幅增大应用可执行文件体积。 printf()、sprintf()可能调用malloc();若使用 heap_3 以外的内存分配方案,这可能非法。详见 2.2 节《内存分配示例方案》。printf()、sprintf()可能要求数倍于常规需求的栈空间。
12.4.1printf-stdarg.c
许多 FreeRTOS 演示工程使用名为 printf-stdarg.c 的文件,它提供一个精简、栈占用高效的 sprintf() 实现,可替代标准库版本。多数情况下,这可为每个调用 sprintf() 及相关函数的任务分配小得多的栈。
printf-stdarg.c 还提供逐字符把 printf() 输出导向某个端口的机制;虽然速度慢,但能进一步降低栈用量。
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 函数。