Mastering the FreeRTOS Real Time Kernel · 中文版 /11 开发者支持

11 · 原书 355–381 页开发者支持

Developer Support

11.1本章引言与范围

本章介绍一组内置特性,通过以下方式最大限度提升开发效率:洞察应用行为;指出优化机会;在错误发生的现场捕获错误。

11.2configASSERT()

C 语言中宏 assert() 用于验证程序做出的断言(假设)。断言写成 C 表达式;若表达式求值为假(0),即判定断言失败。例如清单 163 验证指针 pxMyPointer 非 NULL 的断言。

/* Test the assertion that pxMyPointer is not NULL */
assert( pxMyPointer != NULL );
清单 163 · 用标准 C assert() 宏检查 pxMyPointer 非 NULL

应用编写者通过提供 assert() 宏的实现,来指定断言失败时采取的动作。FreeRTOS 源码不调用 assert(),因为并非所有编译 FreeRTOS 的编译器都提供它;源码中包含大量对名为 configASSERT() 的宏的调用,应用编写者可在 FreeRTOSConfig.h 中定义该宏,行为与标准 C assert() 完全相同。断言失败必须视为致命错误,不要尝试越过断言失败的那一行继续执行。

使用 configASSERT() 可立即捕获并识别许多最常见的错误来源,从而提升效率。强烈建议在开发或调试 FreeRTOS 应用期间定义 configASSERT()。定义它会大大辅助运行时调试,但也会增大应用代码体积、拖慢执行。若未提供定义,将使用默认空定义,所有 configASSERT() 调用都会被 C 预处理器完全移除。

11.2.1configASSERT() 定义示例

清单 164 的定义适用于应用在调试器控制下运行的场景:任一断言失败行都会暂停执行,调试会话暂停时调试器显示的正是失败的那一行。

/* Disable interrupts so the tick interrupt stops executing, then sit in a loop so
execution does not move past the line that failed the assertion.  If the hardware
supports a debug break instruction, then the debug break instruction can be used in
place of the for() loop. */
#define configASSERT( x )  if( ( x ) == 0 ) { taskDISABLE_INTERRUPTS(); for(;;); }
清单 164 · 调试器控制下运行时可用的简单 configASSERT() 定义

清单 165 的定义适用于应用不在调试器控制下运行的场景:打印或以其他方式记录断言失败的源码行。失败行用标准 C __FILE__ 宏获取源文件名、__LINE__ 宏获取源文件内行号来标识。

/* This function must be defined in a C source file, not the FreeRTOSConfig.h header
file. */
void vAssertCalled( const char *pcFile, uint32_t ulLine )
{
    /* Inside this function, pcFile holds the name of the source file that contains
    the line that detected the error, and ulLine holds the line number in the source
    file.  The pcFile and ulLine values can be printed out, or otherwise recorded,
    before the following infinite loop is entered. */
    RecordErrorInformationHere( pcFile, ulLine );

    /* Disable interrupts so the tick interrupt stops executing, then sit in a loop
    so execution does not move past the line that failed the assertion. */
    taskDISABLE_INTERRUPTS();
    for( ;; );
}
/*-----------------------------------------------------------*/
/* These following two lines must be placed in FreeRTOSConfig.h. */
extern void vAssertCalled( const char *pcFile, uint32_t ulLine );
#define configASSERT( x )  if( ( x ) == 0 ) vAssertCalled( __FILE__, __LINE__ )
清单 165 · 记录断言失败源码行的 configASSERT() 定义

11.3FreeRTOS+Trace

FreeRTOS+Trace 是合作伙伴 Percepio 提供的运行时诊断与优化工具。它捕获有价值的动态行为信息,再以相互关联的图形视图呈现;工具还能显示多个同步视图。捕获到的信息在分析、排查问题或单纯优化 FreeRTOS 应用时非常宝贵。FreeRTOS+Trace 可与传统调试器并排使用,以更高层、基于时间的视角补充调试器的视图。

