FreeRTOS 中文参考手册 /7 内核配置

第 7 章 · 原书 328–352 页内核配置

Chapter 7 · Kernel Configuration

FreeRTOS 的全部可配置项集中在一个头文件里:FreeRTOSConfig.h。它是应用侧的头文件(不属于内核源码),在编译时被 FreeRTOS.h 包含,因此每一项都必须在包含 FreeRTOS.h 之前生效。

本章分三块:

改配置之后必须重新编译内核所在的全部源文件。很多“改了配置却没生效”的情况,都是因为目标文件没有重编(尤其是把 config 放在工程全局宏里、又只增量编译了应用文件)。

7.1FreeRTOSConfig.h

FreeRTOSConfig.h 是应用提供给内核的“编译期配置表”。内核源码里的 FreeRTOS.h 会先包含它,然后按其中的宏决定编译哪些代码、缓冲区多大、任务优先级怎么算。

7.1.1文件位置与包含关系

7.1.2一份最小可用的配置示例

#ifndef FREERTOS_CONFIG_H
#define FREERTOS_CONFIG_H

#include "stm32f10x.h"          /* 用于引用 NVIC 优先级位数 */

#define configUSE_PREEMPTION              1
#define configUSE_TIME_SLICING            1
#define configUSE_IDLE_HOOK               0
#define configUSE_TICK_HOOK               0
#define configCPU_CLOCK_HZ                ( ( unsigned long ) 72000000 )
#define configTICK_RATE_HZ                ( ( TickType_t ) 1000 )
#define configMAX_PRIORITIES              ( 7 )
#define configMINIMAL_STACK_SIZE          ( ( unsigned short ) 128 )
#define configTOTAL_HEAP_SIZE             ( ( size_t ) ( 20 * 1024 ) )
#define configMAX_TASK_NAME_LEN           ( 16 )
#define configUSE_TRACE_FACILITY          0
#define configUSE_16_BIT_TICKS            0
#define configIDLE_SHOULD_YIELD           1
#define configUSE_MUTEXES                 1
#define configQUEUE_REGISTRY_SIZE         8
#define configCHECK_FOR_STACK_OVERFLOW    2
#define configUSE_RECURSIVE_MUTEXES       1
#define configUSE_MALLOC_FAILED_HOOK      0
#define configUSE_COUNTING_SEMAPHORES     1
#define configUSE_TIMERS                  1
#define configTIMER_TASK_PRIORITY         ( configMAX_PRIORITIES - 1 )
#define configTIMER_QUEUE_LENGTH          10
#define configTIMER_TASK_STACK_DEPTH      ( configMINIMAL_STACK_SIZE * 2 )

/* Cortex-M: 中断优先级配置,见 7.3 说明 */
#define configLIBRARY_MAX_SYSCALL_INTERRUPT_PRIORITY   5
#define configMAX_SYSCALL_INTERRUPT_PRIORITY \
        ( configLIBRARY_MAX_SYSCALL_INTERRUPT_PRIORITY << (8 - configPRIO_BITS) )

#define configASSERT( x ) if( ( x ) == 0 ) { taskDISABLE_INTERRUPTS(); for( ;; ); }

#define INCLUDE_vTaskPrioritySet          1
#define INCLUDE_uxTaskPriorityGet         1
#define INCLUDE_vTaskDelete               1
#define INCLUDE_vTaskSuspend              1
#define INCLUDE_vTaskDelayUntil           1
#define INCLUDE_vTaskDelay                1

#endif

7.1.3写配置时的四个工程坑点

很多移植工程(尤其 CubeMX 生成的 FreeRTOSConfig.h)在文件末尾用 #define INCLUDE_xx 1 的集中块管理 API 裁剪,修改时不要只改一半。

7.2INCLUDE_ 常量

这类常量并不改变内核行为,只决定某个 API 是否被编译进来。置 0(或不定义)时,对应函数在源码里被条件编译裁掉,链接后代码体积就更小。这是重要的 Flash 优化手段。

