FreeRTOS中的FreeRTOSConfig 里那几个必须改的配置项

打开 CubeMX 生成的工程，你会找到一个FreeRTOSConfig.h（在 CubeMX 里对应FREERTOS → Config parameters）。这个文件里密密麻麻几十个宏，每个都控制着内核的一个开关或参数。

新手通常的做法是：全部保持默认，能跑就行。直到某天任务起不来、或者 RAM 不够、或者栈溢出没报警，才回头来翻这个文件。

这篇把FreeRTOSConfig.h里真正会影响你工程的十几个配置项挑出来，讲清楚每个填什么、填错的后果、F103C8 上的推荐值。这不是文档翻译，而是"哪些你必须懂、哪些可以忽略"的实战指南。

FreeRTOSConfig关键配置项分类

一、配置项分四类，先抓重点

FreeRTOSConfig.h里的几十个宏，按影响程度分四类：

下面逐类讲。所有推荐值针对F103C8（64K Flash / 20K RAM）。

二、资源类：决定 RAM/Flash 用量

这三个配置项直接决定 FreeRTOS 吃掉多少内存，必须懂。

1. configTOTAL_HEAP_SIZE —— 堆大小

#define configTOTAL_HEAP_SIZE ((size_t)3072)

作用：heap_4 动态分配的堆大小。所有osThreadNew、osMessageQueueNew等动态创建，都从这个堆里分。

填小的后果：任务/队列创建失败，osThreadNew返回 NULL，功能起不来。

填大的后果：挤占其它 RAM（栈、全局变量），严重时链接器报 "region RAM overflow"。

F103C8 推荐值：

怎么判断够不够：用xPortGetMinimumEverFreeHeapSize()查堆历史最小剩余（需开启configUSE_MALLOC_FAILED_HOOK）：

/** * @brief 查询堆剩余（字节） * @note 返回历史最小值，说明堆最紧张时刻还剩多少 */ size_t free_heap = xPortGetMinimumEverFreeHeapSize(); printf("[HEAP] min free = %u bytes\r\n", (unsigned)free_heap);

经验：堆剩余保持在总数的 20% 以上。低于 20% 说明快不够了，要么加堆、要么减少任务。

2. configMAX_PRIORITIES —— 最大优先级数

#define configMAX_PRIORITIES 7

作用：任务可用的优先级数量。优先级范围是 0 ~ (MAX_PRIORITIES - 1)。

填小的后果：想给某任务高优先级时没档位可用，任务都挤在低优先级，实时性差。

填大的后果：每级优先级要维护一个就绪链表，每级占一点 RAM（几十字节）。F103C8 上别超过 10。

推荐：7。对应 CMSIS-RTOS v2 的枚举档位（Low/BelowNormal/Normal/AboveNormal/High/Realtime 等）够用。

注意：这个数和 CMSIS-RTOS v2 的osPriority_t枚举值不是一回事。v2 枚举值是离散的大数字（如 osPriorityNormal=24），内核内部会映射到 0~MAX_PRIORITIES-1 的连续范围。

3. configMINIMAL_STACK_SIZE —— 空闲任务栈

#define configMINIMAL_STACK_SIZE ((uint16_t)64)

注意单位是字（word），不是字节！64 字 = 256 字节。

作用：空闲任务（Idle Task）和定时器服务任务的栈大小。这俩任务由内核自动创建，栈也由这个宏决定。

填小的后果：空闲任务栈溢出。如果你在空闲钩子里干了点活（比如统计、喂看门狗），更容易溢出。

填大的后果：浪费 RAM（两个任务都按这个值，共两份）。

F103C8 推荐：64 字（256 字节）。如果空闲钩子里有 printf，加到 128 字（512 字节）。

这是 FreeRTOS 为数不多的"以字为单位"的配置，和osThreadAttr_t.stack_size（字节）不同，容易搞混。记住：configMINIMAL_STACK_SIZE是字，osThreadNew的 stack_size 是字节。

三、安全类：开发期必开

这两个能在出问题时第一时间告诉你，开发阶段绝不能省。

4. configCHECK_FOR_STACK_OVERFLOW —— 栈溢出检测

#define configCHECK_FOR_STACK_OVERFLOW 2

作用：0关 / 1快检 / 2严检（第 07 篇详解过）。

开发期必开 = 2。检测到溢出会调用vApplicationStackOverflowHook，你可以在里面复位或记录。

为什么有人量产关掉：怕增加 CPU 开销。但实测开销极小（每次任务切换检查一次），量产也建议保持开启，比产品现场死机强。

5. configUSE_MALLOC_FAILED_HOOK —— 堆分配失败钩子

#define configUSE_MALLOC_FAILED_HOOK 1

作用：当 heap_4 分配失败（堆不够）时，内核调用vApplicationMallocFailedHook。

为什么重要：任务创建失败时，如果你没检查osThreadNew返回值，问题会变成"某个功能莫名其妙不工作"，极难定位。开这个钩子，分配失败立刻报警。

实现钩子：

/** * @brief 堆分配失败钩子 * @details 当 configTOTAL_HEAP_SIZE 不够、动态分配失败时被调用。 * 说明堆太小或任务/队列创建过多。 * @note 开发期在此打印诊断信息；量产可记录后复位。 */ void vApplicationMallocFailedHook(void) { printf("[FATAL] Heap alloc failed! configTOTAL_HEAP_SIZE too small?\r\n"); /* 可在此打印当前堆剩余辅助定位 */ }