图 82 · FreeRTOS+Trace 包含 20 多个相互关联的视图
图 82 · FreeRTOS+Trace 包含 20 多个相互关联的视图
图 83 · FreeRTOS+Trace 主跟踪视图(20 多个互联跟踪视图之一)
图 83 · FreeRTOS+Trace 主跟踪视图(20 多个互联跟踪视图之一)
图 84 · FreeRTOS+Trace CPU 负载视图(20 多个互联跟踪视图之一)
图 84 · FreeRTOS+Trace CPU 负载视图(20 多个互联跟踪视图之一)
图 85 · FreeRTOS+Trace 响应时间视图(20 多个互联跟踪视图之一)
图 85 · FreeRTOS+Trace 响应时间视图(20 多个互联跟踪视图之一)
图 86 · FreeRTOS+Trace 用户事件绘图视图(20 多个互联跟踪视图之一)
图 86 · FreeRTOS+Trace 用户事件绘图视图(20 多个互联跟踪视图之一)
图 87 · FreeRTOS+Trace 内核对象历史视图(20 多个互联跟踪视图之一)
图 87 · FreeRTOS+Trace 内核对象历史视图(20 多个互联跟踪视图之一)

11.4调试相关钩子(回调)函数

11.4.1内存分配失败钩子

内存分配失败钩子(回调)已在第 2 章《堆内存管理》中介绍。定义该钩子可确保:创建任务、队列、信号量或事件组失败时,应用开发者立即收到通知。

11.4.2栈溢出钩子

栈溢出钩子的细节见 12.3 节《栈溢出》。定义该钩子可确保:任务使用的栈量超过分配给它的栈空间时,应用开发者收到通知。

11.5查看运行时与任务状态信息

11.5.1任务运行时统计

任务运行时统计提供每个任务获得处理时间的信息。任务运行时间是应用启动以来任务处于运行态的总时间。运行时统计用作项目开发阶段的剖析与调试辅助;其信息在用作运行时统计时钟的计数器溢出之前有效。收集运行时统计会增加任务上下文切换时间。

获取二进制运行时统计信息调用 uxTaskGetSystemState();获取人类可读 ASCII 表格形式的运行时统计,调用辅助函数 vTaskGetRunTimeStats()。

11.5.2运行时统计时钟

运行时统计需要度量节拍周期的分数部分,因此不用 RTOS 节拍计数作为统计时钟,时钟由应用代码提供。建议统计时钟频率比节拍中断频率快 10 到 100 倍;时钟越快统计越准确,但时间值也越快溢出。理想情况下,时间值由自由运行的 32 位外设定时器/计数器产生,读取其值无其他处理开销。若可用外设与时钟速度不支持该技术,可采用以下效率较低的替代方法:

通过适当且略复杂的处理,也可把 RTOS 节拍计数与 ARM Cortex-M SysTick 定时器当前值组合出统计时钟;FreeRTOS 下载包中的部分演示工程展示了实现方式。

11.5.3配置应用收集运行时统计

表 54 列出收集任务运行时统计所需的宏。这些宏原本计划纳入 RTOS 移植层(因此前缀为 port),但实践中在 FreeRTOSConfig.h 中定义更方便。

宏说明
configGENERATE_RUN_TIME_STATS必须在 FreeRTOSConfig.h 中设为 1。设为 1 后,调度器会在合适时机调用本表列出的其他宏。
portCONFIGURE_TIMER_FOR_RUN_TIME_STATS()必须提供,用于初始化提供统计时钟的外设。
portGET_RUN_TIME_COUNTER_VALUE(),或 portALT_GET_RUN_TIME_COUNTER_VALUE(Time)必须提供二者之一,返回当前统计时钟值,即应用首次启动以来以统计时钟单位计的总运行时间。用第一个宏时须定义为求值为当前时钟值;用第二个宏时须定义为把其 Time 参数设为当前时钟值。