常量置 1 后可用的 API说明
INCLUDE_vTaskPrioritySetvTaskPrioritySet()运行期改优先级
INCLUDE_uxTaskPriorityGetuxTaskPriorityGet()读取任务优先级
INCLUDE_vTaskDeletevTaskDelete()删除任务
INCLUDE_vTaskSuspendvTaskSuspend() / vTaskResume() / xTaskResumeFromISR() / vTaskSuspendAll() / xTaskResumeAll()挂起/恢复;同时是 portMAX_DELAY 无限等待生效的前提
INCLUDE_xTaskResumeFromISRxTaskResumeFromISR()单独控制中断里恢复任务
INCLUDE_eTaskGetStateeTaskGetState()查询任务状态
INCLUDE_xTaskGetCurrentTaskHandlexTaskGetCurrentTaskHandle()取当前任务句柄
INCLUDE_xTaskGetHandlexTaskGetHandle()按名字查任务句柄
INCLUDE_xTaskGetIdleTaskHandlexTaskGetIdleTaskHandle()取空闲任务句柄
INCLUDE_xTaskGetSchedulerStatexTaskGetSchedulerState()查询调度器状态
INCLUDE_uxTaskGetStackHighWaterMarkuxTaskGetStackHighWaterMark()栈水位统计(找栈溢出最有效的手段)
INCLUDE_xTaskAbortDelayxTaskAbortDelay()强制打断任务的阻塞等待
INCLUDE_xSemaphoreGetMutexHolderxSemaphoreGetMutexHolder()查询互斥量持有者
INCLUDE_xQueueGetMutexHolderxQueueGetMutexHolder()旧接口,查询互斥量持有者
INCLUDE_xTaskGetSchedulerStatexTaskGetSchedulerState()调度器是否已启动/挂起
INCLUDE_xTimerPendFunctionCallxTimerPendFunctionCall() / xTimerPendFunctionCallFromISR()需 configUSE_TIMERS 为 1
INCLUDE_xEventGroupSetBitsFromISRxEventGroupSetBitsFromISR()需 configUSE_TIMERS 为 1
INCLUDE_pcTaskGetTaskNamepcTaskGetTaskName()按句柄取任务名(V8 起并入 xTaskGetName)
INCLUDE_vTaskSuspend 是隐形关键项:你即使不挂起任何任务,只要想用 portMAX_DELAY 做“无限等待”,也必须把它置 1;否则无限等待会被当成“等待 0xFFFFFFFF 个节拍”,仍会超时返回。

7.3config 常量

这一类常量决定内核的实际行为与资源上限。下表先给出全景,随后对影响最大的几项单独说明。

常量典型取值作用
configUSE_PREEMPTION11 = 抢占式调度;0 = 协作式(任务必须主动让出)
configUSE_TIME_SLICING1同优先级任务是否按时间片轮转
configUSE_PORT_OPTIMISED_TASK_SELECTION依移植用硬件指令(如前导零计数)加速“找最高优先级就绪任务”
configUSE_TICKLESS_IDLE0低功耗:空闲时停止节拍中断
configCPU_CLOCK_HZ芯片主频节拍与延时的计算基准
configTICK_RATE_HZ1000每秒节拍数,决定最小延时粒度
configMAX_PRIORITIES5~32优先级级数,0 最低;数值越大 RAM 开销越大(每个优先级一个就绪链表)
configMINIMAL_STACK_SIZE128空闲任务栈深度(单位:字,不是字节)
configMAX_TASK_NAME_LEN16任务名字符数(含结尾 0)
configUSE_16_BIT_TICKS0节拍类型宽度;影响事件组可用位数(见第 6 章)
configIDLE_SHOULD_YIELD1空闲任务是否对同优先级任务让出 CPU
configUSE_MUTEXES1启用互斥量(含优先级继承)
configUSE_RECURSIVE_MUTEXES1启用递归互斥量
configUSE_COUNTING_SEMAPHORES1启用计数信号量
configUSE_QUEUE_SETS0/1启用队列集
configUSE_TASK_NOTIFICATIONS1启用任务通知(默认 1,强烈建议保留)
configUSE_TRACE_FACILITY0启用可视化追踪;vTaskList()/uxTaskGetSystemState() 的前提
configUSE_STATS_FORMATTING_FUNCTIONS0vTaskList()/vTaskGetRunTimeStats() 的格式化输出
configGENERATE_RUN_TIME_STATS0生成运行时间统计(需要额外的定时器/计数器)
configQUEUE_REGISTRY_SIZE0~队列/信号量注册表容量,供调试器查看
configCHECK_FOR_STACK_OVERFLOW0/1/2栈溢出检测,1 = 只查栈指针越界,2 = 额外查栈尾魔数
configUSE_MALLOC_FAILED_HOOK0/1动态内存分配失败时回调
configUSE_IDLE_HOOK0/1空闲任务钩子
configUSE_TICK_HOOK0/1每个节拍中断的钩子
configUSE_DAEMON_TASK_STARTUP_HOOK0/1定时器服务任务首次运行前的钩子
configTOTAL_HEAP_SIZE字节数FreeRTOS 堆总容量(heap_1~heap_5 都依赖它)
configSUPPORT_DYNAMIC_ALLOCATION1允许 xTaskCreate/xQueueCreate 等动态创建 API
configSUPPORT_STATIC_ALLOCATION0/1允许 *Static 系列静态创建 API
configNUM_THREAD_LOCAL_STORAGE_POINTERS0~每个任务的线程局部存储指针个数
configMAX_SYSCALL_INTERRUPT_PRIORITY依芯片可调用 FreeRTOS API 的最高中断优先级门槛
configUSE_TIMERS0/1启用软件定时器(并自动创建定时器服务任务)
configTIMER_TASK_PRIORITY高优先级定时器服务任务优先级
configTIMER_QUEUE_LENGTH10定时器命令队列长度
configTIMER_TASK_STACK_DEPTH字节 or 字定时器服务任务栈深(折算方式随移植层而定,注意单位)