黄金组合：configCHECK_FOR_STACK_OVERFLOW=2+configUSE_MALLOC_FAILED_HOOK=1，能覆盖 80% 的 RTOS 内存类 bug。

四、功能开关：按需启用

这些开关控制 FreeRTOS 的各种同步/通信机制。用到哪个开哪个，不用的关掉省 Flash。

关掉不用的功能能省多少 Flash？粗略参考：

F103C8 有 64K Flash，HAL 库吃掉一大半，能省就省。建议：一开始全开保证功能，功能稳定后，逐个关闭确认无影响，省出 Flash 空间。

五、内核细节：看一眼即可

这些通常 CubeMX 会帮你配好，但你要看得懂。

6. configTICK_RATE_HZ —— Tick 频率

#define configTICK_RATE_HZ 1000

作用：每秒多少个 Tick。本系列固定1000（1ms 一个 Tick）。

• • 填小（如 100）：osDelay 精度变 10ms，省点 CPU（Tick 中断少了），但实时性下降；

• • 填大（如 10000）：精度到 0.1ms，但 Tick 中断太频繁，CPU 开销上升。

1000 是大多数项目的平衡点。

7. configMAX_SYSCALL_INTERRUPT_PRIORITY —— 系统调用中断上限

#define configMAX_SYSCALL_INTERRUPT_PRIORITY 5

作用：只有优先级数值 ≥ 这个值的中断，才能调用FromISR系列 API（带系统调用的中断）。这是 FreeRTOS 的中断安全机制核心。

这个非常重要但容易搞反，本系列第三系列（中断篇）会专门讲。这里只需记住：数值大 = 优先级低（ARM Cortex-M 的反直觉规则）。设成 5，意思是优先级 515 的中断才能调 ISR API，04 的高优先级中断不能调。

填错的后果：要么高优先级中断调 API 导致崩溃，要么所有中断都不能调 API。

8. configCPU_CLOCK_HZ 和 configSYSTICK_CLOCK_HZ

#define configCPU_CLOCK_HZ 72000000UL

CubeMX 根据时钟树自动填，72MHz。一般不用手动改。

六、一个综合配置清单（F103C8 推荐起步值）

把上面汇总成一张表，新建 F103C8 工程时直接照着设：

在 CubeMX 里设置

这些在Middleware → FREERTOS → Config parameters里都能找到对应项。CubeMX 改完后重新生成代码，会自动更新FreeRTOSConfig.h。

重要：不要直接手动改FreeRTOSConfig.h！因为下次 CubeMX 重新生成会覆盖你的修改。所有配置改动都要在 CubeMX 界面里做。CubeMX 会在文件里标注/* USER CODE BEGIN *//* USER CODE END */区域，只有这些区域里的手改才不会被覆盖。

七、验证：打印配置确认生效

写一个小任务，启动后打印当前关键配置，确认 CubeMX 的设置真的生效了：

/** * @file config_check.c * @brief 打印当前 FreeRTOS 配置，确认生效 * @date 2026-07-15 * @version V1.0 - 初版创建 */ #include "cmsis_os2.h" #include <stdio.h> /** * @brief 配置自检任务 * @details 打印内核版本、tick 频率、当前任务数，确认环境正确 */ static void ConfigCheckTask(void *argument) { (void)argument; for (;;) { printf("=== FreeRTOS Config ===\r\n"); printf("Tick freq : %lu Hz\r\n", (unsigned long)osKernelGetTickFreq()); printf("Kernel state : %d\r\n", (int)osKernelGetState()); printf("Current tick : %lu\r\n", (unsigned long)osKernelGetTickCount()); printf("Heap min free: %u bytes\r\n", (unsigned)xPortGetMinimumEverFreeHeapSize()); printf("=======================\r\n"); osDelay(5000); } }

串口结果

=== FreeRTOS Config === Tick freq : 1000 Hz Kernel state : 2 Current tick : 5000 Heap min free: 1432 bytes =======================

串口设置：USART1，115200-8-N-1。观察点：

1. 1.Tick freq = 1000确认configTICK_RATE_HZ=1000生效；

2. 2.Kernel state = 2即osKernelRunning，说明调度器在跑；

3. 3.Heap min free = 1432说明堆 3072 里历史最少剩 1432，用了约 1640，余量充足。

如果Heap min free很小（如只剩几十字节），说明堆快不够，要加大configTOTAL_HEAP_SIZE。

八、本篇要点回顾

1. 1.FreeRTOSConfig.h几十个宏，重点抓三类：资源类（堆/优先级/栈）、安全类（栈溢出检测/堆失败钩子）、功能开关。

2. 2.资源类：configTOTAL_HEAP_SIZE（F103C8 起步 3KB）、configMAX_PRIORITIES（7）、configMINIMAL_STACK_SIZE（64 字）。

3. 3.安全类：configCHECK_FOR_STACK_OVERFLOW=2、configUSE_MALLOC_FAILED_HOOK=1，开发期必开。

4. 4.功能开关：用哪个开哪个，不用的（递归互斥量、队列集）可关，省 Flash。

5. 5.改配置必须在 CubeMX 界面改，不要手改 FreeRTOSConfig.h（会被重新生成覆盖）。

6. 6. 用xPortGetMinimumEverFreeHeapSize监控堆剩余，低于 20% 要警惕。

总结

FreeRTOS 的强大与灵活，很大程度来自这个配置文件。理解了这十几个关键宏，你就能针对 F103C8 的资源约束做精准裁剪——既能保证功能完整，又不会被默认值浪费宝贵的 RAM/Flash。