11.5.4uxTaskGetSystemState() API 函数

uxTaskGetSystemState() 为 FreeRTOS 调度器管理的每个任务提供状态信息快照;信息以 TaskStatus_t 结构体数组形式给出,每个任务对应数组一个索引。TaskStatus_t 见清单 167 与表 56。

UBaseType_t uxTaskGetSystemState( TaskStatus_t * const pxTaskStatusArray,
                                 const UBaseType_t uxArraySize,
                                 uint32_t * const pulTotalRunTime );
清单 166 · uxTaskGetSystemState() API 原型
参数名说明
pxTaskStatusArray指向 TaskStatus_t 结构体数组的指针;数组至少须为每个任务包含一个结构体。任务数可用 uxTaskGetNumberOfTasks() 确定。结构体见清单 167,成员见表 56。
uxArraySizepxTaskStatusArray 所指数组的大小;以数组索引数(结构体个数)指定,而非字节数。
pulTotalRunTime若 FreeRTOSConfig.h 中 configGENERATE_RUN_TIME_STATS 为 1,本函数把 *pulTotalRunTime 设为自目标启动以来的总运行时间(按应用提供的统计时钟计)。可选参数,不需要总运行时间时置 NULL。
返回值返回被填充的 TaskStatus_t 结构体个数;应等于 uxTaskGetNumberOfTasks() 返回值。若 uxArraySize 传入值过小,返回 0。
typedef struct xTASK_STATUS
{
    TaskHandle_t xHandle;
    const char *pcTaskName;
    UBaseType_t xTaskNumber;
    eTaskState eCurrentState;
    UBaseType_t uxCurrentPriority;
    UBaseType_t uxBasePriority;
    uint32_t ulRunTimeCounter;
    uint16_t usStackHighWaterMark;
} TaskStatus_t;
清单 167 · TaskStatus_t 结构体
成员说明
xHandle本结构体信息所关联任务的句柄。
pcTaskName任务的人类可读文本名称。
xTaskNumber每个任务有唯一的 xTaskNumber 值。若应用在运行时创建并删除任务,新任务可能与先前被删任务拥有相同句柄;xTaskNumber 供应用代码与内核感知调试器区分仍有效的任务和与之同句柄的已删除任务。
eCurrentState保存任务状态的枚举类型,可取 eRunning、eReady、eBlocked、eSuspended、eDeleted。任务仅在被 vTaskDelete() 删除、到空闲任务释放其内部数据结构与栈内存之间的短暂时段内被报告为 eDeleted;此后任务已不存在,使用其句柄无效。
uxCurrentPriority调用 uxTaskGetSystemState() 时任务正在运行的优先级。仅当任务按 7.3 节互斥量(与二值信号量)所述优先级继承机制被临时抬升过优先级时,uxCurrentPriority 才高于应用编写者赋予任务的优先级。
uxBasePriority应用编写者赋予任务的优先级。仅当 configUSE_MUTEXES 为 1 时有效。
ulRunTimeCounter任务创建以来使用的总运行时间;以应用编写者为收集统计提供的时钟计的绝对时间。仅当 configGENERATE_RUN_TIME_STATS 为 1 时有效。
usStackHighWaterMark任务栈高水位线:任务创建以来剩余栈空间的最小值,指示任务距离栈溢出有多近;值越接近 0 越接近溢出。单位为字节。

11.5.5vTaskList() 辅助函数

vTaskList() 提供与 uxTaskGetSystemState() 类似的任务状态信息,但以人类可读 ASCII 表格呈现,而非二进制值数组。它是处理器开销很大的函数,会让调度器在较长时间内处于挂起状态,因此建议仅用于调试,不用于生产实时系统。

当 FreeRTOSConfig.h 中 configUSE_TRACE_FACILITY 与 configUSE_STATS_FORMATTING_FUNCTIONS 都为 1 时,vTaskList() 可用。

