RTOS on Blog

RTOS 正传（一）：FreeRTOS 的目录、移植层和配置文件

Mon, 17 Aug 2026 15:52:00 +0800

RTOS 正传（一）：FreeRTOS 的目录、移植层和配置文件

上一篇把启动文件、链接脚本和 CMake 都搭好了，这一篇就是正传，开始把 FreeRTOS 搬进来。

学习 RTOS，注重适配层而不是内核，这一点很关键。这种大型开源项目，本来就是一个组织、一群人在维护，想把里面所有东西全部理解，本身就很困难。

当然，这不是说你不能成为贡献者。真想走这条路，也可以学阿酥在 Coding 那样一路混到大厂 Offer。但如果眼前只是想把 F407 上的系统跑起来，那就先把下面几个问题弄明白：

哪些 FreeRTOS 文件要编进工程？
F407 + GCC 应该选哪个端口？
堆实现到底选哪个？
FreeRTOSConfig.h 里一大堆宏，哪些真的要管？
哪些中断可以调用 xxxFromISR()？

这些问题先弄明白，系统就不再是“复制一个 Demo，能亮就算成功”的黑盒。

RTOS 到底适合什么场景

我们接下来就依照 FreeRTOS 来介绍。OS 本质上就是调度器，就是多任务处理，所以它明显更适合业务逻辑复杂、控制频率没到 us 级的场景，比如智能穿戴和飞控。

没错，我这里把飞控也算作低频率控制系统。一是因为它的数据处理很复杂，二是因为电调本身的控制频率也不高，PX4 就是跑在 NuttX 上的。

但你说我搞高精度伺服、工业电机驱动，上个 RTOS，这就不符合应用场景了。这是很关键的问题。

先把内核仓库拉下来

这次直接看官方的 FreeRTOS-Kernel 仓库。它只放内核源码、头文件和各种 CPU/编译器端口，比把 FreeRTOS-Plus、TCP、MQTT 全带上的聚合仓库清爽得多。

只学习当前版本的话，浅克隆就够了：

1
2


git clone --depth 1 --branch V11.3.0 \
 https://github.com/FreeRTOS/FreeRTOS-Kernel.git

官方文档在 www.freertos.org。内容肯定最全，但第一次打开确实像面对一本全英文词典：每个 API 都能查，问题是根本不知道应该先查哪个。

我还是那个观点，没有什么比上手更重要。应用本来就比原理简单，设计岗薪资更高这一点事实足以佐证。所以这篇不准备逐行做源码解析，只介绍文件作用、怎么裁剪，以及核心移植层是怎么做的。源码主要还得靠自己慢慢啃，工程先跑起来再说。

克隆下来为什么这么吓人

点开目录第一眼确实容易晕：一个 tasks.c 就有 8872 行，旁边还躺着一堆不认识的配置文件。别慌，真正要烧进 F407 的内容并没有这么多。

这个仓库里的东西大致分成四类：

tasks.c、queue.c、list.c 这些通用内核源码；
portable/ 下面针对不同 CPU 和编译器准备的移植代码；
include/ 里的公共 API 和内核头文件；
GitHub、合规、发布和文档文件。

后面不再给每个文件单独截一张图了。最好把仓库放在旁边，对着目录往下看，会比只看文章顺得多。

先分清自己站在哪一层

这里最关键的不是记文件名，而是先搞清楚自己现在扮演什么角色。

应用开发者主要使用 task.h、queue.h、semphr.h 这些 API，再根据业务配置 FreeRTOSConfig.h。任务怎么分、栈给多少、优先级怎么排，这些才是日常工作。

移植者要把内核接到具体 CPU 和工具链上。F407 已经有官方 ARM_CM4F 端口，我们只需要选对、编进来，再接好 SysTick、PendSV、SVC 和中断优先级，不用自己从零写上下文切换。

内核维护者才需要深挖 tasks.c、queue.c、list.c，研究就绪链表、阻塞链表、优先级继承和调度细节。

还有一类是仓库维护者。.github/、MISRA、SPDX、拼写检查这些文件主要服务于 FreeRTOS 项目本身。它们不是垃圾，只是不会进入我们的固件。

顶层目录先过一遍

把截图里的内容整理一下，大概就是这样：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


FreeRTOS-Kernel/
├── .github/ # CI、Issue/PR 模板、贡献规范
├── examples/ # CMake 示例和配置模板
├── include/ # 内核头文件
├── portable/ # CPU、编译器和堆的移植实现
├── tasks.c # 任务和调度器
├── queue.c # 队列、信号量、互斥锁
├── list.c # 内核链表
├── timers.c # 软件定时器
├── event_groups.c # 事件组
├── stream_buffer.c # Stream/Message Buffer
├── croutine.c # 旧式协程
├── CMakeLists.txt # 官方 CMake 入口
├── README.md # 仓库说明
├── History.txt # 版本历史
├── LICENSE.md # MIT 许可证
├── MISRA.md # MISRA 合规与偏离说明
├── manifest.yml # 发布元数据
├── cspell.config.yaml # 英文拼写检查
├── .gitattributes # Git 文件属性
├── .gitmodules # 第三方端口子模块
├── .git-blame-ignore-revs # blame 时忽略格式化提交
├── *SPDX2.3.spdx* # 多种格式的 SBOM
├── GitHub-FreeRTOS-Kernel-Home.url
└── Quick_Start_Guide.url # 网页快捷方式

看起来还是不少，但真正的内核主体其实就是根目录那几个 .c。

根目录的 7 个 `.c`

tasks.c 是调度器主体。任务创建、删除、延时、优先级、就绪与阻塞状态，最后都绕不开它。应用开发者先理解任务状态怎么变化就够了；真要维护内核，再进去研究各条链表怎么转。

queue.c 不只实现 Queue。Semaphore、Mutex、Recursive Mutex、Queue Set 也复用了它的队列结构。应用层最值得先搞懂的是阻塞超时和 Mutex 的优先级继承。

list.c 只有两百多行，却是内核调度的地基。就绪任务、延时任务、挂起任务都要挂到链表上。应用不会直接调用它，内核维护者则必须把它看明白。

上面三个是所有端口都要带的通用内核文件。剩下四个按功能看：

timers.c：软件定时器和 Timer Service Task；
event_groups.c：事件组；
stream_buffer.c：Stream Buffer 和 Message Buffer；
croutine.c：旧式协程，新项目基本不用。

官方 CMake 会把这 7 个文件都放进内核目标，再靠配置宏和链接器裁掉没启用的部分。所以这里说“按需使用”，不是让人刚入门就随手删源码。

`include/`：平时调用的 API 都在这儿

这个目录大部分是声明和宏，不是另一份内核实现。应用最常碰到的是：

1
2
3
4
5
6
7
8


FreeRTOS.h 总入口，读取 FreeRTOSConfig.h
task.h 任务、延时、通知、调度器 API
queue.h 队列和 Queue Set
semphr.h 信号量和互斥锁
timers.h 软件定时器
event_groups.h 事件组
stream_buffer.h Stream Buffer
message_buffer.h Message Buffer

下面这些就更偏内核和移植：

1
2
3
4
5


list.h 内核链表，应用不要直接依赖
portable.h 内核和端口层之间的接口
projdefs.h 通用类型、返回值和基础定义
stack_macros.h 栈溢出检查宏
atomic.h 原子操作宏

剩下的 mpu_*.h 是 MPU 端口用的，newlib-freertos.h、picolibc-freertos.h 负责 C 库适配；StackMacros.h 和 deprecated_definitions.h 主要照顾旧工程。现在知道它们大概在哪儿就行，不用每个都点开拜读。

应用层可以正常包含公共 API，但不要为了“适配板子”去改内核头文件。芯片和板级差异应该留在端口、中断入口和自己的 FreeRTOSConfig.h 里。

`portable/`：真正和芯片接上的地方

这个目录最大不是因为它最复杂，而是 FreeRTOS 要同时照顾 GCC、IAR、Keil，以及 Cortex-M、RISC-V、AVR、PIC 等一大群组合。基本规则就是：

1

portable/<编译器>/<CPU 架构>/

我们现在用的是 STM32F407VET6 + arm-none-eabi-gcc。F407 是带 FPU 的 Cortex-M4，所以选：

1
2
3


portable/GCC/ARM_CM4F/
├── port.c
└── portmacro.h

port.c 负责初始任务栈、启动第一个任务，以及 SysTick、PendSV、SVC 这些和上下文切换有关的东西。portmacro.h 则定义栈类型、字节对齐、临界区和任务切换宏。

