第 7 章 · 原书 328–352 页内核配置
FreeRTOS 的全部可配置项集中在一个头文件里:FreeRTOSConfig.h。它是应用侧的头文件(不属于内核源码),在编译时被 FreeRTOS.h 包含,因此每一项都必须在包含 FreeRTOS.h 之前生效。
本章分三块:
- 7.1 FreeRTOSConfig.h
- 7.2 INCLUDE_ 常量
- 7.3 config 常量
7.1FreeRTOSConfig.h
FreeRTOSConfig.h 是应用提供给内核的“编译期配置表”。内核源码里的 FreeRTOS.h 会先包含它,然后按其中的宏决定编译哪些代码、缓冲区多大、任务优先级怎么算。
7.1.1文件位置与包含关系
- 它必须位于编译器能搜索到的头文件路径中,通常放在应用工程的 Inc/ 或 Config/ 目录下。
- 内核的 portable.h、FreeRTOS.h 会
#include "FreeRTOSConfig.h",所以它不能依赖任何内核头文件。 - 它通常会包含目标芯片的设备头文件(如 stm32f10x.h),以便引用中断优先级宏。
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写配置时的四个工程坑点
- configPRIO_BITS 必须与芯片实际实现的优先级位数一致(Cortex-M3/M4 常见为 0x04)。它由 CMSIS 的 core_cm3.h 提供,若未包含设备头文件就会编译报错。
- configMAX_SYSCALL_INTERRUPT_PRIORITY 一旦配错(配得太低,即数值太小),会在中断里调用 FromISR 系列函数时触发 configASSERT 死循环,表现为“一进中断就卡死”。
- configTOTAL_HEAP_SIZE 是按字节计的堆总容量,所有任务栈、队列、信号量都从这里分配;给小了会在运行期返回 NULL,而不是编译期报错。
- 没有 configASSERT 时很多错误会静默放过,建议在开发阶段始终定义一个会停机的 configASSERT。
#define INCLUDE_xx 1 的集中块管理 API 裁剪,修改时不要只改一半。7.2INCLUDE_ 常量
这类常量并不改变内核行为,只决定某个 API 是否被编译进来。置 0(或不定义)时,对应函数在源码里被条件编译裁掉,链接后代码体积就更小。这是重要的 Flash 优化手段。
| 常量 | 置 1 后可用的 API | 说明 |
|---|---|---|
| INCLUDE_vTaskPrioritySet | vTaskPrioritySet() | 运行期改优先级 |
| INCLUDE_uxTaskPriorityGet | uxTaskPriorityGet() | 读取任务优先级 |
| INCLUDE_vTaskDelete | vTaskDelete() | 删除任务 |
| INCLUDE_vTaskSuspend | vTaskSuspend() / vTaskResume() / xTaskResumeFromISR() / vTaskSuspendAll() / xTaskResumeAll() | 挂起/恢复;同时是 portMAX_DELAY 无限等待生效的前提 |
| INCLUDE_xTaskResumeFromISR | xTaskResumeFromISR() | 单独控制中断里恢复任务 |
| INCLUDE_eTaskGetState | eTaskGetState() | 查询任务状态 |
| INCLUDE_xTaskGetCurrentTaskHandle | xTaskGetCurrentTaskHandle() | 取当前任务句柄 |
| INCLUDE_xTaskGetHandle | xTaskGetHandle() | 按名字查任务句柄 |
| INCLUDE_xTaskGetIdleTaskHandle | xTaskGetIdleTaskHandle() | 取空闲任务句柄 |
| INCLUDE_xTaskGetSchedulerState | xTaskGetSchedulerState() | 查询调度器状态 |
| INCLUDE_uxTaskGetStackHighWaterMark | uxTaskGetStackHighWaterMark() | 栈水位统计(找栈溢出最有效的手段) |
| INCLUDE_xTaskAbortDelay | xTaskAbortDelay() | 强制打断任务的阻塞等待 |
| INCLUDE_xSemaphoreGetMutexHolder | xSemaphoreGetMutexHolder() | 查询互斥量持有者 |
| INCLUDE_xQueueGetMutexHolder | xQueueGetMutexHolder() | 旧接口,查询互斥量持有者 |
| INCLUDE_xTaskGetSchedulerState | xTaskGetSchedulerState() | 调度器是否已启动/挂起 |
| INCLUDE_xTimerPendFunctionCall | xTimerPendFunctionCall() / xTimerPendFunctionCallFromISR() | 需 configUSE_TIMERS 为 1 |
| INCLUDE_xEventGroupSetBitsFromISR | xEventGroupSetBitsFromISR() | 需 configUSE_TIMERS 为 1 |
| INCLUDE_pcTaskGetTaskName | pcTaskGetTaskName() | 按句柄取任务名(V8 起并入 xTaskGetName) |
7.3config 常量
这一类常量决定内核的实际行为与资源上限。下表先给出全景,随后对影响最大的几项单独说明。
| 常量 | 典型取值 | 作用 |
|---|---|---|
| configUSE_PREEMPTION | 1 | 1 = 抢占式调度;0 = 协作式(任务必须主动让出) |
| configUSE_TIME_SLICING | 1 | 同优先级任务是否按时间片轮转 |
| configUSE_PORT_OPTIMISED_TASK_SELECTION | 依移植 | 用硬件指令(如前导零计数)加速“找最高优先级就绪任务” |
| configUSE_TICKLESS_IDLE | 0 | 低功耗:空闲时停止节拍中断 |
| configCPU_CLOCK_HZ | 芯片主频 | 节拍与延时的计算基准 |
| configTICK_RATE_HZ | 1000 | 每秒节拍数,决定最小延时粒度 |
| configMAX_PRIORITIES | 5~32 | 优先级级数,0 最低;数值越大 RAM 开销越大(每个优先级一个就绪链表) |
| configMINIMAL_STACK_SIZE | 128 | 空闲任务栈深度(单位:字,不是字节) |
| configMAX_TASK_NAME_LEN | 16 | 任务名字符数(含结尾 0) |
| configUSE_16_BIT_TICKS | 0 | 节拍类型宽度;影响事件组可用位数(见第 6 章) |
| configIDLE_SHOULD_YIELD | 1 | 空闲任务是否对同优先级任务让出 CPU |
| configUSE_MUTEXES | 1 | 启用互斥量(含优先级继承) |
| configUSE_RECURSIVE_MUTEXES | 1 | 启用递归互斥量 |
| configUSE_COUNTING_SEMAPHORES | 1 | 启用计数信号量 |
| configUSE_QUEUE_SETS | 0/1 | 启用队列集 |
| configUSE_TASK_NOTIFICATIONS | 1 | 启用任务通知(默认 1,强烈建议保留) |
| configUSE_TRACE_FACILITY | 0 | 启用可视化追踪;vTaskList()/uxTaskGetSystemState() 的前提 |
| configUSE_STATS_FORMATTING_FUNCTIONS | 0 | vTaskList()/vTaskGetRunTimeStats() 的格式化输出 |
| configGENERATE_RUN_TIME_STATS | 0 | 生成运行时间统计(需要额外的定时器/计数器) |
| configQUEUE_REGISTRY_SIZE | 0~ | 队列/信号量注册表容量,供调试器查看 |
| configCHECK_FOR_STACK_OVERFLOW | 0/1/2 | 栈溢出检测,1 = 只查栈指针越界,2 = 额外查栈尾魔数 |
| configUSE_MALLOC_FAILED_HOOK | 0/1 | 动态内存分配失败时回调 |
| configUSE_IDLE_HOOK | 0/1 | 空闲任务钩子 |
| configUSE_TICK_HOOK | 0/1 | 每个节拍中断的钩子 |
| configUSE_DAEMON_TASK_STARTUP_HOOK | 0/1 | 定时器服务任务首次运行前的钩子 |
| configTOTAL_HEAP_SIZE | 字节数 | FreeRTOS 堆总容量(heap_1~heap_5 都依赖它) |
| configSUPPORT_DYNAMIC_ALLOCATION | 1 | 允许 xTaskCreate/xQueueCreate 等动态创建 API |
| configSUPPORT_STATIC_ALLOCATION | 0/1 | 允许 *Static 系列静态创建 API |
| configNUM_THREAD_LOCAL_STORAGE_POINTERS | 0~ | 每个任务的线程局部存储指针个数 |
| configMAX_SYSCALL_INTERRUPT_PRIORITY | 依芯片 | 可调用 FreeRTOS API 的最高中断优先级门槛 |
| configUSE_TIMERS | 0/1 | 启用软件定时器(并自动创建定时器服务任务) |
| configTIMER_TASK_PRIORITY | 高优先级 | 定时器服务任务优先级 |
| configTIMER_QUEUE_LENGTH | 10 | 定时器命令队列长度 |
| configTIMER_TASK_STACK_DEPTH | 字节 or 字 | 定时器服务任务栈深(折算方式随移植层而定,注意单位) |
7.3.1configUSE_PREEMPTION 与 configUSE_TIME_SLICING
configUSE_PREEMPTION = 1 时,只要有更高优先级任务就绪,内核会立刻抢占当前任务;这是绝大多数应用需要的模式。置 0 后变为协作式:高优先级任务就绪也必须等当前任务主动调用阻塞类 API(如 vTaskDelay)或被中断唤醒后才能运行,实时性大幅下降。
configUSE_TIME_SLICING 仅在抢占模式下有意义:同优先级的多个就绪任务会按节拍轮流执行;置 0 后同优先级任务之间不会因节拍而切换(只有阻塞/让出才切换),可减少上下文切换开销。
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 开销越大。
7.3.4configMINIMAL_STACK_SIZE
空闲任务的栈深度。单位是字(StackType_t 的个数),不是字节;在 32 位平台上 128 字 = 512 字节。它同时被用作“最小可接受栈深”的参考值,许多工程用 configMINIMAL_STACK_SIZE * 2 之类的表达式配置其它任务的栈。
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 并由应用自己提供控制块。
7.3.6configUSE_TIMERS 与三项定时器参数
configUSE_TIMERS = 1 时,内核在 vTaskStartScheduler() 里自动创建定时器服务任务(daemon task)。三个配套项共同决定它的优先级、栈深与命令队列容量。
- configTIMER_TASK_PRIORITY 一般设为较高优先级,以保证回调及时执行;但过高会挤压业务任务。
- configTIMER_QUEUE_LENGTH 决定能同时排多少条定时器命令(Start/Stop/Reset/ChangePeriod/Delete/Pend)。中断里频繁操作定时器时需加大。
- configTIMER_TASK_STACK_DEPTH 要按回调的实际开销给足,回调里做打印/浮点运算要额外留量。
7.3.7configCHECK_FOR_STACK_OVERFLOW
栈溢出检测有两档:1 只在任务切换时检查栈指针是否已越出分配区域(快但可能漏);2 额外在任务创建与切换时校验栈尾的已知魔数是否被改写(覆盖面更大,仍有漏检可能)。
检测到溢出会调用钩子函数 vApplicationStackOverflowHook( xTaskHandle xTask, signed char *pcTaskName ),默认实现通常是死循环。开发阶段务必实现这个钩子,并记录任务名。
7.3.8configMAX_SYSCALL_INTERRUPT_PRIORITY
这一项与 Cortex-M 的中断优先级机制强绑定,是最容易配错的一项。它的含义是:优先级数值 ≥ 该值的中断,允许调用 FreeRTOS 的 FromISR API,并且会被内核的临界区屏蔽;优先级数值小于该值(即更紧急)的中断不受内核管理,绝对不能调用任何 FreeRTOS API。
数值通常由“逻辑优先级”左移得到:configLIBRARY_MAX_SYSCALL_INTERRUPT_PRIORITY << (8 - configPRIO_BITS)。Cortex-M 的优先级是数值越小越紧急,且只有高位有效。
7.3.9configUSE_TICKLESS_IDLE
低功耗模式下,空闲期间内核会停止周期节拍中断,按“下一个到期事件”的时间睡眠,醒来后再补算节拍。可显著降低平均功耗,但需要移植层支持(如 Cortex-M 的 tickless 实现依赖一个低功耗定时器)。
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_HOOK | vApplicationIdleHook() | 空闲任务每次循环 |
| configUSE_TICK_HOOK | vApplicationTickHook() | 每个节拍中断(必须极短,且在中断上下文) |
| configUSE_MALLOC_FAILED_HOOK | vApplicationMallocFailedHook() | pvPortMalloc 失败 |
| configUSE_DAEMON_TASK_STARTUP_HOOK | vApplicationDaemonTaskStartupHook() | 定时器服务任务首次运行前 |
| configCHECK_FOR_STACK_OVERFLOW | vApplicationStackOverflowHook() | 检测到栈溢出 |