7.3.1configUSE_PREEMPTION 与 configUSE_TIME_SLICING

configUSE_PREEMPTION = 1 时,只要有更高优先级任务就绪,内核会立刻抢占当前任务;这是绝大多数应用需要的模式。置 0 后变为协作式:高优先级任务就绪也必须等当前任务主动调用阻塞类 API(如 vTaskDelay)或被中断唤醒后才能运行,实时性大幅下降。

configUSE_TIME_SLICING 仅在抢占模式下有意义:同优先级的多个就绪任务会按节拍轮流执行;置 0 后同优先级任务之间不会因节拍而切换(只有阻塞/让出才切换),可减少上下文切换开销。

把 configUSE_TIME_SLICING 置 0 而代码又依赖“同优先级轮转”时,会表现为某个任务把 CPU 吃满、其它同优先级任务永远轮不到——排查调度顺序时先看这一项。

7.3.2configTICK_RATE_HZ

节拍频率决定一切延时/超时的时间分辨率。1000 Hz 即 1 ms 一个节拍;过低(如 100 Hz)会让 vTaskDelay(1) 变成 10 ms,且超时判定粗糙;过高则节拍中断本身的开销变大。

vTaskDelayUntil() 用于周期性任务,节拍过粗会导致周期抖动被放大。换算宏 pdMS_TO_TICKS() 依赖 configTICK_RATE_HZ。

7.3.3configMAX_PRIORITIES

优先级范围是 0 ~ configMAX_PRIORITIES-1,数值越大优先级越高(与某些 RTOS 习惯相反,容易记错)。内核为每个优先级维护一个就绪链表,因此该值越大静态 RAM 开销越大。

调用 xTaskCreate() 时传入的优先级若 ≥ configMAX_PRIORITIES,会触发断言(若启用 configASSERT),否则会被裁到最大值。

7.3.4configMINIMAL_STACK_SIZE

空闲任务的栈深度。单位是字(StackType_t 的个数),不是字节;在 32 位平台上 128 字 = 512 字节。它同时被用作“最小可接受栈深”的参考值,许多工程用 configMINIMAL_STACK_SIZE * 2 之类的表达式配置其它任务的栈。

别把“字数”当“字节数”填。给 128 以为是 128 字节的人,往往在任务里调用 printf 或浮点运算就溢出了。

7.3.5configTOTAL_HEAP_SIZE 与两种分配方式

configTOTAL_HEAP_SIZE 定义了 FreeRTOS 私有堆的总字节数(heap_1/2/4/5 使用;heap_3 借用标准 malloc,不受它约束)。所有动态创建的 TCB、任务栈、队列、信号量都从这里切分。

configSUPPORT_DYNAMIC_ALLOCATION 与 configSUPPORT_STATIC_ALLOCATION 可以同时置 1;安全性要求高的项目(如需要 MISRA 或不允许动态内存)通常只开静态分配,用 *Static 系列 API 并由应用自己提供控制块。