其他 CPU 和编译器目录都不用编译。你不是在做一个全架构发行版，没必要把整个 portable/ 一锅端进工程。

portable/MemMang/ 下面还有 5 个堆实现：

heap_1.c：只能分配，不能释放，最简单；
heap_2.c：能释放但不合并相邻空闲块，新项目一般不选；
heap_3.c：包装 C 库的 malloc() 和 free()；
heap_4.c：能释放，也会合并空闲块，普通 MCU 工程最常用；
heap_5.c：能力类似 heap_4.c，但支持多个不连续内存区。

动态分配时只能选一个。这里先用 heap_4.c，别把五个一起编进去开会。

那些不会进固件的文件

根目录剩下的东西也简单过一下，免得每次看到都怀疑是不是漏编了：

.github/：CI、测试、PR 模板和贡献流程；
examples/：CMake 示例、Coverity/MISRA 示例和 FreeRTOSConfig.h 模板；
CMakeLists.txt：官方构建入口；
README.md、History.txt、LICENSE.md：说明、历史和许可证；
MISRA.md：MISRA C:2012 的合规范围和偏离理由；
manifest.yml：发布系统读取的版本和许可证信息；
cspell.config.yaml：英文拼写检查；
.gitattributes、.gitmodules、.git-blame-ignore-revs：Git 自己用的配置；
4 个 SPDX2.3 文件：同一份 SBOM 的文本、JSON、XML、YAML 版本；
两个 .url：官方主页和快速入门的网页快捷方式。

它们都不会被编译器变成 MCU 指令。想给 FreeRTOS 官方仓库提 PR 时再认真研究，现在知道不用塞进 F407 工程就够了。

F407 工程最后到底拿哪些

绕了一圈，真正需要的东西可以缩成这样：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


FreeRTOS-Kernel/
├── tasks.c
├── queue.c
├── list.c
├── timers.c # 开软件定时器时使用
├── event_groups.c # 开事件组时使用
├── stream_buffer.c # 开 Stream/Message Buffer 时使用
├── include/
└── portable/
 ├── GCC/ARM_CM4F/
 │ ├── port.c
 │ └── portmacro.h
 └── MemMang/heap_4.c

自己的工程/
└── FreeRTOSConfig.h

边界也就清楚了：内核维护者去深究 tasks.c + queue.c + list.c；做新端口的人研究 port.c、portmacro.h 和异常机制；我们现在主要负责选对 ARM_CM4F 端口，再把任务、内存和中断规则写进 FreeRTOSConfig.h。

这个配置文件不在内核根目录，因为它本来就属于具体应用。官方只在 examples/template_configuration/FreeRTOSConfig.h 放了一份模板。接下来就开始拆它。

`FreeRTOSConfig.h` 配置分类

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


FreeRTOSConfig.h
├── 1. 时钟与时间
├── 2. 调度器与任务
├── 3. 任务附加能力
├── 4. 任务通信与同步
├── 5. 软件定时器
├── 6. 内存、堆和任务栈
├── 7. 中断与临界区
├── 8. Hook 回调
├── 9. 故障检测、断言、调试统计
├── 10. C 库、POSIX 兼容
├── 11. 旧协程
├── 12. MPU、TrustZone、安全隔离
├── 13. 多核 SMP
└── 14. API 裁剪开关

先说好，这 14 类不是让你全背下来。第一版真能把人折磨疯的，其实就时钟、中断优先级、任务栈、堆和几个调试开关。剩下那些 MPU、TrustZone、多核，看见名字很高级，但和现在这颗 F407 没啥关系，先别给自己加戏。

我们还是一组一组过，不然后面报错了连该骂谁都不知道。

1. 时钟与时间

1
2
3
4
5


configCPU_CLOCK_HZ
configSYSTICK_CLOCK_HZ
configTICK_RATE_HZ
configTICK_TYPE_WIDTH_IN_BITS
configUSE_TICKLESS_IDLE

这组就是告诉 FreeRTOS：CPU 到底跑多快，一秒钟产生多少个 Tick。

最容易写错的是 configCPU_CLOCK_HZ。它填的是启动调度器时真正生效的 HCLK，不是芯片宣传页上的最高主频。假如时钟还没配，现在实际跑的是 16 MHz，那就老老实实填 16 MHz。你代码根本没切到 168 MHz，却在这里写个 168 MHz，后面的延时自然全是歪的。

configSYSTICK_CLOCK_HZ 只有在 SysTick 和 CPU 时钟不同源时才需要单独写。现在两边一样就别重复定义，省得以后改了一个忘了另一个。

configTICK_RATE_HZ 第一版用 1000 就行，也就是 1 Tick = 1 ms。写延时的时候别偷懒：

1

vTaskDelay(pdMS_TO_TICKS(10));

直接写 vTaskDelay(10) 看起来很爽，但哪天 Tick 频率一改，这个 10 就不一定还是 10 ms 了。

F407 用 32 位 Tick：

1

#define configTICK_TYPE_WIDTH_IN_BITS TICK_TYPE_WIDTH_32_BITS

configUSE_TICKLESS_IDLE 是低功耗用的，空闲时把周期 Tick 停掉。第一版先关，系统都还没跑稳就别急着省那点电。

2. 调度器与任务

1
2
3
4
5


#define configUSE_PREEMPTION 1
#define configUSE_TIME_SLICING 1
#define configMAX_PRIORITIES 5
#define configIDLE_SHOULD_YIELD 1
#define configUSE_PORT_OPTIMISED_TASK_SELECTION 1

configUSE_PREEMPTION = 1 就是抢占式调度。高优先级任务一旦就绪，不需要等低优先级任务自己良心发现让出 CPU，直接抢过来运行。

configUSE_TIME_SLICING = 1 是让同优先级任务轮流跑。两个任务优先级一样，又都不阻塞，那就每个 Tick 换一次。

configMAX_PRIORITIES 也不是越大越牛逼。第一版 5 级其实就够分了：控制、采样通信、普通业务、显示日志、Idle。你一上来开几十个优先级，最后只会得到一张自己都看不懂的任务关系网。

ARM_CM4F 可以打开 configUSE_PORT_OPTIMISED_TASK_SELECTION，让内核用 Cortex-M 的指令快速找最高优先级任务。不过开了以后 configMAX_PRIORITIES 不能超过 32，这点记住就行。

3. 任务附加能力

1
2
3
4
5


#define configMAX_TASK_NAME_LEN 16
#define configMINIMAL_STACK_SIZE 128
#define configTASK_NOTIFICATION_ARRAY_ENTRIES 1
#define configNUM_THREAD_LOCAL_STORAGE_POINTERS 0
#define configUSE_APPLICATION_TASK_TAG 0

任务名长度设 16，调试器里能看清名字就行。通知槽第一版一个也够用，线程局部指针和 Task Tag 暂时都关掉。

重点还是 configMINIMAL_STACK_SIZE。这个 128 不是 128 字节。ARM_CM4F 的 StackType_t 是 32 位，所以这里实际是：

1

128 word × 4 byte = 512 byte

而且它主要是 Idle Task 的栈大小，不代表所有任务都照着 128 抄。任务里要是有大数组、浮点计算、printf，栈很快就能给你吃干净。后面一定要看栈水位，不能凭感觉拍一个数字。

4. 任务通信与同步

1
2
3
4
5
6
7


#define configUSE_TASK_NOTIFICATIONS 1
#define configUSE_MUTEXES 1
#define configUSE_RECURSIVE_MUTEXES 0
#define configUSE_COUNTING_SEMAPHORES 1
#define configUSE_QUEUE_SETS 0
#define configUSE_EVENT_GROUPS 0
#define configUSE_STREAM_BUFFERS 0

这一组看着多，其实就是任务之间怎么说话。

Task Notification：一对一通知，快而且省内存，能用它就先用它。
Queue：真的有数据要传，比如传一帧传感器结构体，就用队列。
Semaphore：做事件同步或者资源计数。
Mutex：保护共享资源，它有优先级继承，不要拿二值信号量硬顶。
Event Group：用几个 bit 同时等多个事件。
Stream Buffer：连续字节流，串口接收这类场景比较常见。
Message Buffer：底层还是 Stream Buffer，但是会保留消息边界。

Queue、Semaphore、Mutex 都主要在 queue.c 里；Event Group 需要 event_groups.c；Stream 和 Message Buffer 需要 stream_buffer.c。

