3、FreeRTOS源码获取与移植：从官网获取源码，理解内核文件、可移植层、Demo工程，以STM32为例完成最小系统移植，验证系统运行

FreeRTOS 作为市场占有率最高的嵌入式实时操作系统，其源码组织方式、可移植层设计以及工程构建逻辑，是每一位希望深入掌握 RTOS 原理的开发者必须跨越的门槛。本章将带领你从零开始，完成 FreeRTOS 源码的获取、工程结构的解析，并以 STM32F103 系列芯片为例，手把手完成一次最小系统的移植与验证。我们不仅要让系统“跑起来”，更要理解每一步操作背后的设计哲学——为什么 FreeRTOS 要将架构相关的代码与内核核心代码分离？为什么移植工作主要集中在 port 层？这些问题的答案，将直接决定你在未来面对新芯片平台时，能否独立完成适配工作。

上图清晰地展示了 FreeRTOS 源码的三大核心模块及其关系。内核核心（FreeRTOS/Source 下的 .c 文件）完全使用 C 语言编写，不依赖任何特定芯片或编译器，保证了逻辑的通用性。而可移植层（portable 目录）则针对不同的编译器（如 GCC、IAR、Keil）和处理器架构（如 ARM Cortex-M3、M4、RISC-V）提供了具体的实现。这种“核心与平台分离”的设计，使得 FreeRTOS 能够轻松支持超过 40 种处理器架构。接下来，我们将深入每一个环节，从源码获取开始，逐步构建属于你自己的最小系统。

3.1 源码获取与目录结构深度解析

核心原理：FreeRTOS 的源码托管在 GitHub 官方仓库（FreeRTOS/FreeRTOS），其发布版本以 V10.x.x 命名。获取源码最直接的方式是使用 git clone 命令，或者直接从官网下载 ZIP 压缩包。值得注意的是，从 V10.0 开始，FreeRTOS 将内核与库（如 TCP/IP、FAT 文件系统）分离，因此我们只需要关注 FreeRTOS/Source 目录下的内容。

操作流程：以下是在 Windows 或 Linux 环境下获取源码的标准步骤：

# 使用 Git 克隆（推荐，便于后续更新）
git clone https://github.com/FreeRTOS/FreeRTOS.git
cd FreeRTOS

# 或者直接下载 ZIP 包并解压
# 解压后进入 FreeRTOS 目录，重点关注以下子目录：
#   FreeRTOS/Source/          —— 内核核心源码
#   FreeRTOS/Source/portable/ —— 可移植层
#   FreeRTOS/Demo/            —— 官方示例工程

解压后，你需要理解 Source 目录下的关键文件：tasks.c（任务调度核心）、queue.c（队列与信号量）、list.c（内核链表）、timers.c（软件定时器）、event_groups.c（事件组）、croutine.c（协程，较少用）。此外，portable/MemMang 目录下提供了 heap_1.c 到 heap_5.c 五种内存管理算法，后续章节会详细对比。

3.2 可移植层（portable）的工程意义与选择

核心原理：可移植层是 FreeRTOS 能够运行在不同硬件上的关键。它主要完成三件事：① 上下文切换（保存/恢复寄存器）、② 时钟节拍（SysTick 中断驱动调度）、③ 临界区保护（屏蔽/恢复中断）。对于 STM32F103（Cortex-M3 内核）搭配 Keil 编译器，我们选择 portable/RVDS/ARM_CM3 目录。RVDS 是 Keil 底层使用的 ARM 编译器工具链。

判断方法：选择移植层时，需要同时考虑编译器和内核架构两个维度。例如：

• 使用 GCC 编译器 + STM32F4（Cortex-M4）：选择 portable/GCC/ARM_CM4F。
• 使用 IAR 编译器 + STM32F1（Cortex-M3）：选择 portable/IAR/ARM_CM3。
• 使用 Keil + STM32F1（Cortex-M3）：选择 portable/RVDS/ARM_CM3。

在 port.c 文件中，你会看到 pxPortInitialiseStack() 函数，它负责在创建任务时初始化任务的初始栈帧，模拟一次“刚被中断打断”的状态，这样当调度器第一次切换时，就能正确恢复现场。而 xPortPendSVHandler() 则是 PendSV 中断服务函数，这是上下文切换的“发动机”。

3.3 以 STM32F103 为例的最小系统移植实战

案例背景与目标：假设我们手上有一块 STM32F103C8T6 最小系统板（蓝板），使用 Keil MDK5 环境，目标是在上面运行 FreeRTOS，并创建两个任务：一个任务控制 LED 以 500ms 周期翻转，另一个任务通过串口 1 每秒打印一次系统运行时间（通过 xTaskGetTickCount() 获取）。这是验证移植是否成功的最简方案。

初始现象与约束：板载 LED 连接在 PC13 引脚（高电平点亮），串口使用 USART1（PA9/PA10），晶振为 8MHz，系统主频设置为 72MHz。我们没有任何现成的 FreeRTOS 工程模板，需要从零开始搭建。

操作步骤（关键步骤拆解）：

