【产出】 > 看懂一份设备树源文件:分清 dts、dtsi、dtb,理解节点、属性以及 compatible、reg、status、phandle 这几个最常用的属性;会用 dtc 编译和反编译设备树,并掌握用 overlay 在不改原始文件的前提下修改硬件描述的方法。
【版本】 > 按 Devicetree 规范(devicetree.org)、Linux 内核文档的设备树部分和 dtc 官方手册编写。示例适用于 ARM / ARM64 / RISC-V 等使用设备树的平台,主机为 Ubuntu。
一、设备树解决什么问题
x86 电脑可以通过 ACPI、PCI 枚举自动发现硬件。ARM 开发板上的串口、I2C 控制器、GPIO 控制器大多直接挂在 SoC 内部总线上,CPU 没法"问"出来:寄存器在哪个地址、用哪个中断号、外部接了什么芯片,都得有人告诉内核。
过去这些信息直接写在内核的板级 C 文件里,每块板子一份。设备树把它们改成一份独立于内核代码的数据文件:内核文档对它的定义是"描述硬件的数据结构和语言"。同一个内核镜像,换一份设备树就能在另一块板子上启动。
二、dts、dtsi、dtb、dtbo
| 文件 | 含义 | 谁来用 |
|---|---|---|
.dts | 设备树源文件,描述一块具体的板子 | 人编写,dtc 编译 |
.dtsi | 被包含的公共部分,通常描述一颗 SoC | 被 .dts 包含 |
.dtb | 编译后的二进制(Flattened Device Tree,FDT) | Bootloader 加载到内存,交给内核 |
.dtso / .dtbo | overlay 的源文件和二进制 | 叠加到某个 dtb 上 |
典型的分层:芯片厂商写 soc.dtsi,描述芯片内部所有外设,大多默认关闭;板子的 board.dts 包含它,打开板上实际用到的外设,并补充外接器件。
三、节点和属性
/dts-v1/;
/ {
model = "Example Board";
compatible = "acme,example-board", "acme,soc100";
#address-cells = <1>;
#size-cells = <1>;
chosen {
bootargs = "console=ttyS0,115200";
};
memory@80000000 {
device_type = "memory";
reg = <0x80000000 0x20000000>; /* 起始地址 512 MB */
};
soc {
compatible = "simple-bus";
#address-cells = <1>;
#size-cells = <1>;
ranges;
uart0: serial@10000000 {
compatible = "acme,soc100-uart", "ns16550a";
reg = <0x10000000 0x100>;
status = "okay";
};
};
};
基本语法:
- 整棵树从根节点
/开始,节点用名字 { ... };嵌套。 - 规范规定节点名格式为
node-name@unit-address。node-name描述设备类别(如serial、i2c、gpio),@后面的单元地址必须和reg的第一个地址一致。没有reg的节点不写@。 - 属性是
名字 = 值;。值可以是字符串"..."、字符串列表"a", "b"、尖括号里的 32 位数<0x10 0x20>,或者不带值(布尔属性,存在即为真)。 uart0:是标签,供其他地方用&uart0引用。- 路径写法如
/soc/serial@10000000。
chosen 节点不代表硬件,而是固件传给内核的启动参数,例如 bootargs。
四、compatible:驱动靠它匹配
compatible 是一个字符串列表,从最具体到最通用排列。规范推荐格式为 "厂商,型号",只用小写字母、数字和短横线。
compatible = "acme,soc100-uart", "ns16550a";
内核先找 acme,soc100-uart 的驱动,找不到再用通用的 ns16550a 驱动。根节点的 compatible 描述整块板子,同样按"板子 → SoC → SoC 系列"排列。
内核文档要求每个 compatible 字符串都要在内核源码的 Documentation/devicetree/bindings 下有绑定文档。写设备树时,属性怎么写以对应的 binding 文档为准,不要凭感觉。
五、reg 与 #address-cells / #size-cells
reg 是若干组 <地址 长度>,表示设备资源在父总线地址空间里的位置。每组占几个 32 位数,由父节点的两个属性决定:
| 父节点属性 | 含义 | 规范默认值 |
|---|---|---|
#address-cells | 子节点 reg 中地址占几个 cell | 2 |
#size-cells | 子节点 reg 中长度占几个 cell | 1 |
规范强调这两个属性不从祖先继承,有子节点的节点应显式写出。几个常见场景:
/* 32 位地址总线:地址 1 个 cell,长度 1 个 cell */
reg = <0x10000000 0x100>;
/* 64 位平台常见:地址 2 个 cell,长度 2 个 cell */
reg = <0x0 0x10000000 0x0 0x100>;
/* I2C 总线:#address-cells = <1>; #size-cells = <0>; 只有从机地址 */
eeprom@50 {
compatible = "atmel,24c02";
reg = <0x50>;
};
#size-cells 为 0 时,子节点 reg 里就没有长度字段,I2C、SPI 设备都是这样。
六、status:开关一个设备
| 值 | 规范含义 |
|---|---|
"okay" | 设备可用。不写 status 等同于 okay |
"disabled" | 当前不可用,但以后可能可用(例如未插入、未上电) |
"reserved" | 设备能工作但不该使用,通常由固件等其他软件控制 |
"fail" / "fail-sss" | 检测到严重错误,sss 为具体错误说明 |
Linux 不会为 disabled 的节点创建设备。SoC 的 dtsi 一般把外设都写成 disabled,板级 dts 再按需打开:
#include "soc100.dtsi"
&i2c1 {
status = "okay";
clock-frequency = <400000>;
};
&i2c1 { ... }; 的意思是"找到标签为 i2c1 的节点,往里追加或覆盖属性",不需要重写整个节点。
七、phandle:节点之间互相引用
设备之间常有树结构以外的关系,比如"这个设备的中断接到那个中断控制器"。规范用 phandle 表达:它是一个在整棵树里唯一的 32 位编号,其他节点通过这个编号引用它。
源文件里一般不直接写数字,而是写标签引用,dtc 编译时自动分配 phandle 并替换:
gpio0: gpio@10010000 {
compatible = "acme,soc100-gpio";
reg = <0x10010000 0x100>;
gpio-controller;
#gpio-cells = <2>;
};
leds {
compatible = "gpio-leds";
led-0 {
gpios = <&gpio0 17 0>; /* 控制器、引脚号、标志 */
};
};
<&gpio0 17 0> 中,&gpio0 变成 gpio0 节点的 phandle,后面跟几个参数由被引用节点的 #gpio-cells 决定。中断(interrupt-parent、#interrupt-cells)、时钟(#clock-cells)都是同样的模式。
八、用 dtc 编译和反编译
sudo apt install device-tree-compiler # 提供 dtc、fdtoverlay、fdtdump 等
dtc 的基本用法是 dtc [选项] 输入文件,用 -I 指定输入格式、-O 指定输出格式、-o 指定输出文件:
# 编译
dtc -I dts -O dtb -o board.dtb board.dts
# 反编译:把二进制还原成可读源码
dtc -I dtb -O dts -o board_dump.dts board.dtb
# 查看正在运行的系统实际使用的设备树
dtc -I fs -O dts -o running.dts /proc/device-tree
| 格式 | 说明 |
|---|---|
dts | 源码 |
dtb | 二进制 |
fs | 目录形式,节点是目录、属性是文件,即 /proc/device-tree |
【提示】 > 从
/proc/device-tree反编译出的结果,是 Bootloader 修改之后、内核真正看到的那份树。排查"改了 dts 却不生效"时,先看这份,确认板子到底加载的是哪个 dtb。
【注意】 > 内核源码里的 dts 使用 C 预处理器的
#include和宏(如GPIO_ACTIVE_LOW),直接交给 dtc 会报错。内核里应使用make dtbs编译;单独编译时要先用cpp预处理。反编译得到的 dts 里标签名丢失,phandle 变成数字,只适合查看,不适合当源码维护。
九、overlay:不改原文件修改硬件描述
扩展板、可选模块各不相同,为每种组合维护一份完整 dts 很麻烦。overlay 是一个"补丁"式的小设备树,在启动时或运行时叠加到基础 dtb 上。
/* eeprom-overlay.dtso */
/dts-v1/;
/plugin/;
&i2c1 {
status = "okay";
eeprom@50 {
compatible = "atmel,24c02";
reg = <0x50>;
};
};
/plugin/; 表明这是 overlay。&i2c1 是基础树里的标签,overlay 编译时并不知道它在哪,要等叠加时再解析。因此:
- 基础树编译时要加
-@。dtc 手册说明,-@会在根节点生成__symbols__节点,记录每个标签对应的路径。没有它,按标签引用的 overlay 无法叠加。 - 也可以用路径写法
&{/soc/i2c@10020000} { ... };,这样不依赖标签。内核文档推荐标签写法,因为只要基础树有同名标签就能用,与节点实际位置无关。
dtc -@ -I dts -O dtb -o base.dtb base.dts
dtc -@ -I dts -O dtb -o eeprom-overlay.dtbo eeprom-overlay.dtso
# 离线合并,检查结果
fdtoverlay -i base.dtb -o merged.dtb eeprom-overlay.dtbo
dtc -I dtb -O dts merged.dtb | less
overlay 实际生效有三种常见途径:
| 途径 | 说明 |
|---|---|
| 离线合并 | 用 fdtoverlay 生成新 dtb,直接替换 |
| Bootloader 叠加 | U-Boot 用 fdt addr、fdt resize、fdt apply 在启动前叠加 |
| 发行版机制 | 例如树莓派在 config.txt 里用 dtoverlay= 指定 |
【注意】 > 老教程常见
fragment@0 { target = <&i2c1>; __overlay__ { ... }; };写法,这是 overlay 编译后的底层结构。新版 dtc 支持上面的&label { }简写,内核文档的示例也只用简写。两种写法效果相同,新写的 overlay 建议用简写。
参考资料
- Devicetree 规范(基础概念与标准属性):https://devicetree-specification.readthedocs.io/en/latest/chapter2-devicetree-basics.html
- Devicetree 官方站点:https://www.devicetree.org/
- Linux 内核设备树使用模型:https://docs.kernel.org/devicetree/usage-model.html
- Linux 内核设备树 overlay 说明:https://docs.kernel.org/devicetree/overlay-notes.html
- dtc 官方手册:https://github.com/dgibson/dtc/blob/main/Documentation/manual.txt
- U-Boot 设备树 overlay:https://docs.u-boot.org/en/latest/usage/fdt_overlays.html
评价 (0)