中断里又是另一套规矩，只能调用带 FromISR 的接口：

1
2
3
4


BaseType_t xHigherPriorityTaskWoken = pdFALSE;

vTaskNotifyGiveFromISR(xTaskHandle, &xHigherPriorityTaskWoken);
portYIELD_FROM_ISR(xHigherPriorityTaskWoken);

最后这个 portYIELD_FROM_ISR() 不是装饰品。中断唤醒了更高优先级任务，就应该让它在退出中断后马上运行。

5. 软件定时器

1
2
3
4


configUSE_TIMERS
configTIMER_TASK_PRIORITY
configTIMER_TASK_STACK_DEPTH
configTIMER_QUEUE_LENGTH

软件定时器开启以后，FreeRTOS 会多创建一个 Timer Service Task。所有软件定时器到期，最终都是这个任务来执行回调。

所以它和硬件定时器完全不是一回事。回调不是在某个神秘的精准时刻凭空执行，它得排队，还会受 Timer Task 优先级和其他回调耗时影响。

第一版不用就直接：

1

#define configUSE_TIMERS 0

要用就把 timers.c 编进来，再配置任务优先级、栈和命令队列长度。回调里别延时，别疯狂打印，更别塞一大坨计算。一个回调卡住，后面的定时器全跟着排队。

6. 内存、堆和任务栈

1
2
3
4
5
6
7


#define configSUPPORT_STATIC_ALLOCATION 0
#define configSUPPORT_DYNAMIC_ALLOCATION 1
#define configTOTAL_HEAP_SIZE (32 * 1024)
#define configAPPLICATION_ALLOCATED_HEAP 0
#define configSTACK_ALLOCATION_FROM_SEPARATE_HEAP 0
#define configENABLE_HEAP_PROTECTOR 0
#define configHEAP_CLEAR_MEMORY_ON_FREE 0

这里先按 heap_4.c + 动态分配 来。heap_4.c 能释放，也会合并相邻空闲块，对这种普通 MCU 工程够用了。

configTOTAL_HEAP_SIZE 是 FreeRTOS 自己的堆，动态创建出来的任务栈、TCB、队列和信号量都从这里拿内存。它和链接脚本里的 C 库堆不是一回事，也不会自动接管普通 malloc()。

上面写 32 KB 只是一个起步例子，不是说所有工程都必须 32 KB。最后到底要多少，得把每个任务栈、队列长度、对象数量都算进去，再配合：

1
2
3


xPortGetFreeHeapSize();
xPortGetMinimumEverFreeHeapSize();
uxTaskGetStackHighWaterMark();

这里还有个经典坑：configTOTAL_HEAP_SIZE 的单位是字节，但是 xTaskCreate() 的栈深度在 ARM_CM4F 上通常是 32 位 word。两个数字放在一起很像，单位完全不一样。

configAPPLICATION_ALLOCATED_HEAP = 0 表示 ucHeap[] 还是由 heap_4.c 自己定义；设成 1 以后就得由应用提供。任务栈单独放进另一块内存、释放时清零、堆指针保护这些东西第一版也先关，真有对应需求再开。

静态分配以后再单独讲。它不是把开关改成 1 就结束了，Idle Task 的静态内存得自己提供；如果开了软件定时器，Timer Task 的内存也一样。

7. 中断与临界区

这一组真得认真看。前面那些东西配错，大不了功能不对；中断优先级配错，经常是平时能跑，一上负载就随机爆炸，最恶心。

STM32F407 有 4 个 NVIC 优先级位。这里按 4 位全部用于抢占优先级、不分子优先级来配：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


#define configPRIO_BITS 4
#define configLIBRARY_LOWEST_INTERRUPT_PRIORITY 15
#define configLIBRARY_MAX_SYSCALL_INTERRUPT_PRIORITY 5

#define configKERNEL_INTERRUPT_PRIORITY \
 (configLIBRARY_LOWEST_INTERRUPT_PRIORITY << (8 - configPRIO_BITS))

#define configMAX_SYSCALL_INTERRUPT_PRIORITY \
 (configLIBRARY_MAX_SYSCALL_INTERRUPT_PRIORITY << (8 - configPRIO_BITS))

#define configCHECK_HANDLER_INSTALLATION 1

Cortex-M 的优先级数字越小，实际优先级反而越高，这个反人类设计先接受。

按上面这套配置：

1
2
3


优先级 0 ~ 4 不会被 FreeRTOS 临界区挡住，但禁止调用 FreeRTOS API
优先级 5 ~ 15 可以调用对应的 xxxFromISR() API
优先级 15 给 SysTick 和 PendSV，放到最低

configMAX_SYSCALL_INTERRUPT_PRIORITY 千万不能填 0。还有，CMSIS 里写的优先级 5 是没左移的逻辑值，FreeRTOS 这里要的是左移后写进寄存器的值。网上很多教程两个混着写，抄完还能跑只能说命硬。

configCHECK_HANDLER_INSTALLATION = 1 会检查 SVC 和 PendSV 有没有正确挂进向量表，但它依赖 configASSERT。这两个要一起开，不然新版内核会直接编译报错。

8. Hook 回调

1
2
3
4
5


#define configUSE_IDLE_HOOK 0
#define configUSE_TICK_HOOK 0
#define configUSE_MALLOC_FAILED_HOOK 1
#define configUSE_DAEMON_TASK_STARTUP_HOOK 0
#define configUSE_SB_COMPLETED_CALLBACK 0

Hook 就是 FreeRTOS 在几个固定时机回调你写的函数。

Idle Hook 会跟着 Idle Task 跑，Tick Hook 每个 Tick 都会进，而且是在中断上下文里。第一版都先关，尤其别在 Tick Hook 里打印日志，那是在给自己制造新问题。

但是 configUSE_MALLOC_FAILED_HOOK 我建议调试阶段直接打开：

1
2
3
4
5
6
7
8


void vApplicationMallocFailedHook(void)
{
 taskDISABLE_INTERRUPTS();

 for (;;)
 {
 }
}

内存分配失败以后停在这里，至少调试器能告诉你是堆没了。不开的话，错误可能继续往后传，最后在一个毫不相干的地方炸掉，到时候又要查半天。

9. 故障检测、断言与统计

1
2
3
4
5


#define configCHECK_FOR_STACK_OVERFLOW 2
#define configGENERATE_RUN_TIME_STATS 0
#define configUSE_TRACE_FACILITY 0
#define configUSE_STATS_FORMATTING_FUNCTIONS 0
#define configQUEUE_REGISTRY_SIZE 0

configCHECK_FOR_STACK_OVERFLOW = 2 会检查任务栈末尾的填充值有没有被踩。开了以后还要实现：

1

void vApplicationStackOverflowHook(TaskHandle_t xTask, char *pcTaskName);

然后是 configASSERT，调试阶段别关：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


#define configASSERT(x) \
 do \
 { \
 if ((x) == 0) \
 { \
 taskDISABLE_INTERRUPTS(); \
 for (;;) \
 { \
 } \
 } \
 } while (0)

FreeRTOS 很多错误不是靠返回一个 error 告诉你，而是靠断言把程序钉在现场。中断优先级配错、参数不合法、Handler 没挂好，都可能从这里抓出来。

运行时间统计、Trace、格式化任务列表先关。它们当然有用，但运行时间统计还需要额外的高频计数器，格式化函数又会把字符串处理带进来。先把系统跑起来，后面需要分析 CPU 占用时再开。

10. C 库与 POSIX 兼容

1
2
3


#define configUSE_NEWLIB_REENTRANT 0
#define configUSE_POSIX_ERRNO 0
#define configENABLE_BACKWARD_COMPATIBILITY 0

这一组第一版全关。

configUSE_POSIX_ERRNO 只是让每个任务有自己的 FreeRTOS_errno，不是说打开以后 FreeRTOS 就突然变成 Linux 了。

configUSE_NEWLIB_REENTRANT 会给每个任务塞一份 Newlib 重入状态，内存开销也会跟着涨。而且它不等于“从此 printf 随便多线程调用都安全”。串口日志最好还是统一丢给一个日志任务，或者至少用互斥锁保护。

新工程也没必要兼容一堆旧 API 名字，所以 configENABLE_BACKWARD_COMPATIBILITY 关掉。

11. 旧协程

1
2


#define configUSE_CO_ROUTINES 0
#define configMAX_CO_ROUTINE_PRIORITIES 0