void vTaskList( signed char *pcWriteBuffer );
清单 168 · vTaskList() API 原型
参数名说明
pcWriteBuffer指向字符缓冲区的指针,格式化后的可读表格写入其中;缓冲区必须足够容纳整张表格,函数不做边界检查。

vTaskList() 输出示例见图 88。输出中:每行提供单个任务信息;第一列是任务名;第二列是任务状态,R 表示就绪、B 表示阻塞、S 表示挂起、D 表示已删除;第三列是任务优先级;第四列是任务栈高水位线(见表 56 中 usStackHighWaterMark);第五列是分配给任务的唯一编号(见表 56 中 xTaskNumber)。

图 88 · vTaskList() 生成的示例输出
图 88 · vTaskList() 生成的示例输出

11.5.6vTaskGetRunTimeStats() 辅助函数

vTaskGetRunTimeStats() 把收集到的运行时统计格式化为人类可读 ASCII 表格。它同样是处理器开销很大的函数,会让调度器在较长时间内挂起,建议仅用于调试,不用于生产实时系统。当 configGENERATE_RUN_TIME_STATS 与 configUSE_STATS_FORMATTING_FUNCTIONS 都为 1 时可用。

void vTaskGetRunTimeStats( signed char *pcWriteBuffer );
清单 169 · vTaskGetRunTimeStats() API 原型
参数名说明
pcWriteBuffer指向字符缓冲区的指针,格式化后的可读表格写入其中;缓冲区必须足够容纳整张表格,函数不做边界检查。

输出示例见图 89。输出中:每行提供单个任务信息;第一列是任务名;第二列是任务处于运行态时间的绝对值(见表 56 中 ulRunTimeCounter);第三列是任务运行态时间占目标启动以来总时间的百分比。显示百分比之和通常小于预期的 100%,因为统计使用向下取整到最近整数的整数运算收集和计算。

图 89(vTaskGetRunTimeStats() 示例输出):表格按任务列出绝对运行计数与占总运行时间的百分比;因整数向下取整,各百分比之和通常略低于 100%。

11.5.7生成并显示运行时统计:完整示例

本例用一个假设的 16 位定时器产生 32 位运行时统计时钟。计数器配置为 16 位值到达最大值时产生中断(实质为溢出中断),ISR 统计溢出次数。32 位值以溢出次数计数作为高两字节、当前 16 位计数器值作为低两字节组合而成,ISR 伪代码见清单 170。

void TimerOverflowInterruptHandler( void )
{
    /* Just count the number of interrupts. */
    ulOverflowCount++;

    /* Clear the interrupt. */
    ClearTimerInterrupt();
}
清单 170 · 统计定时器溢出次数的 16 位定时器溢出中断处理程序

清单 171 给出在 FreeRTOSConfig.h 中为启用运行时统计收集而加入的行。

/* Set configGENERATE_RUN_TIME_STATS to 1 to enable collection of run-time
statistics.  When this is done, both portCONFIGURE_TIMER_FOR_RUN_TIME_STATS() and
portGET_RUN_TIME_COUNTER_VALUE() or portALT_GET_RUN_TIME_COUNTER_VALUE(x) must also
be defined. */
#define configGENERATE_RUN_TIME_STATS
1

/* portCONFIGURE_TIMER_FOR_RUN_TIME_STATS() is defined to call the function that sets
up the hypothetical 16-bit timer (the function’s implementation is not shown). */
void vSetupTimerForRunTimeStats( void );
#define portCONFIGURE_TIMER_FOR_RUN_TIME_STATS() vSetupTimerForRunTimeStats()