开静态分配后,空闲任务与定时器服务任务的控制块、栈也需要应用通过 vApplicationGetIdleTaskMemory() / vApplicationGetTimerTaskMemory() 提供,否则链接会报未定义符号。

7.3.6configUSE_TIMERS 与三项定时器参数

configUSE_TIMERS = 1 时,内核在 vTaskStartScheduler() 里自动创建定时器服务任务(daemon task)。三个配套项共同决定它的优先级、栈深与命令队列容量。

7.3.7configCHECK_FOR_STACK_OVERFLOW

栈溢出检测有两档:1 只在任务切换时检查栈指针是否已越出分配区域(快但可能漏);2 额外在任务创建与切换时校验栈尾的已知魔数是否被改写(覆盖面更大,仍有漏检可能)。

检测到溢出会调用钩子函数 vApplicationStackOverflowHook( xTaskHandle xTask, signed char *pcTaskName ),默认实现通常是死循环。开发阶段务必实现这个钩子,并记录任务名。

栈溢出是嵌入式 RTOS 最常见的崩溃原因,而 configCHECK_FOR_STACK_OVERFLOW = 0 时它表现得像“随机跑飞”,很难定位。调试固件建议至少设为 2,配合 uxTaskGetStackHighWaterMark() 精确定容。

7.3.8configMAX_SYSCALL_INTERRUPT_PRIORITY

这一项与 Cortex-M 的中断优先级机制强绑定,是最容易配错的一项。它的含义是:优先级数值 ≥ 该值的中断,允许调用 FreeRTOS 的 FromISR API,并且会被内核的临界区屏蔽;优先级数值小于该值(即更紧急)的中断不受内核管理,绝对不能调用任何 FreeRTOS API。

数值通常由“逻辑优先级”左移得到:configLIBRARY_MAX_SYSCALL_INTERRUPT_PRIORITY << (8 - configPRIO_BITS)。Cortex-M 的优先级是数值越小越紧急,且只有高位有效。

典型故障:把 UART 中断优先级设成 0(最高),又在里面调用 xQueueSendFromISR(),结果触发 configASSERT 或数据错乱。正确做法是把所有会调用 FreeRTOS API 的中断优先级设在 configMAX_SYSCALL_INTERRUPT_PRIORITY 之下(数值更大)。

7.3.9configUSE_TICKLESS_IDLE

低功耗模式下,空闲期间内核会停止周期节拍中断,按“下一个到期事件”的时间睡眠,醒来后再补算节拍。可显著降低平均功耗,但需要移植层支持(如 Cortex-M 的 tickless 实现依赖一个低功耗定时器)。

tickless 打开后,节拍会“跳跃”,凡是假定“节拍严格每 1 ms 加 1”的业务(如软件 PWM、精确时间戳)都要重新验证。

7.3.10运行统计与可视化:configGENERATE_RUN_TIME_STATS / configUSE_TRACE_FACILITY

要使用 vTaskGetRunTimeStats(),必须同时开启 configGENERATE_RUN_TIME_STATS 与 configUSE_STATS_FORMATTING_FUNCTIONS,并实现两个端口宏:portCONFIGURE_TIMER_FOR_RUN_TIME_STATS()(配置一个比节拍频率高得多的计数器)与 portGET_RUN_TIME_COUNTER_VALUE()(返回该计数器当前值)。

要使用 vTaskList(),需要 configUSE_TRACE_FACILITY 与 configUSE_STATS_FORMATTING_FUNCTIONS。两者输出都是格式化文本,通常需要较大的栈与串口缓冲。

7.3.11钩子函数一览

配置项启用的钩子触发时机
configUSE_IDLE_HOOKvApplicationIdleHook()空闲任务每次循环
configUSE_TICK_HOOKvApplicationTickHook()每个节拍中断(必须极短,且在中断上下文)
configUSE_MALLOC_FAILED_HOOKvApplicationMallocFailedHook()pvPortMalloc 失败
configUSE_DAEMON_TASK_STARTUP_HOOKvApplicationDaemonTaskStartupHook()定时器服务任务首次运行前
configCHECK_FOR_STACK_OVERFLOWvApplicationStackOverflowHook()检测到栈溢出
节拍钩子运行在中断上下文里,只能用 FromISR 系列 API;在里面调用普通 API(如 xQueueSend)会破坏中断嵌套假设,表现为偶发死机。