这个东西是给 RAM 极小的老设备准备的。它没有普通任务那样的独立栈，走的还是合作式调度。

F407 又不是穷到这点内存都没有，没必要为了省一点 RAM 同时养两套调度模型。关掉，也不用编译 croutine.c。

12. MPU、TrustZone 与安全隔离

1
2
3
4


configENABLE_MPU
configENABLE_TRUSTZONE
configRUN_FREERTOS_SECURE_ONLY
configENABLE_FPU

这几个宏出现在通用模板的 ARMv8-M 配置区里。F407 是 ARMv7-M Cortex-M4F，没有 TrustZone，所以不要照着模板把它们全抄进来。

F407 自己有 MPU，但我们现在选的是标准 portable/GCC/ARM_CM4F，不是 ARM_CM4_MPU。只定义一个 configENABLE_MPU 没用，真正做 MPU 隔离还得换端口、划内存区域、区分特权任务和非特权任务，这已经是下一阶段的东西了。

configTOTAL_MPU_REGIONS 和 configUSE_MPU_WRAPPERS_V1 也都是 MPU 端口才会认真处理的东西。标准 ARM_CM4F 端口下先不用管。

至于 FPU，选中 ARM_CM4F 端口并使用正确的浮点编译参数后，端口会负责浮点上下文；这里也不用额外定义 configENABLE_FPU。这个宏主要是给模板里对应的 ARMv8-M 端口准备的。

13. 多核 SMP

1
2
3


#define configNUMBER_OF_CORES 1
#define configRUN_MULTIPLE_PRIORITIES 0
#define configUSE_CORE_AFFINITY 0

STM32F407 就一个 Cortex-M4F 核心，这组没什么好纠结的。核心数设 1，亲和性关掉，定时器任务绑哪个核这种问题也和我们没关系。

所以 configTASK_DEFAULT_CORE_AFFINITY、configTIMER_SERVICE_TASK_CORE_AFFINITY 这些宏可以直接忽略，它们是多核开启以后才有意义。

官方模板是给所有端口看的，所以里面出现 SMP 不代表 F407 突然长出了第二个核。

14. API 裁剪开关

最后这组 INCLUDE_* 不是在选择调度模式，它只是决定某个 API 要不要编进来。

比如：

1

#define INCLUDE_vTaskDelay 1

开了以后才能用 vTaskDelay()。第一版我会先保留这些：

1
2
3
4
5
6


#define INCLUDE_vTaskDelay 1
#define INCLUDE_xTaskDelayUntil 1
#define INCLUDE_vTaskDelete 1
#define INCLUDE_xTaskGetSchedulerState 1
#define INCLUDE_xTaskGetCurrentTaskHandle 1
#define INCLUDE_uxTaskGetStackHighWaterMark 1

周期任务尽量用 xTaskDelayUntil()，它是按固定时间点唤醒，比“运行完再延时一段时间”更适合做稳定周期。

下面这些没有明确需求就先关：

1
2
3
4
5
6


#define INCLUDE_vTaskSuspend 0
#define INCLUDE_eTaskGetState 0
#define INCLUDE_xTaskAbortDelay 0
#define INCLUDE_xTaskGetHandle 0
#define INCLUDE_xTimerPendFunctionCall 0
#define INCLUDE_xTaskResumeFromISR 0

尤其别把 vTaskSuspend() 当成万能同步工具。任务之间有事件关系，就老老实实用通知、信号量或者队列，不然代码跑着跑着就不知道是谁把谁挂起了。

总结一下

这么一大串看完，其实真正的优先级就几条：

先确认 CPU 真实时钟和 Tick 频率，不然所有时间都是假的。
把 NVIC 分组和 FreeRTOS 中断优先级配对，搞清楚哪些中断能调用 FromISR。
打开 configASSERT、栈溢出检查和 Malloc Failed Hook，让程序死也死得明白。
算任务栈和 FreeRTOS 堆，别拿“现在还没崩”当内存够用的证据。
软件定时器、事件组、Stream Buffer 用到哪个再开哪个。
协程、MPU、TrustZone、SMP 暂时全部放一边。

所以 FreeRTOSConfig.h 不是官方宏大全，更不是把所有功能都设成 1 就完事。它应该老老实实记录这块板子现在跑多快、任务怎么调度、中断能做到什么程度、内存又准备拿出多少。这个文件配明白了，FreeRTOS 才算真的进了自己的工程，而不是从别人的 Demo 里复制过来勉强亮机。

RTOS 前传：先把IDE的编译黑盒拆了

Sun, 16 Aug 2026 01:42:00 +0800

RTOS 前传：先把IDE的编译黑盒拆了

之前其实学过 RTOS，但那时候纯纯把它当黑盒来用：会创建任务、会调度，能跑起来就完事了。CMake 也差不多，自己甚至没怎么手写过。

我发现自己每次开学，工程能力都会 ++；每次一放长假，又会再进化一次。原因可能也很简单：假期里有时间把那些最基础、最底层的东西重新磨一遍。刀磨了一整个假期，开学当然砍得更快。

所以接下来准备更新一个新篇章，重新学 RTOS。这次以 STM32F407VET6 为例，不急着上操作系统，先从最基础的工程开始：补齐启动文件、系统初始化文件和链接脚本，再亲手写好 CMake，让它真的编译起来。

这一篇就是前传。看懂它最好有一点汇编语言和微机原理基础，不然中间可能会有点吃力。

本系列均使用编辑器 + CLI，拒绝一切丑陋的 IDE，比如 Keil CubeMX。用 Keil 的你一辈子没法成长 ,就等着找底薪工作吧。

先把官方仓库拉下来

先克隆 ST 官方的 STM32CubeF4 仓库。里面有一堆库、驱动和例程，也有我们需要的启动文件。

这个仓库其实挺大，只想拿来搭工程的话，浅克隆就够了：

1

gh repo clone STMicroelectronics/STM32CubeF4 -- --depth 1 --recursive

相比完整克隆，体积能小一半以上，快多了。没必要为了三个文件把整个 Git 历史请回家供着。

接下来把工具配齐：

arm-none-eabi-gcc
gdb-multiarch
cmake
ninja
openocd

我自己都安装过了，这里就不演示了。

一个最小工程需要什么

先从 CubeF4 里复制三个关键文件：

1
2
3
4


F407_RTOS_EXAMPLE/
├── Startup/startup_stm32f407xx.s
├── Platform/system_stm32f4xx.c
└── linker/STM32F407VETX_FLASH.ld

官方仓库里比较容易找到的是 STM32F407VGTX_FLASH.ld。它也能拿来改，但一定要注意：F407VGT6 有 1 MB Flash，这里使用的 F407VET6 只有 512 KB Flash。复制之后要把链接脚本改对，最好顺手重命名，免得哪天把自己也骗了。

最基础的文件结构大概这样：

这几个文件到底是干啥的？这就要从编译开始说了。之前说用 IDE 的永远不会成长，原因就在这里：一点 Build，后面的东西全黑了。你只知道没报错，牛逼，可以烧录；或者突然蹦出一个 error，卧槽，牛魔的，快修改。

但我们写的一堆 .c、.h，到底是怎么变成 MCU 能执行的机器码的？大致流程其实就这一条：

1
2
3
4
5
6
7
8
9


C / 汇编源码
 ↓ 编译、汇编
.o 目标文件
 ↓ 链接脚本安排地址
ELF
 ↓ objcopy
BIN / HEX
 ↓ OpenOCD
STM32 Flash

`arm-none-eabi` 这一家子

先简单认一下工具链，后面报错时至少知道该骂谁：

工具	作用
`arm-none-eabi-gcc`	编译 C，也可以统一调用汇编器和链接器
`arm-none-eabi-as`	把汇编代码变成`.o`
`arm-none-eabi-ld`	把一堆`.o` 链接成 ELF
`arm-none-eabi-objcopy`	把 ELF 转成 BIN 或 HEX
`arm-none-eabi-objdump`	看段信息和反汇编
`arm-none-eabi-nm`	看符号和地址
`arm-none-eabi-size`	看 Flash 和 RAM 占用
`arm-none-eabi-gdb`	调试正在运行的程序

arm-none-eabi 也不是什么神秘咒语：

1
2
3


arm → 目标架构是 ARM
none → 不针对某个操作系统
eabi → 使用嵌入式应用二进制接口