/* portALT_GET_RUN_TIME_COUNTER_VALUE() is defined to set its parameter to the
current run-time counter/time value.  The returned time value is 32-bits long, and is
formed by shifting the count of 16-bit timer overflows into the top two bytes of a
32-bit number, then bitwise ORing the result with the current 16-bit counter
value. */
#define portALT_GET_RUN_TIME_COUNTER_VALUE( ulCountValue )                   \
    {                                                                        \
    extern volatile unsigned long ulOverflowCount;                           \
                                                                            \
        /* Disconnect the clock from the counter so it does not change       \
        while its value is being used. */                                    \
        PauseTimer();                                                        \
                                                                            \
        /* The number of overflows is shifted into the most significant      \
        two bytes of the returned 32-bit value. */                           \
        ulCountValue = ( ulOverflowCount << 16UL );                          \
                                                                            \
        /* The current counter value is used as the least significant        \
        two bytes of the returned 32-bit value. */                           \
        ulCountValue |= ( unsigned long ) ReadTimerCount();                  \
                                                                            \
        /* Reconnect the clock to the counter. */                            \
        ResumeTimer();                                                       \
    }
清单 171 · 加入 FreeRTOSConfig.h 以启用运行时统计收集的宏

清单 172 所示任务每 5 秒打印一次收集到的运行时统计。

/* For clarity, calls to fflush() have been omitted from this code listing. */
static void prvStatsTask( void *pvParameters )
{
    TickType_t xLastExecutionTime;

    /* The buffer used to hold the formatted run-time statistics text needs to be quite
    large.  It is therefore declared static to ensure it is not allocated on the task
    stack.  This makes this function non re-entrant. */
    static signed char cStringBuffer[ 512 ];

    /* The task will run every 5 seconds. */
    const TickType_t xBlockPeriod = pdMS_TO_TICKS( 5000 );

    /* Initialize xLastExecutionTime to the current time.  This is the only time this
    variable needs to be written to explicitly.  Afterwards it is updated internally
    within the vTaskDelayUntil() API function. */
    xLastExecutionTime = xTaskGetTickCount();

    /* As per most tasks, this task is implemented in an infinite loop. */
    for( ;; )
    {
        /* Wait until it is time to run this task again. */
        vTaskDelayUntil( &xLastExecutionTime, xBlockPeriod );

        /* Generate a text table from the run-time stats.  This must fit into the
        cStringBuffer array. */
        vTaskGetRunTimeStats( cStringBuffer );

        /* Print out column headings for the run-time stats table. */
        printf( "\nTask\t\tAbs\t\t\t%%\n" );
        printf( "-------------------------------------------------------------\n" );

        /* Print out the run-time stats themselves.  The table of data contains
        multiple lines, so the vPrintMultipleLines() function is called instead of
        calling printf() directly.  vPrintMultipleLines() simply calls printf() on
        each line individually, to ensure the line buffering works as expected. */
        vPrintMultipleLines( cStringBuffer );
    }
}
清单 172 · 打印收集到的运行时统计的任务

11.6跟踪钩子宏

跟踪宏是放置在 FreeRTOS 源码关键位置的宏。默认情况下这些宏为空,不产生任何代码、无运行时开销。通过覆盖默认空实现,应用编写者可以:在不修改 FreeRTOS 源文件的情况下向 FreeRTOS 插入代码;用目标硬件上可用的任何方式输出详细的执行时序信息。跟踪宏在 FreeRTOS 源码中出现的位置足够多,可用于创建完整、详细的调度器活动跟踪与剖析日志。

11.6.1可用的跟踪钩子宏

此处篇幅有限,无法逐一详述每个宏。表 59 列出对应用编写者最有用的一组子集。表中多处描述引用名为 pxCurrentTCB 的变量:它是 FreeRTOS 私有变量,保存处于运行态任务的句柄,可供从 FreeRTOS/Source/tasks.c 源文件中调用的任何宏使用。

