Zephyr on Blog

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 工作流接到一起，形成一套自己能长期维护、长期扩展的嵌入式工程体系。

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

Zephyr on Blog

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

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

`zephyr/` 目录该从哪儿看