至于 MCU 是哪个内核，则由编译参数告诉 GCC，比如 F407 是 Cortex-M4，F1 常见型号是 Cortex-M3。-mcpu=cortex-m4 -mthumb 这类参数就该出现在工具链或 CMake 配置里。

真正决定“代码放到 Flash 哪儿、变量放到哪块 RAM”的，是下面这个文件。

1. 链接脚本：告诉链接器这个家有多大

文件：linker/STM32F407VETX_FLASH.ld

链接脚本干的事很直接：

老子是什么型号？RAM、Flash 多大？每一段程序到底放哪里？

首先是程序入口：

1

ENTRY(Reset_Handler)

这表示固件的入口符号是启动文件里的 Reset_Handler。

然后计算栈顶：

1

_estack = ORIGIN(RAM) + LENGTH(RAM);

再描述物理内存。以 STM32F407VET6 为例：

1
2
3
4
5
6


MEMORY
{
 CCMRAM (xrw) : ORIGIN = 0x10000000, LENGTH = 64K
 RAM (xrw) : ORIGIN = 0x20000000, LENGTH = 128K
 FLASH (rx) : ORIGIN = 0x08000000, LENGTH = 512K
}

这里必须和手上的芯片对得上。写小一点一般只是浪费空间，写大了却可能把程序链接到根本不存在的 Flash 里，到时候就不是“为什么没亮”这么温柔了。

所以 IDE 里选择芯片型号，不只是让界面左上角多一串字；它背后也在替你选启动文件、链接脚本和编译参数。IDE 帮你做了不代表这些东西不存在，只是以前它们被藏起来了。

一句话总结：arm-none-eabi-ld 负责链接，.ld 负责告诉它怎样安排 STM32 的内存。

2. `startup_stm32f407xx.s`：上电后第一棒

第二个关键文件是：Startup/startup_stm32f407xx.s。

它有两重身份。构建时，它先被汇编成目标文件，再和 main.o、system_stm32f4xx.o 一起链接：

1
2
3
4
5
6
7


startup_stm32f407xx.s
 ↓ 汇编
startup_stm32f407xx.o
 ↓ 和其他 .o 一起链接
app.elf
 ↓ 烧录
STM32 Flash

它主要贡献几块内容：

1
2
3


.isr_vector 中断向量表
.text.Reset_Handler 复位启动代码
.text.Default_Handler 默认中断处理代码

链接器再根据 .ld 文件，把向量表和代码放进 Flash。

不过，CPU 并不是从 .s 文件第一行开始往下读。像 .syntax、.cpu、.section、.word 这些，大多是给汇编器看的指令或者数据，不是 CPU 上电后逐句执行的代码。

假设 BOOT0 = 0，芯片从内部 Flash 启动，硬件会先读取向量表前两项：

1
2


0x08000000 的 32 位数 → 装进 MSP，成为初始栈顶
0x08000004 的 32 位数 → 装进 PC，跳到复位入口

对应到启动文件里就是：

1
2
3


g_pfnVectors:
 .word _estack
 .word Reset_Handler

于是整个过程变成：

1
2
3
4
5
6
7
8
9


上电 / 复位
 ↓
CPU 读取 _estack
 ↓
CPU 读取 Reset_Handler 地址
 ↓
跳进 Reset_Handler
 ↓
SystemInit → 初始化 .data/.bss → main

所以更准确的说法不是“CPU 从 startup 第一行开始执行”，而是：

CPU 根据 startup 生成的向量表找到 Reset_Handler，再开始执行它生成的复位代码。

到这里，.s 文件也没那么吓人了。它本质上就是在 C 世界开门之前，先把栈、内存和入口准备好。

3. `system_stm32f4xx.c`：终于回到舒适区

最后一个关键文件是 Platform/system_stm32f4xx.c。唯一一个 .c，是不是瞬间亲切多了？

这个文件来自 CMSIS，处在 startup 和 main() 之间：

1
2
3
4
5
6
7


Reset_Handler
 ↓
SystemInit() ← system_stm32f4xx.c
 ↓
初始化 .data/.bss
 ↓
main()

启动文件里会调用：

1

bl SystemInit

但 startup.o 自己没有这个函数。链接时，ld 会去 system_stm32f4xx.o 里把同名符号找出来。之前那一大家子工具到这里终于串上了。

这个文件里最值得先认识的是三个东西：

1
2
3


void SystemInit(void);
void SystemCoreClockUpdate(void);
uint32_t SystemCoreClock;

`SystemInit()`

它会在复位后、进入 main() 前运行，主要负责把 RCC 恢复到一个确定的基础状态、打开 HSI、处理 FPU 访问权限，以及按配置设置向量表或外部存储器。

它一般不会替你完成这些事：

配置最终的 168 MHz 主频
初始化 GPIO 和串口
初始化 HAL
初始化 FreeRTOS

这些还是后面的板级初始化代码来干。

这时候就有看到这里的吴彦祖、彭于晏困惑了：我不是已经在 CubeMX 的时钟树里把主频改成 168 MHz 了吗，怎么这里还是 16 MHz？

因为 CubeMX 生成的时钟配置，是进入后续初始化阶段才执行的。SystemInit() 只是先把芯片送回一个大家都认识的起点，然后你的代码再去开 HSE、配 PLL、切系统时钟。

`SystemCoreClock`

1

uint32_t SystemCoreClock = 16000000;

它只是一个记录当前 HCLK 的软件变量，很多地方会拿它计算 SysTick、RTOS Tick、串口波特率和定时器参数。

注意，它不是许愿池。你直接写：

1

SystemCoreClock = 168000000;

并不会让 MCU 原地超频到 168 MHz，只会让软件以为它已经到了。真正的时钟还是得改 RCC 寄存器，然后调用 SystemCoreClockUpdate() 重新读取并计算。

`HSE_VALUE`

HSE_VALUE 表示软件认为外部晶振是多少 Hz：

1
2
3


#ifndef HSE_VALUE
#define HSE_VALUE 25000000U
#endif

这不代表程序已经启用了 25 MHz HSE，更不代表你板子上真的焊了 25 MHz 晶振。板子是 8 MHz，就应该通过编译宏传入正确的值：

1

target_compile_definitions(app PRIVATE HSE_VALUE=8000000U)

要不然硬件跑它的，软件算软件的，最后两边各过各的。

还有一个容易漏掉的点：这份启动文件会在 .data 复制和 .bss 清零之前调用 SystemInit()。所以它不能随便依赖已经初始化好的普通全局变量、堆或者完整的 C 运行库，主要还是直接操作硬件寄存器。

一句话总结：

startup 负责把 C 程序的运行环境搭起来，system_stm32f4xx.c 负责把 Cortex-M4 和 STM32F4 拉回一个确定的基础状态，后面的 Platform 代码再配置这块板真正需要的时钟和外设。

最后交给 CMake

必备文件当然还有 main.c，这我就懒得说了。剩下主要是两个和 CMake 有关的文件：

1
2


arm-none-eabi-gcc.cmake # 指定交叉编译工具链和 CPU 参数
CMakeLists.txt # 描述源文件、头文件、链接脚本和产物

工具链文件告诉 CMake 去哪里找 arm-none-eabi-gcc，目标是 Cortex-M4，要使用什么浮点 ABI；CMakeLists.txt 再把 startup、system、main 和链接脚本串起来，最后顺手生成 .elf、.bin、.hex。

具体 CMake 我这里就不展开了。了解基本逻辑之后完全可以让 AI 写，再自己检查参数和路径。这里还要顺便吐槽一下 py：这种东西简单到极致，有啥难度，用的时候学就行了，我完全不知道刻意学习的意义在哪里。

写好之后，工程结构如下：

然后：

1
2


cmake -S . -B build -G Ninja
cmake --build build

哦也，能编译了。

恭喜你亲手拆开了 IDE 的编译黑盒。下一步再往里面塞 RTOS，至少这次知道它到底站在什么东西上面了。牛逼吧。

Zephyr 入门（二）：设备树是什么，应用怎样使用它

Fri, 10 Jul 2026 00:40:00 +0800

Lesson 2: 设备树是什么，应用怎样使用它

上一课的闪灯程序里有这样一行：

1

GPIO_DT_SPEC_GET(DT_ALIAS(led0), gpios)

它看起来没有写 GPIO 端口和引脚号，却能找到板上的 LED。这一课就把这条线拆开：led0 从哪里来，它怎样变成具体硬件，以及为什么换一块兼容的板后，应用代码有机会不改。

设备树是在替应用保管硬件细节

