简介：这是一份面向嵌入式学习者与开发者的 FreeRTOS 移植实验资源，基于 STM32F103 正点原子精英板，提供可直接复用的工程模板。压缩包共 196 个文件，约 3.7MB，主要包含 C 源文件、头文件、Keil 工程配置（uvprojx/uvoptx）以及编译生成的 axf/hex 等文件，适合在 Keil 环境下打开并烧录运行。已有 2847 人学习/下载。模板已将 FreeRTOS 内核、时钟与中断配置、内存管理等基础工作预置完成，并保留启动文件与外设驱动，使用者无需从头移植，只需按业务需求修改任务函数、调整优先级即可快速搭建多任务应用。同时，包内文件结构清晰，便于对照学习任务创建、队列、信号量等 RTOS 核心机制，也能帮助理解任务优先级分配和内存管理中的常见坑点。无论是入门 FreeRTOS 移植流程，还是在 STM32 平台上从裸机转向 RTOS 开发，这份资源都能提供清晰、精简的起步参考，适合作为课程实验或项目预研的基础模板。
1. 为什么 STM32F103 移植 FreeRTOS 值得有一份「拿来就用」的模板
很多人把 FreeRTOS 移植到 STM32F103 上的第一道坎并不是任务怎么写，而是系统根本起不来——点灯程序跑得好好的，加了系统之后直接掉进 HardFault，连个日志都没有。这套通用模板把内核源码、Cortex-M3 移植层、内存分配器和配置文件打包成一套可以直接覆盖到工程里的结构，目的就是让「拿到模板到两个任务交替运行」的路径压缩到一小时以内。它适合两类人：一类是刚接触 RTOS、想在 F103 上把多任务真正跑通的初学者；另一类是项目选型期需要快速验证「在 F103 上跑 FreeRTOS 到底行不行」的工程师。下面从移植的底层逻辑开始，逐步拆到配置、验证和排错。
2. FreeRTOS 移植的底层逻辑：文件结构、异常机制与内存方案三件事
这一章先不碰具体代码，把三件决定移植成败的事捋一遍：文件从哪里来、任务切换靠哪个中断、内存用哪个分配器。这三件事是后面所有配置和排错的底层依据，模板文件可以直接拿来用，但理解了它们之后，遇到问题才能定位而不是靠运气。
2.1 文件构成：哪些代码平台无关，哪些必须换成 Cortex-M3 版本
FreeRTOS 内核源码按职责可以切成三块。第一块是平台无关的内核本体：tasks.c 负责任务管理和调度，list.c 是内核内部使用的链表实现，queue.c 提供队列和信号量，event_groups.c 提供事件组，这些文件在 Cortex-M3、M4、M7 甚至 RISC-V 上都是同一份代码，不需要改动。第二块是移植层，核心文件是 port.c 和 portmacro.h，它们直接操作 CPU 寄存器、完成任务栈的初始化、触发 PendSV 异常，不同的内核和不同的编译器对应不同的实现。第三块是内存分配器，heap_1.c 到 heap_5.c 五选一放进工程。
F103 属于 Cortex-M3 内核，移植层应当取官方源码 portable 目录下对应 CM3 的那份。这里最容易翻车的是编译器匹配：同一套 CPU 内核，Keil 用的 RVDS 移植层和 GCC 移植层在内联汇编写法上差别很大，如果你从某个 GCC 工程里拷了 port.c 到 Keil 工程，编译期通常能过，但任务切换第一次触发时就会出诡异问题，而且表现得毫无规律，很像是玄学，实际就是汇编指令不匹配。我一般直接把官方源码包里对应编译器的那整个子目录拷过来，不单独挑文件，避免缺头文件路径。
启动文件和 FreeRTOS 也有一个容易被忽略的耦合点。启动文件里分配的 Stack_Size 是给主栈 MSP 用的，FreeRTOS 启动后每个任务跑在自己的私有栈上，用的是 PSP，两者独立。但 SysTick 中断和 PendSV 执行时仍然压栈到 MSP，所以启动文件的 Stack_Size 并不决定任务能占多深，它决定的是中断嵌套能有多深。如果你在中断里调用了比较重的处理，或者中断嵌套层数多，MSP 太小一样会爆栈复位。
还有一个容易出问题的点：任务栈的方向。Cortex-M3 的栈是向下生长的，FreeRTOS 在创建任务时会调用 pxPortInitialiseStack 把任务初始寄存器和入口地址按「从高地址往低地址」的顺序填进任务栈，并让 PSP 指向合适的位置。每个任务的栈顶地址必须按 8 字节对齐，如果不是，第一次上下文恢复时就容易触发总线错误。把任务栈声明成局部大数组时尤其容易出现对齐问题，我一般把任务栈放在全局区或者从 heap 里直接分配，交给编译器和对齐宏处理。
2.2 PendSV 与 SVC：为什么任务切换不放在定时器中断里做
裸机程序要实现「轮流执行」，常规做法是开一个定时器中断、在中断里置标志位、主循环见到标志再切换。FreeRTOS 的思路不同，它依赖 Cortex-M3 内核自带的两个系统异常：SVC 和 PendSV。SVC 是同步异常，执行 SVC 指令后会立即进入，FreeRTOS 用它来启动第一个任务。在第一个任务启动之前，系统还没有任何一个任务上下文在跑，必须借助 SVC 异常例程完成初始上下文的装载，这是整个系统从「裸机状态」切换到「任务状态」的入口。
PendSV 则是可以挂起的异常，它的特点是如果当前正有更高优先级的异常在响应，PendSV 会被挂起，等更高优先级异常退出后再执行。这个特性正适合抢占式调度。SysTick 时钟节拍一到，调度器判定需要切换任务时，并不在 SysTick 里直接做上下文切换，而是只把 PendSV 异常挂起。等 SysTick 中断返回，PendSV 才开始保存前一个任务的寄存器现场、恢复下一个任务的寄存器现场。这么设计的目的，是避免在中断里做复杂切换导致的中断嵌套和临界区混乱。
F103 移植里有一个配置因此变得极其关键：所有调用 FreeRTOS API 的中断，其优先级数值必须不小于 configMAX_SYSCALL_INTERRUPT_PRIORITY，而 PendSV 和 SysTick 必须设为最低优先级。F103 的 NVIC 优先级是 4 位，取值 0 到 15，数值越大优先级越低，所以这两个异常通常配成 15。如果把 SysTick 优先级设成 0，等于让时钟节拍打断一切，调度器在临界区里的保护逻辑会被击穿，系统表现为随机死机。这个问题在后面的排查章节会专门展开。
F103 移植层里还有一段和中断开关相关的代码需要留意。Cortex-M3 上关闭中断用的是 PRIMASK 寄存器，FreeRTOS 的 portENTER_CRITICAL 和 portEXIT_CRITICAL 在 RVDS 移植层里分别对应 CPSID I 和 CPSIE I 指令。这套机制保证临界区期间连 SysTick 都无法打断，从而保护调度链表的一致性。但临界区不能长时间停留，否则时钟节拍会被饿着，系统时间就不准了。
2.3 五种堆分配器怎么选：F103 模板为什么普遍默认 heap_4
FreeRTOS 提供的五种内存分配实现，本质上都是对一个大数组进行管理，区别在算法策略。heap_1 只分配不释放，适合任务数量固定、创建后永不删除的场景，优点是代码量最小、无碎片。heap_2 支持释放，但释放后不合并相邻空闲块，申请释放内存块大小参差时会慢慢产生不可用碎片。heap_3 是对 C 标准库 malloc/free 的封装，线程安全要自己保证，实际工程里很少直接用。heap_4 在 heap_2 的基础上增加了相邻空闲块合并和字节对齐，是官方文档推荐、也是多数 F103 模板的默认选择。heap_5 更进一步，能管理多个不连续的内存区域，适合 RAM 分布零散的大容量芯片，F103 这种单片小内存场景用不上。
heap_4 内部维护一条空闲块链表，每次分配都要遍历链表找尺寸匹配的空闲块，再把块切出来，剩余部分挂回链表。所以它本质上有 O(n) 复杂度的分配过程，实时性要求苛刻的中断服务函数里不适合直接创建任务或队列，应该在普通任务上下文里预分配。另外，heap_4 分配出去的内存地址会按 8 字节对齐，对 Cortex-M3 这种要求栈指针 8 字节对齐的内核来说是必要的。
模板要兼顾「通用」两个字，面对的场景是任务可能动态创建、信号量和消息队列可能动态分配，所以 heap_4 是容错性最好的选择。需要估内存的时候，可以按 configTOTAL_HEAP_SIZE 减去各任务栈和内核对象的需求来粗算：每个任务栈按 configMINIMAL_STACK_SIZE 起步，再加上 TCB 控制块和队列控制块的消耗，一块 20KB 的堆能撑起十几个普通任务。要注意 configTOTAL_HEAP_SIZE 的单位是字节而不是字，模板里给的是 8 乘以 1024，别按 8192 个字去理解，那会把超分配直接写进配置，换来的就是运行期找不出原因的 HardFault。
3. 把模板落到工程里：STM32F103 的最小移植步骤与首个多任务
3.1 文件复制清单：模板到 Keil 工程的最小文件集
先看文件结构，模板里最关键的是 FreeRTOS 目录下的这部分内容：
YourProject/ ├── User/ │ ├── main.c │ ├── FreeRTOSConfig.h │ └── stm32f10x_it.c # 注释掉与系统内核冲突的中断函数 ├── FreeRTOS/ │ ├── include/ # tasks.h、queue.h、list.h 等全部头文件 │ ├── tasks.c │ ├── list.c │ ├── queue.c │ ├── timers.c # 如果用到软件定时器再编入 │ └── portable/ │ ├── MemMang/ │ │ └── heap_4.c │ └── RVDS/ │ └── ARM_CM3/ │ ├── port.c │ └── portmacro.h └── 原有外设库文件照旧这一步不做任何修改，先保证文件位置和头文件路径一致。三个关键点：include 目录里是所有 FreeRTOS 公共头文件，一个都不能少，头文件之间有交叉包含，不要按「用到的才拷」来复制；port.c 和 portmacro.h 必须来自 RVDS/ARM_CM3，对应 Keil 编译环境；heap_4.c 放在 portable/MemMang 目录，路径自己理顺就行。
Keil 工程添加文件时，建议给这三部分分别建组，比如 FreeRTOS-Core、FreeRTOS-Portable、FreeRTOS-MemMang，后续出问题可以按组排查。头文件路径方面，在 Project 的 C/C++ 选项卡里把 FreeRTOS/include、FreeRTOS/portable/RVDS/ARM_CM3 两个目录加进 Include Paths 就够了，不需要把 MemMang 也加进去，因为 heap_4.c 里用的是相对包含。
提示：FreeRTOS 的头文件采用双引号包含，Keil 里没把对应目录加入 Include Paths 时，编译错误信息会指向某个看起来毫不相关的头文件。出现这种情况先检查路径，不要怀疑代码。
3.2 最小验证代码：两个任务交替翻转 GPIO
模板的 main.c 就是这个最小验证程序的骨架，我抄录一段最常用的写法：
#include "FreeRTOS.h" #include "task.h" #include "stm32f10x.h" static void vTask1(void *pvParameters) { (void)pvParameters; for (;;) { GPIO_SetBits(GPIOA, GPIO_Pin_0); /* 点亮 */ vTaskDelay(500 / portTICK_PERIOD_MS); /* 延时 500ms */ GPIO_ResetBits(GPIOA, GPIO_Pin_0); /* 熄灭 */ vTaskDelay(500 / portTICK_PERIOD_MS); } } static void vTask2(void *pvParameters) { (void)pvParameters; for (;;) { GPIO_SetBits(GPIOA, GPIO_Pin_1); /* 点亮 */ vTaskDelay(200 / portTICK_PERIOD_MS); /* 延时 200ms */ GPIO_ResetBits(GPIOA, GPIO_Pin_1); /* 熄灭 */ vTaskDelay(200 / portTICK_PERIOD_MS); } } int main(void) { GPIO_InitTypeDef gpio; RCC_APB2PeriphClockCmd(RCC_APB2Periph_GPIOA, ENABLE); GPIO_StructInit(&gpio); gpio.GPIO_Pin = GPIO_Pin_0 | GPIO_Pin_1; gpio.GPIO_Mode = GPIO_Mode_Out_PP; gpio.GPIO_Speed = GPIO_Speed_50MHz; GPIO_Init(GPIOA, &gpio); xTaskCreate(vTask1, "T1", 128, NULL, 1, NULL); /* 优先级 1 */ xTaskCreate(vTask2, "T2", 128, NULL, 2, NULL); /* 优先级 2 */ vTaskStartScheduler(); /* 启动调度器，正常不返回 */ for (;;) { } }这是一个最小可跑工程。两个任务的栈深度都用 128 字，在模板默认的 20KB 堆里没有压力。vTaskDelay(500 / portTICK_PERIOD_MS) 的意思是延时 500 个 tick，而 portTICK_PERIOD_MS 就是 1 除以 tick 频率换算成毫秒的值，默认配置下 1ms 一个 tick，所以除下来刚好是 500。这样写而不是直接填 500，是为了在修改 configTICK_RATE_HZ 之后代码不用跟着改。
注意 xTaskCreate 的参数：第二个参数是任务名，只用于调试，不参与调度，长度受 configMAX_TASK_NAME_LEN 限制，默认 16 字节，超长会被截断但不影响运行。这里把 T2 的优先级设得比 T1 高，两者循环里都有 vTaskDelay，所以能交替运行。如果哪个任务循环里没有任何会触发任务切换的调用，高优先级任务会独占 CPU，低优先级任务彻底饿死，这是新手最常踩的坑之一。
3.3 中断文件与启动文件：内核中断函数为什么不能重复定义
FreeRTOS 的移植层在 port.c 里已经实现了 PendSV_Handler 和 SysTick_Handler，但很多外设库工程在 stm32f10x_it.c 里也定义了这两个同名函数，或者用户把 SysTick_Handler 用来做自己的延时函数。链接时同名符号冲突是移植后最先要处理的事。模板的做法是注释掉 stm32f10x_it.c 里的这两个函数，让 FreeRTOS 的版本生效，同时保留 SVC_Handler 的原本定义。这几个名字是启动文件里的向量名，不能随意改动，改了就指向错误的中断处理入口。
很多 F103 的标准外设库例程都自带 Delay 函数，内部用的是 SysTick。如果你把这些例程里的 SysTick 配置代码原样保留，那么 vTaskStartScheduler 启动调度器时会再次配置 SysTick，两次配置互相覆盖，表现为 Delay 失效或者任务延时变慢。移植时把用户自己的 SysTick 配置全部删掉，只保留 FreeRTOS 在 port.c 里的那套。
启动文件里 Stack_Size 的默认值通常是 0x400，也就是 1KB。这个数值和 FreeRTOS 任务栈没有直接关系，因为任务栈在堆里分配，但中断嵌套深度完全由它决定。F103 上 SysTick、PendSV，以及优先级不高于 configMAX_SYSCALL_INTERRUPT_PRIORITY 的中断都会往 MSP 压栈，如果外部中断里处理较重，1KB 的 MSP 很容易爆。我一般会把它调到 0x800 或 0x1000，代价只是静态 RAM 多占一点，换的是安全余量。这个修改在启动文件里直接改数就行，和 FreeRTOS 配置不冲突。
4. FreeRTOSConfig.h 裁剪：关键宏的作用与 F103 直接可用配置
4.1 一张表看懂关键宏：优先级、节拍、堆大小与任务名
模板的 FreeRTOSConfig.h 是针对 F103 调过的，先看这张配置表：
| 配置宏 | 模板取值 | 作用与影响 |
|---|---|---|
| configCPU_CLOCK_HZ | 72000000 | F103 外部晶振 8MHz 经 PLL 倍频到 72MHz 时填这个值，用于 SysTick 的 tick 频率计算 |
| configTICK_RATE_HZ | 1000 | 系统节拍 1kHz，vTaskDelay 最小粒度 1ms；调大可提高延时精度但增加 tick 中断开销 |
| configTOTAL_HEAP_SIZE | 8 * 1024 | 供 heap_4 使用的总堆大小，单位是字节，修改时注意 F103 的 RAM 容量 |
| configMAX_PRIORITIES | 5 | 可用的优先级数，不是任务数上限，任务创建时指定的优先级不能超过这个数值 |
| configMINIMAL_STACK_SIZE | 128 | 空闲任务栈大小，单位是字，即 512 字节 |
| configMAX_TASK_NAME_LEN | 16 | 任务名字符串最大长度，超出会被截断，不影响运行 |
| configUSE_PREEMPTION | 1 | 抢占式调度；置 0 时变成协作式，任务必须主动让出 CPU |
| configUSE_TIME_SLICING | 1 | 同优先级任务间时间片轮转；置 0 时同优先级任务必须靠 vTaskDelay 让出 |
| configMAX_SYSCALL_INTERRUPT_PRIORITY | 5 | 能在中断里调用 FreeRTOS API 的优先级编号下限 |
| configPEND_SVC_PRIORITY | 15 | PendSV 异常优先级编号，必须为最低，数值上就是最大 |
| configSYSTICK_PRIORITY | 15 | SysTick 优先级编号，同样必须为最低 |
这张表里最容易搞混的是优先级方向。F103 的 NVIC 优先级数值越大，实际优先级越低。configMAX_SYSCALL_INTERRUPT_PRIORITY 取 5，意味着优先级编号 5 到 15 的中断可以调用 FreeRTOS API，而编号 0 到 4 的中断不能调用。这样设计是为了保证调用 API 的中断不会打断系统的临界区保护。如果你把某个中断的优先级设成 0，又在中断里调用了 xQueueSend，系统可能在临界区中被这个中断打断，链表结构被破坏，死机只是时间问题。
4.2 一块可直接抄进工程的 FreeRTOSConfig.h
这是模板里可以直接覆盖到工程里的版本，每一行都能在 F103 上跑通：
#ifndef FREERTOS_CONFIG_H #define FREERTOS_CONFIG_H #include "stm32f10x.h" #define configUSE_PREEMPTION 1 #define configUSE_TIME_SLICING 1 #define configUSE_PORT_OPTIMISED_TASK_SELECTION 1 #define configCPU_CLOCK_HZ ( ( unsigned long ) 72000000 ) #define configTICK_RATE_HZ ( ( TickType_t ) 1000 ) #define configTOTAL_HEAP_SIZE ( ( size_t ) ( 8 * 1024 ) ) #define configMAX_PRIORITIES ( 5 ) #define configMINIMAL_STACK_SIZE ( ( unsigned short ) 128 ) #define configMAX_TASK_NAME_LEN ( 16 ) #define configUSE_IDLE_HOOK 1 #define configUSE_TICK_HOOK 0 #define configCHECK_FOR_STACK_OVERFLOW 2 #define configUSE_MALLOC_FAILED_HOOK 1 #define configMAX_SYSCALL_INTERRUPT_PRIORITY 5 #define configPEND_SVC_PRIORITY 15 #define configSYSTICK_PRIORITY 15 #define configUSE_16_BIT_TICKS 0 #define INCLUDE_vTaskDelay 1 #define INCLUDE_xTaskDelayUntil 1 #define INCLUDE_vTaskDelete 1 #define INCLUDE_vTaskSuspend 1 #define INCLUDE_xTaskGetIdleTaskHandle 1 #define vPortSVCHandler SVC_Handler #define xPortPendSVHandler PendSV_Handler #define xPortSysTickHandler SysTick_Handler #endif重点说三个容易被忽略的地方。configUSE_PORT_OPTIMISED_TASK_SELECTION 取 1，会让调度器在 CM3 上使用 CLZ 指令直接计算最高优先级任务，省掉遍历优先级的循环；改为 0 也能跑，只是切换开销略大。configCHECK_FOR_STACK_OVERFLOW 取 2，在做上下文切换时对任务栈做更完整的检查，一旦发现栈指针越界就调用 vApplicationStackOverflowHook，开发阶段建议保持，交付时可以关掉省一点性能。最后三行宏把 FreeRTOS 内部的中断函数名映射到启动文件里的向量名，F103 标准外设库用的是 SVC_Handler 而不是 SVCall_Handler，必须手动映射一次；你从 GCC 工程抄配置时这三行往往不同，不能原样照搬。
注意：最后三行映射宏依赖启动文件里存在 SVC_Handler、PendSV_Handler、SysTick_Handler 三个符号。如果你的工程换过启动文件，先确认这三个向量名存在，否则链接阶段直接报未定义。
4.3 裁剪与内存占用：加功能之前先算这笔账
很多人在 F103 上跑 FreeRTOS 的功能裁剪不够，把所有 API 全部编进固件，结果 ROM 和 RAM 都多花了不少。下表是常见功能与主要开销：
| 功能 | 相关配置/源文件 | 主要内存开销 |
|---|---|---|
| 软件定时器 | configUSE_TIMERS 置 1，编入 timers.c | 每个定时器一个定时器控制块，加上定时器服务任务的栈 |
| 互斥量 | configUSE_MUTEXES 置 1 | 每个互斥量约 80 字节，含优先级继承相关字段 |
| 事件组 | 直接编入 event_groups.c | 每个事件组一个事件组控制块，约 20 字节 |
裁剪的原则是「用不到的 API 就关掉」。INCLUDE_vTaskSuspend 这类宏调整为 0 后，对应函数会被条件编译从固件里剔除，省的是 ROM；想省 RAM，重点在 configTOTAL_HEAP_SIZE 和各个任务的栈深度。任务栈使用量的经验判断：一个做消息处理和少量计算的普通任务，128 字通常够；如果任务里用了 printf 这类耗栈的库函数，栈需要加大到 256 字以上。每多建一个任务，RAM 增加等于任务栈加 TCB 控制块的总和。
还有人为了省 RAM 把 configTICK_RATE_HZ 从 1000 降到 100，这样 tick 间隔变成 10ms，vTaskDelay 的延时精度同步变粗。降 tick 频率能减少 SysTick 中断的上下文切换开销，但代价是响应变慢。F103 跑 72MHz，tick 设 1000Hz 的开销其实很小，不建议为了省一点 CPU 时间牺牲实时性。
5. 移植常见问题排查：四个高频翻车现场与定位路径
这一章是移植过程真正花时间的部分。下面的几个问题，都是 F103 上跑 FreeRTOS 反复出现的典型故障，每一条按「现象、原因、解决」来拆，你可以对照自己的现象直接定位。
5.1 HardFault：系统刚启动就崩溃，连第一个任务都没跑起来
现象：编译下载后程序复位直接进 HardFault_Handler，断点打在 main 里能停，一旦执行到 vTaskStartScheduler 之后就再也回不来。在线调试时查看寄存器，PC 指到一个无法解析的地址，调用栈里看到的是几个汇编层的函数。
原因：最常见的有三种。第一种是 heap 内存不足，configTOTAL_HEAP_SIZE 设得太小，任务栈加起来超过堆容量，xTaskCreate 返回失败而代码没检查，调度器仍然启动，内部链表已经被破坏。第二种是 port.c 的编译器和实际工程编译器不一致，内联汇编生成的指令无法正确装载任务寄存器。第三种较少见但存在：任务函数写成了普通函数而不是死循环，任务第一次返回时没有退出路径，FreeRTOS 把非法返回当成错误处理。
解决：先检查 xTaskCreate 的返回值，返回 pdPASS 才继续创建下一个任务；同时把 configUSE_MALLOC_FAILED_HOOK 置 1，在钩子里点灯或打印，第一时间暴露内存分配失败。再确认 port.c 来自 Keil 对应的 RVDS 目录，不是 GCC 目录。最后检查每个任务函数是不是 for(;;) 死循环结构，不要在任务函数尾部做返回操作。按这个顺序排查，HardFault 大概率能定位到具体某一项。
5.2 任务切换不生效：高优先级任务独占 CPU，低优先级任务永远不运行
现象：两个任务都创建成功，只有高优先级任务在跑，低优先级任务里的断点永远打不到。用调试器查看两个任务状态，发现低优先级任务一直停在 Ready 状态，没有被杀掉，也没有被挂起。
原因：高优先级任务的循环里没有任何会导致任务切换的 API，比如 vTaskDelay、xQueueReceive 这类带阻塞机制的调用。抢占式调度不是时间片轮转，高优先级任务只要一直处于就绪态，低优先级任务就没有机会运行。这经常被误认为是「任务切换坏了」，实际上调度器工作得完全正常。
解决：确认设计意图。如果是想让两者交替运行，给每个任务的循环里加 vTaskDelay(10 / portTICK_PERIOD_MS) 让出 CPU；如果是做事件驱动，低优先级任务应该调用 xQueueReceive 等待队列消息，而不是空转轮询。想用时间片轮转，就让两个任务优先级相同，并保持 configUSE_TIME_SLICING 为 1，这样每个 tick 会在同优先级任务之间轮流切换。
5.3 vTaskDelay 不按预期延时：延时时间完全不对
现象：vTaskDelay(1000 / portTICK_PERIOD_MS) 期望延时 1 秒，实际要么非常快、要么非常慢，用示波器量 GPIO 翻转周期，和预期差出好几倍。
原因：configTICK_RATE_HZ 和实际 SysTick 配置不一致。FreeRTOS 在 vTaskStartScheduler 里根据 configCPU_CLOCK_HZ 计算 SysTick 的重载值，如果 configCPU_CLOCK_HZ 写的是 72MHz，而你的系统时钟实际只有 8MHz，也就是没用 PLL，tick 会比预期快 9 倍；反过来则慢。另一个原因是 stm32f10x_it.c 里的 SysTick_Handler 没有注释掉，用户代码和 FreeRTOS 的 handler 共存，一个 tick 被处理两次，延时结果同样不对。
解决：先用 RCC_GetClocksFreq 读出系统时钟频率，对比 configCPU_CLOCK_HZ 是否一致。然后全局搜索 SysTick_Handler，确认整个工程只有 port.c 里定义的那一个。这两个动作能解决九成延时不准的案例。剩下的情况多半是调试时断点停留导致 tick 计数暂停，属于调试器的影响，不是代码问题。
5.4 动态创建任务失败：xTaskCreate 返回 pdFAIL
现象：代码在创建第三个或第四个任务时，xTaskCreate 返回 pdFAIL，新任务没有运行，系统其余任务暂时正常，但后面某些功能开始失灵。
原因：configTOTAL_HEAP_SIZE 不够用了。xTaskCreate 每次分配的内存包括任务栈和 TCB 控制块两部分，任务栈按 128 字算就是 512 字节，TCB 还要占一百多字节。堆里剩余空间不足时，heap_4 的分配函数返回 NULL，xTaskCreate 就报 pdFAIL。很多时候并不是总量不够，而是碎片导致没有足够大的连续空闲块。虽然 heap_4 会合并相邻空闲块，但被长期占用的块之间仍然可能留下零碎空洞。
解决：在 xTaskCreate 返回值上直接判断，pdFAIL 时打印当前的剩余堆大小。调用 xPortGetFreeHeapSize 可以拿到剩余堆字节数，对比新任务的需求就知道差多少。临时验证时可以调大 configTOTAL_HEAP_SIZE，长期规划则要根据任务栈使用率重新评估，给堆留 20% 余量是 F103 这种 48KB RAM 芯片上比较合理的习惯。
5.5 任务栈溢出：系统跑一会儿就死机或数据被悄悄改掉
现象：系统能正常启动，但运行一段时间后随机死机，有时候某个变量的值突然变成异常数据。开启 configCHECK_FOR_STACK_OVERFLOW 后，在钩子里设断点能拦到栈溢出。
原因：任务里局部数组过大，或者调用了耗栈的库函数，比如 printf、浮点格式化输出，实际栈使用超过创建任务时指定的栈深度。Cortex-M3 的栈向下生长，溢出时会侵蚀相邻内存区域，可能是另一个任务的 TCB 控制块，也可能是队列数据，于是表现为完全随机的脏数据。
解决：把 configCHECK_FOR_STACK_OVERFLOW 设为 2 重新编译，在 vApplicationStackOverflowHook 函数里点灯或打调试串口，确认是哪个任务溢出。这个检测机制是启发式的，能抓到一部分溢出场景，抓不到全部。定位到具体任务后，把该任务的栈深度调大，经验值：任务里出现一个 64 字节以上的局部数组，栈从 128 字提到 192 字起步。更稳妥的做法是开发阶段把所有任务栈统一设为 256 字，功能验证通过后再逐个调小，逼近真实需求。
6. 验证模板跑没跑对：两个不依赖串口的实测技巧
6.1 用 GPIO 翻转的上升沿测量真实任务切换节奏
把 3.2 节里两个任务的延时改成固定值，比如都设成 100ms，用示波器两通道同时观察两个 GPIO 引脚。正常的抢占式调度下，波形应该是稳定的方波，切换点间隔等于 tick 周期的整数倍。如果波形抖动、周期忽长忽短，说明 tick 不稳定，优先怀疑时钟配置；如果某个引脚波形完全消失，就是那个任务没在运行，翻回 5.2 查优先级和阻塞调用。这个方法是零成本的回归验证手段，改配置后跑一次，十几秒就能确认系统基本健康。
6.2 用空闲任务钩子估算 CPU 占用率
在 configUSE_IDLE_HOOK 置 1 的情况下，可以实现一个 vApplicationIdleHook，里面只做一个计数器自增，然后开一个 1 秒的定时任务去读这个计数器的值。先让系统空载跑，读数拿到一个基准值，再运行真实负载，读数变化就能粗略推算出 CPU 占用率。这个方案精度不高，但用来评估任务负载是足够的。注意钩子函数里不能调用任何可能阻塞的 API，也不要放延时，它本身就在最低优先级任务里执行。
做移植实验这几年，我养成一个习惯：不管项目多急，拿到模板先跑一遍最小双任务加 GPIO 翻转验证，再往里加业务功能。这个习惯帮我挡掉了至少三次把优先级配错当成硬件故障的返工。希望帮到你。
本文还有配套的精品资源，点击获取