1. 创建基础工程：在 Keil 中新建工程，选择芯片型号 STM32F103C8，并配置好 Flash（64KB）和 RAM（20KB）大小。添加必要的启动文件 startup_stm32f10x_md.s 和系统时钟初始化文件 system_stm32f10x.c。
2. 复制 FreeRTOS 源文件：在工程目录下新建 FreeRTOS 文件夹，将 Source 下的所有 .c 文件（tasks.c、queue.c、list.c、timers.c、event_groups.c、croutine.c）和 include 文件夹复制进去。再新建 port 文件夹，将 portable/RVDS/ARM_CM3 下的 port.c 复制进去，并将 portable/MemMang/heap_4.c 复制到 FreeRTOS 根目录下。
3. 添加头文件路径：在 Keil 的 C/C++ 选项卡中，添加以下头文件路径：FreeRTOS/include、FreeRTOS/port、以及存放 FreeRTOSConfig.h 的路径。
4. 编写 FreeRTOSConfig.h：这是移植的核心配置文件。针对 STM32F103，关键配置如下：

#define configCPU_CLOCK_HZ        ( ( unsigned long ) 72000000 )  // 系统主频 72MHz
#define configTICK_RATE_HZ        ( ( TickType_t ) 1000 )         // 时钟节拍 1ms
#define configMAX_PRIORITIES      ( 5 )                            // 最大优先级数
#define configMINIMAL_STACK_SIZE  ( ( unsigned short ) 128 )       // 最小任务栈大小（字）
#define configTOTAL_HEAP_SIZE     ( ( size_t ) ( 10 * 1024 ) )     // 堆大小 10KB
#define configUSE_PREEMPTION      1                                // 抢占式调度
#define configUSE_IDLE_HOOK       0
#define configUSE_TICK_HOOK       0
#define configENABLE_FPU          0                                // M3 内核无 FPU

中断优先级配置：在 FreeRTOSConfig.h 中必须定义 configLIBRARY_MAX_SYSCALL_INTERRUPT_PRIORITY 为 5（对应 5<<4=80），并确保 PendSV 和 SysTick 中断优先级设置为最低（数值最大）。在 main.c 中调用 NVIC_PriorityGroupConfig(NVIC_PriorityGroup_4); 设置分组。

编写 main.c 与中断处理：

#include "FreeRTOS.h"
#include "task.h"
#include "queue.h"

// 任务函数声明
void vLEDTask(void *pvParameters);
void vUARTTask(void *pvParameters);

int main(void)
{
    // 硬件初始化：LED GPIO、USART1 等（此处省略）
    
    // 创建任务
    xTaskCreate(vLEDTask, "LED", configMINIMAL_STACK_SIZE, NULL, 1, NULL);
    xTaskCreate(vUARTTask, "UART", configMINIMAL_STACK_SIZE, NULL, 2, NULL);
    
    // 启动调度器
    vTaskStartScheduler();
    
    // 正常情况下不会运行到这里
    while(1);
}

void vLEDTask(void *pvParameters)
{
    for( ;; )
    {
        GPIO_WriteBit(GPIOC, GPIO_Pin_13, Bit_SET);
        vTaskDelay(500 / portTICK_PERIOD_MS);
        GPIO_WriteBit(GPIOC, GPIO_Pin_13, Bit_RESET);
        vTaskDelay(500 / portTICK_PERIOD_MS);
    }
}

void vUARTTask(void *pvParameters)
{
    TickType_t xLastWakeTime = xTaskGetTickCount();
    for( ;; )
    {
        printf("Tick: %lu\r\n", (unsigned long)xTaskGetTickCount());
        vTaskDelayUntil(&xLastWakeTime, 1000);
    }
}

// 注意：需要实现 vApplicationStackOverflowHook 和 vApplicationMallocFailedHook 钩子函数

结果对比与验证：编译下载后，观察现象：LED 以 1Hz 频率闪烁（亮 500ms 灭 500ms），串口助手每秒收到一条 Tick: xxx 信息，且数值递增。这说明任务调度正常，时间片轮转和延时功能均工作正常。如果 LED 不闪烁或串口无输出，优先检查 configCPU_CLOCK_HZ 是否与实际主频一致，以及中断优先级配置是否正确。

3.4 常见误区与移植后的系统验证清单

常见误区：

• 误区一：忽略中断优先级分组。FreeRTOS 要求使用 NVIC_PriorityGroup_4（全部 4 位用于抢占优先级），否则临界区保护可能失效。
• 误区二：在中断服务函数中调用非中断安全的 API（如 printf）。应使用 FromISR 结尾的函数，如 xQueueSendFromISR。
• 误区三：任务栈分配过小。Cortex-M3 的每个任务至少需要 128 字（512 字节）的栈空间，如果任务中有较大的局部变量或调用较深的函数，需要适当增大。
• 误区四：忘记实现钩子函数。当 configUSE_IDLE_HOOK 或 configUSE_TICK_HOOK 置 1 时，必须提供对应的钩子函数实现，否则链接报错。

验证清单（移植完成后逐项检查）：

总结复盘：FreeRTOS 的移植工作本质上是一个“配置 + 集成”的过程，而非“修改内核”的过程。理解 port.c 中上下文切换的汇编代码，能帮助你更深刻地理解 RTOS 的调度机制。建议在完成本章移植后，尝试阅读 port.c 中的 xPortPendSVHandler 汇编代码，结合《Cortex-M3 权威指南》中关于 PendSV 和 SysTick 的描述，你将打通“硬件中断”与“软件调度”之间的任督二脉。在下一阶段的学习中，你将基于这个最小系统，逐步探索队列、信号量、互斥量等同步机制的实际应用。