GD32F103系列FreeRTOS移植实战：从零搭建到LED任务测试

1. 开篇：为什么要在GD32F103上跑FreeRTOS？

大家好，我是老李，一个在嵌入式圈子里摸爬滚打了十多年的老码农。今天想和大家聊聊一个非常具体、也非常有成就感的事儿：把FreeRTOS这个轻量级的实时操作系统，移植到国产的GD32F103系列MCU上，并且亲手点亮一个LED灯来验证它跑起来了。

你可能要问，GD32F103本身不是跑裸机程序挺好的吗，为啥要折腾RTOS？我刚开始也这么想，但后来项目复杂了，发现裸机程序写状态机、处理多个传感器数据、还要响应网络请求，代码很快就变成了一团乱麻，维护起来简直是噩梦。FreeRTOS的价值就在于，它能把你的应用拆分成一个个独立的小任务（Task），每个任务只管自己那摊事儿，由操作系统内核来负责调度和切换。这就好比从一个单线程的杂货铺老板，变成了一个管理着多个熟练员工的店长，效率和组织性完全不是一个级别。

GD32F103作为一款高性价比的国产Cortex-M3内核MCU，性能和资源对于很多物联网、工控小设备来说绰绰有余。把它和FreeRTOS结合起来，就像是给一辆性能不错的经济型轿车装上了一套智能驾驶系统，既能完成复杂的多任务操作，成本又控制得非常好。这个组合特别适合那些想从裸机编程进阶到RTOS的开发者，或者正在寻找稳定、低成本RTOS方案的团队。今天，我就手把手带你走一遍完整的移植和验证流程，从零搭建工程，到解决那些必然会遇到的编译“坑”，最后让LED灯在你的指挥下欢快地闪烁起来。放心，过程很详细，就算你是第一次接触RTOS，跟着做也一定能成功。

2. 万事开头难：工程准备与源码获取

移植的第一步，不是急着写代码，而是要把“厨房”收拾好，把“食材”备齐。这里说的厨房，就是你的工程模板；食材，就是FreeRTOS的官方源码。

2.1 准备一个干净的GD32F103工程模板

我强烈建议你不要在现有的复杂项目里直接开搞移植，那会引入太多干扰项。最好是为这次移植专门新建一个工程，或者使用一个最基础的、能点灯的GD32F103模板工程。这个模板工程需要包含GD32官方标准外设库（或者HAL库）的基本驱动文件、正确的芯片型号链接脚本、以及初始化系统时钟的代码。你可以从GD32官网的例程里找一个，或者用STM32CubeMX针对兼容型号生成后修改过来。我习惯用一个之前博客里分享的GD32F103C8T6最小系统板模板，它只包含了最基础的GPIO、时钟和延时函数，非常干净。有了这个模板，我们就能在一个已知正确的起点上开始工作。

2.2 获取正确的FreeRTOS源码

接下来是获取FreeRTOS源码。一定要去官网（sourceforge.net/projects/freertos/files/FreeRTOS/）下载。我写这篇文章时，最新的长期支持版是FreeRTOSv202406.01-LTS.zip，我们就用这个版本。用LTS（长期支持）版本的好处是稳定，坑相对少一些。下载后解压，你会看到一个包含很多文件夹的目录。我们真正需要的核心文件，都在 FreeRTOS-LTS/FreeRTOS/FreeRTOS-Kernel 这个路径下。这里就是FreeRTOS的心脏，包含了任务调度、队列、信号量、内存管理等所有核心功能的源码。

2.3 在工程中创建FreeRTOS的家

在你的GD32工程根目录下，新建一个文件夹，就命名为 FreeRTOS。然后，把刚才提到的 FreeRTOS-Kernel 目录下的所有文件（注意是文件，不是文件夹）都复制到这个新建的 FreeRTOS 文件夹里。复制完后，你的工程 FreeRTOS 目录下应该有一堆 .c 和 .h 文件，比如 tasks.c, queue.c, list.c 等，还有一个 portable 文件夹。

为了让工程结构更清晰，我习惯在 FreeRTOS 目录下再新建一个 src 文件夹。然后，把除了 portable 文件夹和 FreeRTOSConfig.h（这个可能还没有）之外的所有 .c/.h 文件，都移动到 src 里。这样，核心源码就归拢到了一起。接着，处理 portable 文件夹。这个文件夹里存放的是针对不同编译器和处理器架构的移植层代码。我们只需要保留三个子文件夹：

1. MemMang：里面是内存堆管理方案，有5种（heap_1 到 heap_5），我们通常选 heap_4.c，因为它支持内存碎片合并，比较通用。
2. RVDS：这个文件夹里存放的是针对ARM编译器（ARMCC、ARMClang）的移植文件。我们展开它，找到 ARM_CM3，因为GD32F103是Cortex-M3内核。把这个 ARM_CM3 文件夹整个保留。
3. GCC 或 IAR：如果你的开发环境是Keil MDK（使用ARM编译器），通常用 RVDS 里的文件。但有时也需要参考其他文件夹的结构。为了保险，我们可以先把 GCC 和 IAR 备份到别处，工程里只保留 RVDS 和 MemMang，这样结构最清爽。

把