宏说明
traceTASK_INCREMENT_TICK(xTickCount)在节拍中断中、节拍计数自增之后调用。xTickCount 参数把新的节拍计数值传入宏。
traceTASK_SWITCHED_OUT()在选中新任务运行之前调用。此时 pxCurrentTCB 保存即将离开运行态的任务句柄。
traceTASK_SWITCHED_IN()在选中任务运行之后调用。此时 pxCurrentTCB 保存即将进入运行态的任务句柄。
traceBLOCKING_ON_QUEUE_RECEIVE(pxQueue)当前执行任务因尝试读取空队列、或尝试“获取”空信号量/互斥量而进入阻塞态之前立即调用。pxQueue 参数把目标队列或信号量句柄传入宏。
traceBLOCKING_ON_QUEUE_SEND(pxQueue)当前执行任务因尝试写入已满队列而进入阻塞态之前立即调用。pxQueue 参数把目标队列句柄传入宏。
traceQUEUE_SEND(pxQueue)在 xQueueSend()、xQueueSendToFront()、xQueueSendToBack() 或任一信号量“给出”函数内部,队列发送或信号量“给出”成功时调用。pxQueue 传入目标队列或信号量句柄。
traceQUEUE_SEND_FAILED(pxQueue)在上述发送/给出函数内部,发送或给出操作失败时调用。若队列已满并在指定阻塞时长内一直保持已满,发送/给出失败。pxQueue 传入目标队列或信号量句柄。
traceQUEUE_RECEIVE(pxQueue)在 xQueueReceive() 或任一信号量“获取”函数内部,队列接收或信号量“获取”成功时调用。pxQueue 传入目标队列或信号量句柄。
traceQUEUE_RECEIVE_FAILED(pxQueue)在 xQueueReceive() 或任一信号量“获取”函数内部,队列或信号量接收操作失败时调用。若队列/信号量为空并在指定阻塞时长内一直保持为空,接收失败。pxQueue 传入目标队列或信号量句柄。
traceQUEUE_SEND_FROM_ISR(pxQueue)在 xQueueSendFromISR() 内部发送成功时调用。pxQueue 传入目标队列句柄。
traceQUEUE_SEND_FROM_ISR_FAILED(pxQueue)在 xQueueSendFromISR() 内部发送失败时调用;队列已满则发送失败。pxQueue 传入目标队列句柄。
traceQUEUE_RECEIVE_FROM_ISR(pxQueue)在 xQueueReceiveFromISR() 内部接收成功时调用。pxQueue 传入目标队列句柄。
traceQUEUE_RECEIVE_FROM_ISR_FAILED(pxQueue)在 xQueueReceiveFromISR() 内部因队列已空导致接收失败时调用。pxQueue 传入目标队列句柄。
traceTASK_DELAY_UNTIL()在 vTaskDelayUntil() 内部、调用任务进入阻塞态之前立即调用。
traceTASK_DELAY()在 vTaskDelay() 内部、调用任务进入阻塞态之前立即调用。

11.6.2定义跟踪钩子宏

每个跟踪宏都有默认空定义;可在 FreeRTOSConfig.h 中提供新的宏定义覆盖默认定义。若跟踪宏定义较长或较复杂,可在新头文件中实现,再由 FreeRTOSConfig.h 包含该头文件。

遵循软件工程最佳实践,FreeRTOS 维持严格的数据隐藏策略。跟踪宏允许把用户代码加入 FreeRTOS 源文件,因此跟踪宏可见的数据类型与应用代码可见的数据类型不同:

若跟踪宏直接访问通常为私有的 FreeRTOS 数据结构,必须极度谨慎:私有数据结构在不同 FreeRTOS 版本之间可能发生变化。

11.6.3FreeRTOS 感知调试器插件

以下 IDE 提供具备一定 FreeRTOS 感知能力的插件(此列表未必穷尽):

图 90 · Code Confidence Ltd. 提供的 FreeRTOS ThreadSpy Eclipse 插件
图 90 · Code Confidence Ltd. 提供的 FreeRTOS ThreadSpy Eclipse 插件