假设一块板把用户 LED 接在 gpio0 的 12 号引脚，另一块板把它接在 gpio1 的 7 号引脚。如果在应用中写死端口和引脚：

1

HAL_GPIO_TogglePin(GPIOC, GPIO_PIN_13);

这段代码就把“闪灯逻辑”和“这块板的接线”绑在了一起。换板时，功能本身没变，仍然只是闪灯，却要回到业务代码里找引脚号。

Zephyr 的做法是把接线关系放进设备树。应用只说“我想操作默认 LED”或“我想使用这个 I2C 传感器”；设备树负责回答它接在哪个控制器、占用哪个引脚、地址和中断是什么。可以把它看成开发板附带的一张硬件清单：应用不必记住仓库里每个零件的位置，只需要按清单取用。

1
2
3
4
5
6
7
8


应用 C 代码
 使用 led0、uart0、传感器节点等逻辑入口
 |
设备树
 记录控制器、引脚、总线、地址、中断和连接关系
 |
驱动
 根据这些参数操作实际外设

设备树不会凭空让所有程序跨板运行。目标板需要有对应硬件描述和驱动；但当两块板都提供相同的逻辑入口时，应用不再需要关心 LED 实际接到 P0.13 还是 P1.7。

一份设备树从哪里拼出来

以一块 STM32 开发板为例，最终设备树通常不是单个文件，而是几层描述叠加的结果。以下路径都相对于 zephyr/ 源码根目录：

1
2
3
4
5
6
7
8


boards/<厂商>/<开发板>/<开发板>.dts
 板级硬件：板载 LED、按键、晶振、默认串口、外接器件等。

