4. FreeRTOSConfig.h 配置文件详解

好，咱们今天来聊聊 FreeRTOSConfig.h 这个文件。说实话，很多初学者觉得它就是个“配置头文件”，随便改改就能用。但我告诉你，这里面的每一个宏定义，都直接决定了你的系统能不能稳定跑起来。

我个人习惯，拿到一个新的 MCU 工程，第一件事就是打开这个文件，逐行过一遍。为什么？因为这里埋的坑，比 RTOS 内核本身还多。你想想看，时钟配错了，系统 tick 就乱套；堆大小设小了，任务创建直接失败。嗯，咱们今天就一条一条把它讲透。

4.1 核心时钟与 Tick 配置

先看两个最基础的宏：

#define configCPU_CLOCK_HZ    ( ( unsigned long ) 168000000 )
#define configTICK_RATE_HZ    ( ( TickType_t ) 1000 )

configCPU_CLOCK_HZ 是 CPU 的主频。我用的 STM32F407，主频 168MHz，所以这里写 168000000。你如果用 F103，那就是 72000000。这个值必须跟你的系统时钟配置一致，否则 FreeRTOS 内部的时间计算全都会错。

我曾经遇到一个项目，同事把这里写成了 72MHz，但实际 PLL 配的是 168MHz。结果呢？系统 tick 快了将近一倍，所有延时函数都缩水了。排查了两天才找到问题，你说冤不冤？

configTICK_RATE_HZ 是系统心跳频率。我一般设 1000Hz，也就是 1ms 一个 tick。这个值越大，调度精度越高，但中断开销也越大。如果你做低功耗应用，设 100Hz 就够了，省电。

4.2 堆大小配置

#define configTOTAL_HEAP_SIZE    ( ( size_t ) 1024 * 50 )

这个宏定义的是 FreeRTOS 内部管理的堆大小。说白了，你创建任务、队列、信号量，都是从这块堆里分配内存的。

我建议新手先设大一点，比如 50KB。等系统跑起来之后，用 vPortGetFreeHeapSize() 看看实际用了多少，再慢慢往下调。我见过有人一上来就设 10KB，结果任务创建失败，还以为是内核有问题。

4.3 任务与调度配置

#define configMAX_PRIORITIES        ( 5 )
#define configMINIMAL_STACK_SIZE    ( ( unsigned short ) 128 )
#define configMAX_TASK_NAME_LEN     ( 16 )

configMAX_PRIORITIES 是最大优先级数。FreeRTOS 的优先级数值越大，优先级越高。我一般设 5 到 10 个优先级就够了。设太多反而浪费 RAM，因为每个优先级都要维护一个就绪列表。

configMINIMAL_STACK_SIZE 是空闲任务的栈大小。128 个字（不是字节）通常够用。但如果你在空闲任务钩子里做了复杂操作，记得加大。

configMAX_TASK_NAME_LEN 是任务名字符串长度。16 字节够写个“LED_Task”之类的名字了。别设太大，每个任务都要占这个空间。

4.4 功能裁剪宏

#define configUSE_PREEMPTION        1
#define configUSE_IDLE_HOOK         0
#define configUSE_TICK_HOOK         0
#define configUSE_CO_ROUTINES       0
#define configUSE_MUTEXES           1

这些宏是用来裁剪 FreeRTOS 功能的。说白了，用不上的功能就关掉，省 RAM 省 Flash。

• configUSE_PREEMPTION：1 表示抢占式调度，0 表示协作式。我从来只用抢占式，协作式在实际项目中基本没用。
• configUSE_IDLE_HOOK 和 configUSE_TICK_HOOK：这两个钩子函数，我一般关掉。除非你真的需要在空闲时做低功耗处理，或者在 tick 中断里做统计。
• configUSE_CO_ROUTINES：协程，老古董了，直接关掉。
• configUSE_MUTEXES：互斥量，这个我建议打开。项目中用到共享资源的地方太多了。

4.5 中断与临界区配置

#define configLIBRARY_LOWEST_INTERRUPT_PRIORITY    15
#define configLIBRARY_MAX_SYSCALL_INTERRUPT_PRIORITY 5
#define configKERNEL_INTERRUPT_PRIORITY             ( configLIBRARY_LOWEST_INTERRUPT_PRIORITY << 4 )
#define configMAX_SYSCALL_INTERRUPT_PRIORITY        ( configLIBRARY_MAX_SYSCALL_INTERRUPT_PRIORITY << 4 )

这部分是 STM32 移植最关键的配置。STM32 的中断优先级是 4 位，所以数值范围是 0-15。数值越小，优先级越高。

configLIBRARY_LOWEST_INTERRUPT_PRIORITY 是系统能屏蔽的最低优先级。我设 15，也就是最低优先级。

configLIBRARY_MAX_SYSCALL_INTERRUPT_PRIORITY 是能调用 FreeRTOS API 的最高中断优先级。我设 5，意思是优先级 0-4 的中断可以打断 FreeRTOS 的临界区，但优先级 5-15 的中断不行。

我记得有一次，一个定时器中断优先级设成了 3，里面调用了 xQueueSendFromISR。结果系统跑着跑着就死机了。查了半天才发现是优先级冲突。从那以后，我所有调用 FreeRTOS API 的中断，优先级统一设成 5 或更低。

4.6 其他实用配置

#define INCLUDE_vTaskDelay            1
#define INCLUDE_xTaskDelayUntil       1
#define INCLUDE_vTaskDelete           1
#define INCLUDE_xSemaphoreTake        1
#define INCLUDE_xQueueSend            1

这些 INCLUDE 开头的宏，控制哪些 API 函数被编译进固件。用不到的可以关掉，省 Flash 空间。

我一般把 vTaskDelay、xTaskDelayUntil、vTaskDelete 都打开。调试阶段方便，正式发布时再酌情裁剪。

4.7 一个完整的配置示例

最后，给你一个我常用的配置模板，直接复制过去改改就能用：

#define configCPU_CLOCK_HZ                ( 168000000 )
#define configTICK_RATE_HZ                ( 1000 )
#define configTOTAL_HEAP_SIZE             ( 50 * 1024 )
#define configMAX_PRIORITIES              ( 5 )
#define configMINIMAL_STACK_SIZE          ( 128 )
#define configMAX_TASK_NAME_LEN           ( 16 )
#define configUSE_PREEMPTION              1
#define configUSE_IDLE_HOOK               0
#define configUSE_TICK_HOOK               0
#define configUSE_CO_ROUTINES             0
#define configUSE_MUTEXES                 1
#define configLIBRARY_LOWEST_INTERRUPT_PRIORITY      15
#define configLIBRARY_MAX_SYSCALL_INTERRUPT_PRIORITY 5
#define configKERNEL_INTERRUPT_PRIORITY   ( 15 << 4 )
#define configMAX_SYSCALL_INTERRUPT_PRIORITY ( 5 << 4 )
#define INCLUDE_vTaskDelay                1
#define INCLUDE_xTaskDelayUntil           1
#define INCLUDE_vTaskDelete               1
#define INCLUDE_xSemaphoreTake            1
#define INCLUDE_xQueueSend                1

嗯，这个配置我用了好几年，从 F103 到 F407 再到 H743，基本没出过问题。你照着这个改，至少能省掉一半的调试时间。

好了，FreeRTOSConfig.h 的核心配置就这些。下一章咱们开始动手写移植代码，到时候你会真正理解这些配置是怎么起作用的。