dts/<架构>/<厂商>/<SoC 系列>/*.dtsi
 SoC 硬件：片内 UART、GPIO、I2C、SPI、时钟、中断和内存地址。

dts/bindings/
 binding YAML：说明 compatible 对应的设备类型、属性和参数格式。

可以这样理解它们的分工：SoC 的 .dtsi 先说明“芯片里有几路 I2C、每路在哪个地址”；开发板的 .dts 再说明“这块板把 LED 接到了哪个引脚”；应用 overlay 最后补充“这次项目要在 I2C0 上接一个传感器”。

应用不应该直接改 Zephyr 自带的板级 DTS，否则升级 Zephyr 或切换版本时很难维护。通常在应用目录里添加 overlay：

1
2


<application>/app.overlay
<application>/boards/<board>.overlay

构建后要看的不是某一层输入，而是最终合并结果：

1
2


build/zephyr/zephyr.dts
build/zephyr/include/generated/devicetree_generated.h

如果你在 overlay 中改了 LED 引脚，实际却没有变化，先打开 build/zephyr/zephyr.dts 搜索 led0 或节点标签。它才是本次构建真正采用的硬件清单。

先分清四个容易混淆的名字

同一个设备在 DTS 中可能有几种名字，刚开始很容易看花：

1
2
3
4


节点名 DTS 树中的名字，例如 led_0、serial@4000xxxx。
节点标签 供 DTS 内部引用的名字，例如 led0:、uart0:，引用时写 &led0。
属性 节点的参数，例如 gpios、reg、status、compatible。
alias /aliases 下给应用的逻辑名字，例如 led0、sw0。

可以把节点标签理解为设备树内部的“书签”，而 alias 更像留给应用的快捷入口。两者名字可以相同，但不是同一个概念。尤其要记住：DT_ALIAS(led0) 查的是 /aliases 中的 led0，不是节点名，也不是节点标签。

例子：从 `led0` 找到真实引脚

下面是一段简化的板级 DTS。它把真实 LED 映射为通用别名：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


/ {
 leds {
 compatible = "gpio-leds";

 user_led: led_0 {
 gpios = <&gpio0 12 GPIO_ACTIVE_HIGH>;
 };
 };

 aliases {
 led0 = &user_led;
 };
};

这里的 user_led 是节点标签，led_0 是节点名。真正描述接线的是 gpios：LED 连到 gpio0 的 12 号引脚，高电平有效。aliases 则给它起了一个跨板更好使用的名字 led0。

应用只要取这个别名：

1
2
3
4


#include <zephyr/drivers/gpio.h>

#define LED_NODE DT_ALIAS(led0)
static const struct gpio_dt_spec led = GPIO_DT_SPEC_GET(LED_NODE, gpios);

这段代码并不是运行时去读取一个配置文件。宏会在编译期一路展开：

1
2
3
4
5
6


DT_ALIAS(led0)
 -> /aliases 中的 led0
 -> user_led 节点
 -> gpios 属性
 -> GPIO 控制器、12 号引脚、有效电平
 -> struct gpio_dt_spec

随后就可以调用 gpio_pin_configure_dt()、gpio_pin_set_dt() 或 gpio_pin_toggle_dt()。若另一块板把默认 LED 定义为 led0，它可以接在完全不同的引脚上，而这段应用逻辑不必知道。

例子：给项目接一个 I2C 传感器

再看一个更接近项目的场景：开发板已经有 i2c0，但板级 DTS 没有写你的 BME280 传感器。此时不需要复制整份板级 DTS，只要在应用的 app.overlay 中补上一段：

1
2
3
4
5
6
7
8


&i2c0 {
 status = "okay";

 bme280: sensor@76 {
 compatible = "bosch,bme280";
 reg = <0x76>;
 };
};

这段话可以顺着读：找到已有的 i2c0；确保它启用；在这条总线上声明一个地址是 0x76 的设备；它遵循 bosch,bme280 这份 binding 的规则。bme280: 是节点标签，因此 C 代码可以按标签取到设备：

1
2
3


#include <zephyr/device.h>

const struct device *sensor = DEVICE_DT_GET(DT_NODELABEL(bme280));

设备树到这里解决的是“传感器接在哪里、是什么类型”。它还不保证传感器一定可用：对应的驱动必须被 Kconfig 编译进固件，运行前也应该用 device_is_ready(sensor) 检查设备是否准备好。下一课的 Kconfig 正好解释这个条件。

DTS、DTSI、overlay 和 binding 各自负责什么

回看上面的两个例子，这四类文件的边界就比较清楚了：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


SoC .dtsi
 描述芯片内部已有的外设资源，好比芯片的数据手册。

板级 .dts
 描述开发板怎样使用这些资源，例如 LED 和按键接在哪里。

应用 overlay
 描述当前应用新增、启用或修改的硬件，例如接入自己的传感器。

binding YAML
 定义某种 compatible 允许哪些属性、数据格式和约束，像一份填写规则。

构建系统把它们合并成 build/zephyr/zephyr.dts，再生成 C 宏头文件。设备树不是运行时配置文件，所有宏都在编译期展开；改了 overlay 后必须重新构建，固件里的描述才会更新。

本课结论

设备树回答“硬件有什么、怎样连接、参数是什么”，应用代码再用设备树宏把这些信息交给驱动 API。读设备树时，先从板级 .dts 看这块板怎样接线；需要了解片内资源时再追到 SoC .dtsi；不清楚某个属性怎么写时查 binding；改完后始终以 build/zephyr/zephyr.dts 为准。

下一课会看 Kconfig：设备树已经说清“这里接着一颗 BME280”，Kconfig 还要决定“它的驱动是否真的进入这次固件”。

Zephyr 入门（一）：认识 Zephyr 工程

Fri, 10 Jul 2026 00:30:00 +0800

这一系列想从 Zephyr 入门开始，补上之前一直想写却没动笔的内容。

Lesson 1: 认识 Zephyr 工程

Zephyr 是一个面向资源受限设备的开源实时操作系统（RTOS）。它有线程、调度和同步这些内核能力，但它想管的不只是“任务怎么调度”：驱动、硬件描述、配置、板级支持和构建流程也被放进了同一套体系。

先想一个最常见的练习：每隔一秒翻转一次 LED。用 FreeRTOS 时，任务里的延时可以写成 vTaskDelay()；但 LED 在哪个引脚、GPIO 时钟怎样开、引脚怎样初始化，仍要由 STM32 HAL、TI DriverLib 或其他厂商库处理。任务代码可以不变，换一块板后，HAL_GPIO_TogglePin(GPIOC, GPIO_PIN_13) 这类外设代码和初始化往往还是得跟着改。

Zephyr 希望把这部分差异挪到应用代码之外。应用更接近下面这种写法：

1
2
3


static const struct gpio_dt_spec led = GPIO_DT_SPEC_GET(DT_ALIAS(led0), gpios);

gpio_pin_toggle_dt(&led);

这里没有出现 GPIOC 或 PIN_13。应用只说“切换这块板的默认 LED”；led0 到底接在哪个 GPIO 控制器、哪个引脚，以及应该选用哪一个 GPIO 驱动，由开发板的设备树和 Kconfig 配置决定。换到另一块已支持、也提供 led0 的板时，这段闪灯逻辑可以保持不动，只需要重新选择目标板构建。

这不是魔法，也不是硬件差异消失了。可以把设备树看成一张接线和设备清单：它把“LED 接在 P0.13”这样的事实放在板级描述里，而不是散落在应用业务代码中。DMA、低功耗、特殊时钟等功能仍然要面对具体芯片的能力和限制；只是普通应用不必反复触碰同一组寄存器和引脚号。

这也是 Zephyr 值得学习、同时需要先熟悉工程体系的原因。它适合 MCU、传感器节点、可穿戴设备等需要实时性和较小资源占用的场景，也覆盖了从小型开发板到部分带 MMU 的平台。刚接触时，最容易困惑的往往不是 API，而是应用、配置、设备树和驱动究竟怎样配合。

这一课先不急着读内核。先建立整体印象：一份闪灯应用从哪些文件得到“这块板有什么”，又如何变成可以烧录的固件。理解了这条线，再回头读线程和调度会顺得多。

先看整个工作区

用 West 初始化后的工作区通常长这样：

1
2
3
4
5


workspace/
├── .west/ West 工作区配置
├── zephyr/ Zephyr RTOS 源码
├── modules/ 第三方模块，例如 CMSIS、芯片 HAL
└── my-application/ 自己的应用工程

可以把这个目录想成一个项目工地：my-application 是你正在写的产品代码，zephyr 是公共框架和基础设施，modules 放着芯片厂商和第三方提供的零件。Zephyr SDK 不在工地里，它安装在开发电脑上，提供交叉编译器、链接器等工具；它不属于 Zephyr 源码，也不会被烧录进开发板。

刚开始最值得盯住的是两处：

1
2


my-application/ 应用代码、应用配置、设备树覆盖
zephyr/ RTOS、驱动、设备树、板级支持和构建规则

west、SDK 和 modules/hal/<vendor>/ 当然都重要，但前期不需要急着读实现。它们的作用分别是管理多个仓库、提供工具链，以及承载厂商 HAL；应用通常会通过 Zephyr 的驱动间接使用这些 HAL。

West 到底负责什么

Git 管理单个仓库的历史，West 管理的是一组彼此有依赖关系的仓库。可以把它理解为项目的“装配清单”：zephyr/west.yml 记录 CMSIS、芯片 HAL 等模块该放在哪里、要使用哪个版本。执行：

1

west update

West 会把工作区同步到清单指定的状态。比如同一个 Zephyr 版本需要某个版本的 STM32 HAL，west update 会按清单取回匹配版本，避免每个人手动拼一套不兼容的仓库。它还把构建、烧录和调试入口统一起来：

1
2
3


west build -b <board> <application-directory>
west flash
west debug

不过 West 本身不编译 C 代码。真正干活的是 Zephyr 的 CMake 构建系统、构建工具和交叉编译器；West 更像是把这些步骤组织到同一个命令入口下。

一份应用怎样变成固件

还是以闪灯程序为例。main.c 只写“翻转 LED”，但编译器还不知道这颗 LED 接在哪里、GPIO 驱动要不要编进去。应用代码并不是直接丢给编译器，而是先经过配置和硬件描述的合并：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


src/main.c
 |
 v
CMakeLists.txt
 find_package(Zephyr ...): 引入 Zephyr 构建系统
 target_sources(...): 将应用源文件加入 app 目标
 |
 v
prj.conf
 选择需要的 Kconfig 功能，例如 GPIO、日志、线程
 |
 v
板级 DTS + SoC DTSI + 应用 overlay
 描述目标硬件，以及应用对硬件描述的修改
 |
 v
生成最终设备树、最终 Kconfig 和设备树 C 宏
 |
 v
交叉编译并链接
 |
 v
zephyr.elf / zephyr.bin

构建目录不是可以完全忽略的临时垃圾，它像是构建系统交卷前留下的草稿。比如你把 led0 指到另一个引脚，却发现灯没有变化；这时先看最终合并出的设备树，而不是靠猜。遇到“明明改了配置却没生效”这类问题，也先来这里确认：

1
2
3
4
5
6
7
8


build/zephyr/zephyr.dts
 最终合并后的设备树。

build/zephyr/.config
 最终生效的 Kconfig 配置。

build/zephyr/include/generated/devicetree_generated.h
 设备树生成的 C 宏。

Zephyr 和 Zephyr SDK 别混在一起

1
2


Zephyr： 会被编译进目标设备的 RTOS、驱动和板级支持源码。
Zephyr SDK： 在开发主机上执行编译、汇编、链接和二进制转换的工具链。

它们之间的关系可以简单理解为：

1
2
3
4
5
6
7
8


应用源码 + Zephyr 源码
 |
 | Zephyr SDK 提供交叉编译器、链接器等工具
 v
zephyr.elf / zephyr.bin
 |
 v
烧录到目标开发板并运行

所以日常开发主要修改应用源码、prj.conf 和设备树；SDK 通常只在安装、升级或排查工具链问题时才需要关注。

`zephyr/` 目录该从哪儿看

1
2
3
4
5
6
7


kernel/ 线程、调度、定时器、同步机制
drivers/ GPIO、UART、I2C、SPI 等驱动框架
boards/ 开发板定义
soc/ 芯片和 SoC 支持
dts/ 通用设备树定义与 bindings
include/zephyr/ 应用可包含的 API 头文件
cmake/、scripts/ 构建和代码生成规则

第一次打开 zephyr/ 时很容易被目录数量劝退。不建议马上扎进 kernel/：先从自己的 main.c 出发，找到它使用的 led0，再看它在最终设备树里落到了哪个 GPIO。等这条“代码如何落到硬件上”的路走通，再读内核时，看到的就不再是一堆孤立文件。

Zephyr 能支持哪些硬件

Zephyr 不是给任意 MCU 都能直接编译运行的通用库。把一个 STM32 的应用拿去给一颗新的 Cortex-M 芯片编译，并不因为两者都是 Cortex-M 就会成功。要支持一颗芯片，架构、SoC、开发板定义、设备树 binding、驱动和工具链必须一起就位：

1
2
3
4
5
6
7
8
9


应用代码
 |
Zephyr 通用 API
 |
驱动 + 设备树 binding
 |
SoC 支持 + 启动代码 + 中断/时钟/内存配置
 |
具体 MCU 硬件

这有点像两辆车都使用同一款发动机，并不代表仪表、线束和控制器可以直接互换。判断某个 MCU 是否受支持，不能只看它是不是 Cortex-M；外设、时钟、中断控制器、内存布局、启动方式和所需驱动是否完成适配，同样关键。

移植一颗新 MCU 为什么费工夫

移植不只是让 main() 跑起来，通常还要补齐下面这些环节：

1
2
3
4
5
6


CPU 架构层 异常入口、上下文切换、中断模型
启动与内存 启动代码、向量表、链接脚本、Flash/RAM 布局
SoC 基础设施 时钟、复位、中断控制器、系统定时器
硬件描述 DTS、pinmux/pinctrl、设备树 bindings
外设驱动 GPIO、UART、SPI、I2C、DMA 等驱动及其 Kconfig
构建与调试 交叉工具链、烧录、调试器配置

同一 CPU 架构的异常和上下文切换部分可能可以复用，但真正花时间的通常是 SoC 基础设施、设备树和外设驱动。厂商 HAL 也不能自动解决问题：它只是提供了操作硬件的底层能力，还需要接入 Zephyr 的驱动模型、Kconfig 和设备树体系，应用才能通过统一 API 使用它。

Zephyr 怎样把 API 接到硬件上

Zephyr 希望应用表达“我要控制这块板定义的 LED”，而不是直接写寄存器地址或厂商专属的 GPIO 端口。比如：

1

gpio_pin_toggle_dt(&led);

这句 API 最终能改变引脚电平，靠的是下面几层接力：

1
2
3
4
5


应用： 使用 GPIO API
设备树： 指定 LED 对应哪个 GPIO 控制器和引脚
GPIO 驱动： 将 API 调用转换为该控制器的操作
SoC/厂商 HAL： 访问具体外设寄存器
硬件： 改变引脚电平

其中三件事尤其重要。统一 API 是应用看到的操作面板，例如 GPIO、UART、I2C、SPI API；设备树像硬件清单，描述“板上有什么、连在哪里”；Kconfig 像装配选项，决定哪些功能和驱动会被编译进固件。

抽象并不意味着硬件差异消失。目标板已经有相应 DTS 描述和驱动时，同一份应用代码才可能少改甚至不改地迁移；DMA、低功耗、特殊时钟和厂商私有外设功能仍然需要结合具体 SoC 的限制来处理。

与 FreeRTOS 的应用开发模型对比

Zephyr 和 FreeRTOS 都能做实时嵌入式应用，区别主要不在“有没有线程和队列”，而在于平台覆盖的范围。前者更像一套带标准接口和装配规则的平台，后者的 Kernel 则专注把实时内核做好：

1
2
3
4
5
6


FreeRTOS Kernel
 重点提供任务调度、队列、信号量、软件定时器等内核能力。

Zephyr
 除了内核，还把驱动模型、设备树、Kconfig、板级支持和构建流程
 作为同一平台的一部分。

这并不代表 FreeRTOS 不能用驱动或厂商库。实际项目里，它常和厂商的启动代码、HAL、手写或厂商提供的外设驱动一起使用，只是这些组件不由 FreeRTOS Kernel 统一定义和管理。若项目只固定在一块板上，这种方式完全合理；当要支持多块板、维护多种芯片，或希望复用驱动和配置时，Zephyr 试图用一套接口、配置和硬件描述把这些部分串起来。

问题	FreeRTOS 项目中常见做法	Zephyr 项目中常见做法
创建任务/线程	`xTaskCreate()`	`K_THREAD_DEFINE()` 或 `k_thread_create()`
延时	`vTaskDelay()`	`k_sleep()` 或 `k_msleep()`
队列与同步	Queue、Semaphore、Event Group	`k_msgq`、`k_sem`、`k_event` 等对象
外设选择	厂商 HAL、手写寄存器配置或项目代码	通用驱动 API + DTS + Kconfig
引脚和外设实例	通常在 BSP、初始化代码或应用中配置	主要由设备树描述
编译开关	`FreeRTOSConfig.h` 加上工程配置	Kconfig，例如 `prj.conf`
换一块板	常需要调整 BSP、时钟、引脚和驱动初始化	若目标板已被支持，通常通过板选择和 DTS/overlay 调整

API 名称不能机械地一一替换，两者的对象模型、内存管理方式和配置选项并不完全相同。学习入口也不同：FreeRTOS 往往从任务和调度开始；Zephyr 更适合先弄清应用如何经过配置、设备树和驱动连接到硬件，再进入内核。

工具链搭建完成

Mon, 18 May 2026 00:00:00 +0000

工具链搭建完成

这段时间主要在折腾自己的嵌入式工具链。到 5.18 这一天，基本可以算是阶段性搭建完成了。

以前做嵌入式，很多流程其实是被厂商 IDE、图形配置工具和各种零散脚本拖着走。能跑是能跑，但每次换平台、换板子、换环境，都像是在重新和工具链打一架。现在我更想把这些东西统一到一套可复现、可调用、可交给 agent 执行的流程里：构建、烧录、检查、日志、错误定位，都尽量走明确的命令和工程结构。

这次最重要的成果，是测试成功了两条 ARM 架构相关的烧录链路。

一条是经典的 STM32F1。这基本算是我最熟悉的一类 MCU，也是很多嵌入式开发者绕不开的起点。能把它从传统开发方式里抽出来，用现代一点的工程结构完成构建和烧录，对我来说像是把老朋友重新接进新的工作流。

另一条是 TI MSPM0。相比 STM32F1，它更像是一个新的切入点：同样是 ARM 生态，但厂商工具、SDK 组织方式、烧录链路和调试习惯都不完全一样。把 MSPM0 也跑通，说明这套工具链不是只为某一个芯片临时拼出来的，而是有机会扩展成更通用的嵌入式开发底座。

从结果看，STM32F1 和 MSPM0 两边都能完成烧录验证，这件事让我很兴奋。工程流开始从“某个项目能跑”变成“某类流程能复用”。只要构建、烧录、调试这些基础动作足够稳定，后面再接入更多芯片、板卡和模板，就不用每次都从一片混乱里重新开始。

下一步：认识 Zephyr

工具链跑通之后，我开始对 Zephyr 这个 RTOS 产生兴趣。

以前接触 RTOS，更多是从裸机工程往上加：任务、调度、信号量、队列、驱动抽象，一层一层把东西堆起来。这样学很扎实，但也容易停留在“我会移植一个系统”或者“我会用一套接口”的阶段。

Zephyr 给我的感觉不太一样。它不像只是一个单纯的内核，更像一整套面向现代嵌入式工程的系统：设备树、配置系统、构建系统、驱动模型、板级支持、跨平台抽象，这些东西组合在一起，才接近我想理解的“工程化嵌入式”。

我想认识它，不只是为了会用一个新的 RTOS，而是想看看成熟的嵌入式系统到底怎么组织复杂性。为什么它能支持那么多板子，为什么驱动可以被抽象成统一模型，为什么配置和构建能被系统化管理，这些问题都值得拆开看。

工具链搭好只是第一步。烧录跑通代表入口打通了，有意思的事情还在后面：把底层硬件、构建系统、RTOS 思想和 agent 工作流接到一起，形成一套自己能长期维护、长期扩展的嵌入式工程体系。

这是我接下来想继续推进的方向。

RTOS on Blog

RTOS 正传（一）：FreeRTOS 的目录、移植层和配置文件

RTOS 正传（一）：FreeRTOS 的目录、移植层和配置文件

RTOS 到底适合什么场景

先把内核仓库拉下来

克隆下来为什么这么吓人

先分清自己站在哪一层

顶层目录先过一遍

根目录的 7 个 .c

include/：平时调用的 API 都在这儿

portable/：真正和芯片接上的地方

那些不会进固件的文件

F407 工程最后到底拿哪些

FreeRTOSConfig.h 配置分类

1. 时钟与时间

2. 调度器与任务

3. 任务附加能力

4. 任务通信与同步

5. 软件定时器

6. 内存、堆和任务栈

7. 中断与临界区

8. Hook 回调

9. 故障检测、断言与统计

10. C 库与 POSIX 兼容

11. 旧协程

12. MPU、TrustZone 与安全隔离

13. 多核 SMP

14. API 裁剪开关

总结一下

RTOS 前传：先把IDE的编译黑盒拆了

RTOS 前传：先把IDE的编译黑盒拆了

先把官方仓库拉下来

一个最小工程需要什么

arm-none-eabi 这一家子

1. 链接脚本：告诉链接器这个家有多大

2. startup_stm32f407xx.s：上电后第一棒

3. system_stm32f4xx.c：终于回到舒适区

SystemInit()

SystemCoreClock

HSE_VALUE

最后交给 CMake

Zephyr 入门（二）：设备树是什么，应用怎样使用它

Lesson 2: 设备树是什么，应用怎样使用它

设备树是在替应用保管硬件细节

一份设备树从哪里拼出来

先分清四个容易混淆的名字

例子：从 led0 找到真实引脚

例子：给项目接一个 I2C 传感器

DTS、DTSI、overlay 和 binding 各自负责什么

本课结论

Zephyr 入门（一）：认识 Zephyr 工程

Lesson 1: 认识 Zephyr 工程

先看整个工作区

West 到底负责什么

一份应用怎样变成固件

Zephyr 和 Zephyr SDK 别混在一起

zephyr/ 目录该从哪儿看

Zephyr 能支持哪些硬件

移植一颗新 MCU 为什么费工夫

Zephyr 怎样把 API 接到硬件上

与 FreeRTOS 的应用开发模型对比

推荐的阅读顺序

工具链搭建完成

工具链搭建完成

下一步：认识 Zephyr

根目录的 7 个 `.c`

`include/`：平时调用的 API 都在这儿

`portable/`：真正和芯片接上的地方

`FreeRTOSConfig.h` 配置分类

`arm-none-eabi` 这一家子

2. `startup_stm32f407xx.s`：上电后第一棒

3. `system_stm32f4xx.c`：终于回到舒适区

`SystemInit()`

`SystemCoreClock`

`HSE_VALUE`

例子：从 `led0` 找到真实引脚

`zephyr/` 目录该从哪儿看