1. 项目概述：从“硬编码”到“软描述”的进化
如果你在嵌入式Linux或者内核驱动开发领域摸爬滚打过几年，一定经历过或者听说过那个“蛮荒时代”：为了支持一块新的开发板，我们需要在内核源码的arch/arm/mach-xxx/目录下，写满成百上千行的C代码，用来描述这块板子上有什么CPU、内存多大、各个外设挂在哪个总线上、中断号是多少、时钟频率几何。每换一块板子，哪怕只是改个LED灯的GPIO引脚，都得重新编译内核。这种将硬件信息“硬编码”进内核的方式，不仅让内核代码变得臃肿不堪，更让硬件和驱动之间的耦合度极高，移植和维护简直就是一场噩梦。
设备树（Device Tree）的出现，就是为了终结这场噩梦。它的核心思想非常优雅：用一个结构化的文本文件（.dts或.dtsi）来静态地描述系统的硬件拓扑结构，比如CPU、内存、总线、外设控制器以及挂在总线上的具体设备。这个文件在系统启动时，由Bootloader（如U-Boot）传递给Linux内核。内核在启动初期解析这个“硬件地图”，然后根据地图的描述，动态地创建和注册相应的平台设备。这样一来，同一个内核镜像，搭配不同的设备树文件，就能跑在不同的硬件平台上，真正实现了“一个内核，多种硬件”的梦想。
设备树文件看起来像一棵倒置的树，根节点/下挂着各种总线节点（如soc），总线节点下又挂着具体的设备节点（如uart0,i2c0）。而描述每个节点“是什么”、“在哪里”、“怎么用”的关键，就在于节点内部的属性。属性是键值对，是设备树的灵魂。今天，我们不谈那些由芯片厂商或开发者自定义的属性，而是聚焦于那些被内核广泛认可和使用的标准属性。理解这些标准属性，是读懂和编写设备树的基石。无论你用的是瑞芯微的RK3568、全志的T系列，还是赛灵思的Zynq-7000，这些标准属性都是相通的。
2. 设备树标准属性深度解析
设备树规范定义了一系列标准属性，它们具有特定的含义和格式，内核中的相应驱动会按照约定来解析它们。掌握这些属性，就等于拿到了打开设备树大门的钥匙。
2.1 设备标识类属性：告诉内核“你是谁”
这类属性主要用于设备匹配，是驱动绑定设备的关键依据。
2.1.1compatible：最重要的“身份证”
compatible属性是设备节点中最重要的属性，没有之一。它定义了设备的兼容性列表，内核通过它来寻找并绑定最合适的设备驱动。
它的值是一个字符串列表（string-list）。例如：
compatible = “fsl,imx6ul-uart”, “fsl,imx6q-uart”, “fsl,imx21-uart”;当内核开始初始化这个UART设备节点时，它会从compatible列表的第一个字符串“fsl,imx6ul-uart”开始，在已注册的驱动中查找of_device_id表里是否有与之匹配的条目。如果找不到，就尝试匹配第二个字符串“fsl,imx6q-uart”，依此类推。这种设计提供了良好的向后兼容性，新的驱动可以声明兼容旧的设备标识。
实操心得：
- 格式惯例：通常采用“制造商,型号”的格式，如
“ti,omap3-gpio”。这有助于避免命名冲突。 - 排序原则：把最具体、最匹配的兼容ID放在最前面，把更通用、用于“兜底”的兼容ID放在后面。这能确保优先使用最合适的驱动。
- 查阅依据：具体该写什么
compatible字符串，必须参考芯片厂商提供的设备树绑定（Device Tree Binding）文档，或者直接参考内核源码中类似平台的dts文件。切忌自己随意编造。
2.1.2model与compatible
model属性是一个描述性字符串，用于说明设备的型号。例如model = “TI AM335x BeagleBone Black”;。它更多是给人看的，内核在设备匹配时基本不依赖它。它的作用在于在/proc/device-tree中提供一个可读的设备模型信息。
与compatible的区别：compatible是给机器（内核）看的，用于精确匹配驱动；model是给人看的，用于标识产品型号。一个设备节点可以没有model，但绝对不能没有compatible（除非是那些没有对应驱动、仅用于描述硬件连接的节点，比如一个简单的GPIO LED）。
2.2 资源定位类属性：告诉内核“你在哪”
这类属性描述设备所占用的系统资源，如内存地址、中断号等。
2.2.1reg：地址资源的“门牌号”
reg属性用于描述设备在其父总线地址空间内的资源分配情况，最常见的就是内存映射I/O（MMIO）的地址范围。
它的值是一个或多个(address, length)对组成的列表。每个(address, length)对称为一个“资源”。address和length的单位不是固定的字节，而是由其父节点的#address-cells和#size-cells属性决定的。
举个例子，对于一个典型的SoC内部外设：
soc { #address-cells = <1>; // 子reg地址用1个32位数表示 #size-cells = <1>; // 子reg长度用1个32位数表示 serial@4000a000 { compatible = “fsl,imx6ul-uart”; reg = <0x4000a000 0x400>; // 起始地址0x4000a000，长度0x400字节 }; };这里，serial设备的reg = <0x4000a000 0x400>;表示该UART控制器的寄存器区域从物理地址0x4000a000开始，长度为0x400（1KB）。内核驱动会通过platform_get_resource()等API获取这个区域，并将其映射到内核虚拟地址空间，从而进行读写操作。
注意事项：
#address-cells和#size-cells：这是父节点的属性，用于规定其子节点reg属性的格式。必须正确设置，否则内核解析会出错。对于简单的内存映射设备，通常设为<1>（32位系统）或<2>（64位系统）。- 地址空间：
reg描述的地址是其父总线定义的地址空间，不一定是CPU视角的物理地址。例如在有些带地址转换的总线上，这里的地址是总线本地地址。 - 多区域设备：有些设备有多个独立的寄存器区域，
reg属性可以包含多组地址长度对，如reg = <0x1000 0x100 0x2000 0x200>;。
2.2.2ranges：地址空间的“翻译官”
当一个总线节点（子空间）的地址域与其父节点（父空间）的地址域不同时，就需要ranges属性来建立地址映射关系。
ranges的值是一个转换表，每一项是一个三元组：(子总线地址, 父总线地址, 长度)。例如：
external-bus { #address-cells = <2>; #size-cells = <1>; ranges = <0 0 0x10100000 0x10000 // 子地址0x0映射到父地址0x10100000，长64KB 1 0 0x10160000 0x10000 2 0 0x30000000 0x1000000>; ethernet@0,0 { compatible = “smc,smc91c111”; reg = <0 0 0x1000>; // 这里的地址0 0是在external-bus地址空间内 }; };在这个例子中，ethernet节点的reg地址<0 0 0x1000>是相对于external-bus这个子地址空间的。通过ranges属性的第一条映射，内核知道这个子空间的0地址对应父空间（可能是系统内存空间）的0x10100000地址。这样，驱动访问设备寄存器时，才能找到正确的物理地址。
常见问题：对于SoC内部集成的外设，其寄存器通常直接映射到系统内存空间，此时父节点（如soc）的地址空间和系统内存空间一致，所以一般不需要ranges属性。ranges更多用于描述外部扩展总线，如FPGA桥接、PCIe等。
2.3 中断与时钟类属性：告诉内核“你怎么动”
现代外设离不开中断和时钟，设备树也需要描述这些资源。
2.3.1interrupts：设备的“呼叫铃”
interrupts属性描述设备产生的中断号。和reg类似，其格式也依赖于父节点定义的#interrupt-cells。
一个典型的例子：
intc: interrupt-controller@40000000 { compatible = “arm,cortex-a7-gic”; #interrupt-cells = <3>; // 对于GIC，需要3个cell interrupt-controller; }; gpio_keys { compatible = “gpio-keys”; interrupt-parent = <&intc>; // 指定中断控制器 interrupts = <0 66 IRQ_TYPE_EDGE_FALLING>; // SPI 66号中断，下降沿触发 };这里，interrupt-parent指向了中断控制器节点intc。interrupts = <0 66 IRQ_TYPE_EDGE_FALLING>中的三个数字由intc节点的#interrupt-cells = <3>决定。对于ARM GIC，这三个cell通常表示：中断类型（0为SPI，1为PPI）、中断号、触发标志（边沿/电平，高/低）。
关键点：
interrupt-controller属性：标记一个节点为中断控制器。#interrupt-cells属性：中断控制器节点特有，定义其子节点interrupts属性的cell数量。interrupt-parent属性：设备节点可以通过此属性指定中断控制器，否则默认继承父节点的中断父节点。- 中断号：这里的编号是硬件中断号（HWIRQ），是中断控制器视角的编号，不是Linux内核分配的虚拟中断号（IRQ number）。内核驱动会通过
platform_get_irq()等函数获取最终的IRQ number。
2.3.2clocks与clock-names：设备的“心跳”
clocks属性用于指定设备所使用的时钟源。通常与clock-names配合使用，为每个时钟提供一个名字，方便驱动通过名字获取特定的时钟。
uart0: serial@4000a000 { compatible = “fsl,imx6ul-uart”; reg = <0x4000a000 0x400>; interrupts = <0 72 IRQ_TYPE_LEVEL_HIGH>; clocks = <&clks IMX6UL_CLK_UART0_IPG>, <&clks IMX6UL_CLK_UART0_SERIAL>; clock-names = “ipg”, “per”; };驱动中可以通过devm_clk_get(&pdev->dev, “ipg”)来获取名为“ipg”的时钟句柄，然后进行使能、设置频率等操作。
注意事项：时钟的消费者（如uart0）通过clocks属性引用时钟的提供者（如clks节点）。提供者节点必须具有#clock-cells属性，并且通常被标记为clock-controller。
2.4 引脚控制与GPIO类属性：告诉内核“你连到哪”
对于需要连接GPIO、配置引脚复用（Pinmux）的设备，设备树提供了标准的描述方式。
2.4.1pinctrl-*：引脚的“多功能开关”
在复杂的SoC中，一个物理引脚往往可以复用为多种功能（如GPIO、UART的TX、I2C的SCL）。pinctrl子系统就是用来管理这个的。设备树中通过pinctrl-0,pinctrl-1等属性和pinctrl-names来指定设备在不同状态（如默认状态、睡眠状态）下所需的引脚配置。
&iomuxc { pinctrl_uart0: uart0grp { fsl,pins = < MX6UL_PAD_UART0_TX_DATA__UART0_DCE_TX 0x000010B0 MX6UL_PAD_UART0_RX_DATA__UART0_DCE_RX 0x000010B0 >; }; }; &uart0 { pinctrl-names = “default”; pinctrl-0 = <&pinctrl_uart0>; status = “okay”; };这里，pinctrl_0引用了在iomuxc节点下定义的一个引脚配置组pinctrl_uart0。驱动在初始化uart0时，pinctrl子系统会自动将对应的引脚配置为UART功能。
实操心得：引脚配置的具体数值（如0x000010B0）是一组包含电气特性（如上拉、下拉、驱动强度、速率）的宏，必须严格参考芯片手册和厂商提供的头文件（如imx6ul-pinfunc.h）来编写，一个数字写错就可能导致通信失败或损坏硬件。
2.4.2gpios：通用的“数字接口”
对于简单的GPIO设备，如LED、按键，可以直接使用gpios属性。
led0 { compatible = “gpio-leds”; gpios = <&gpio1 5 GPIO_ACTIVE_HIGH>; // 使用gpio1组的第5号引脚，高电平有效 default-state = “off”; };gpios属性引用了一个GPIO控制器节点（&gpio1），并指定了引脚偏移（5）和标志（GPIO_ACTIVE_HIGH）。驱动（这里是gpio-leds）会通过GPIO子系统申请并控制这个引脚。
扩展属性：像gpio-controller、#gpio-cells是GPIO控制器节点的标准属性，用于声明自身是控制器并定义gpios属性的cell格式。
3. 设备树属性在驱动中的使用实操
理解了属性的含义，我们来看看内核驱动是如何获取并使用这些信息的。这是打通设备树和驱动代码的关键。
3.1 驱动如何匹配设备树节点
驱动通过of_device_id结构体数组来声明自己可以兼容哪些设备树节点。
static const struct of_device_id my_uart_dt_ids[] = { { .compatible = “fsl,imx6ul-uart” }, { .compatible = “fsl,imx6q-uart” }, { /* sentinel */ } }; MODULE_DEVICE_TABLE(of, my_uart_dt_ids); static struct platform_driver my_uart_driver = { .driver = { .name = “my_imx_uart”, .of_match_table = my_uart_dt_ids, // 这里关联匹配表 }, .probe = my_uart_probe, .remove = my_uart_remove, };当内核解析设备树，发现一个节点的compatible属性与my_uart_dt_ids表中的某一项匹配时，就会调用该驱动的probe函数。
3.2 在Probe函数中解析资源
在驱动的probe函数中，我们可以使用一系列以of_或devm_开头的API来获取设备树中定义的资源。
static int my_uart_probe(struct platform_device *pdev) { struct device *dev = &pdev->dev; struct device_node *np = dev->of_node; // 获取设备对应的设备树节点指针 struct resource *mem_res; void __iomem *base; int irq; struct clk *clk_ipg; // 1. 获取内存资源 mem_res = platform_get_resource(pdev, IORESOURCE_MEM, 0); if (!mem_res) { dev_err(dev, “failed to get memory resource\n”); return -EINVAL; } // 将物理地址映射为内核可访问的虚拟地址 base = devm_ioremap_resource(dev, mem_res); if (IS_ERR(base)) return PTR_ERR(base); // 2. 获取中断号 irq = platform_get_irq(pdev, 0); if (irq < 0) { dev_err(dev, “failed to get IRQ\n”); return irq; } // 注册中断处理函数 ret = devm_request_irq(dev, irq, my_uart_isr, 0, dev_name(dev), priv); // 3. 获取时钟（通过名称） clk_ipg = devm_clk_get(dev, “ipg”); if (IS_ERR(clk_ipg)) { ret = PTR_ERR(clk_ipg); dev_err(dev, “failed to get ipg clock: %d\n”, ret); return ret; } ret = clk_prepare_enable(clk_ipg); // 4. 解析自定义属性（如果有） of_property_read_u32(np, “my-custom-baudrate”, &custom_baud); // ... 其他初始化操作 return 0; }platform_get_resource、platform_get_irq这些函数，其底层正是通过解析设备节点的reg、interrupts属性来获取资源的。devm_clk_get则通过clock-names来查找对应的时钟。
3.3 解析GPIO和Pinctrl
对于GPIO和Pinctrl，驱动通常不需要直接解析设备树属性，而是由相应的子系统框架自动处理。
- GPIO：像
gpio-leds这样的驱动，在probe函数中会调用gpiod_get()或gpiod_get_index()，这些函数内部会自动查找设备节点的gpios属性并进行解析和申请。 - Pinctrl：在
platform_driver的标准流程中，内核会在调用驱动的probe函数之前，自动根据设备节点的pinctrl-0等属性应用默认的引脚状态。驱动代码中通常不需要显式操作。
核心技巧：现代Linux驱动开发推崇“设备树描述，驱动获取”的模式。驱动应尽可能使用devm_（Managed Device Resource）系列API来申请资源，如devm_ioremap_resource、devm_clk_get、devm_request_irq。这些API能确保在驱动卸载或发生错误时自动释放资源，避免资源泄漏，极大地简化了错误处理逻辑。
4. 设备树调试与常见问题排查实录
设备树编写或修改后，如何验证其正确性？驱动加载失败时，如何定位是设备树的问题？以下是实战中积累的排查技巧。
4.1 系统启动阶段查看设备树
查看原始设备树Blob（DTB）： U-Boot传递设备树给内核时，有时会将DTB的加载地址打印出来。你可以通过U-Boot命令（如
md）查看该内存区域，或者使用fdtdump工具在主机上反编译DTB文件：fdtdump my-board.dtb | less。这能帮你确认编译出的DTB内容是否符合预期。查看内核解析后的设备树： Linux内核在
/proc/device-tree目录下，以目录和文件的形式提供了运行时设备树的视图。你可以直接cat某个属性文件来查看其值。# 查看根节点的compatible属性 cat /proc/device-tree/compatible # 查看某个节点下的所有属性 ls /proc/device-tree/soc/serial@4000a000/ # 查看reg属性（可能是二进制格式） hexdump -C /proc/device-tree/soc/serial@4000a000/reg这是最直接的调试手段，可以确认内核“看到”的设备树和你编写的
dts是否一致。
4.2 内核日志中的关键信息
内核启动时，关于设备树的解析和设备匹配信息会打印在日志中（dmesg）。关注以下几类信息：
- OF（Open Firmware）解析日志：内核可能打印
OF: fdt: …之类的信息，显示设备树的基本信息。 - 平台设备创建：搜索
of_platform相关的日志，可以看到内核从设备树创建了哪些平台设备。 - 设备与驱动匹配：这是最关键的信息。当驱动
probe成功时，通常会打印类似[ 1.234567] 2020000.serial: ttyS0 at MMIO 0x2020000 (irq = 38, base_baud = 5000000) is a 16550A的日志。如果没看到你的设备被初始化，或者看到了匹配失败的信息，就要重点排查。
一个典型的匹配失败日志：
[ 1.345678] my_uart: probe of 4000a000.serial failed with error -2错误码-2是-ENOENT，通常意味着驱动没有从设备树中成功获取到必需的资源（如内存区域、中断）。这时就需要检查reg、interrupts等属性是否正确，以及父节点的#address-cells等是否匹配。
4.3 常见问题与解决方案速查表
| 问题现象 | 可能原因 | 排查步骤与解决方案 |
|---|---|---|
| 驱动完全不被调用（无probe日志） | 1.compatible字符串不匹配。2. 驱动未编译进内核或模块未加载。 3. 设备节点状态为 disabled。 | 1. 检查/proc/device-tree/…/compatible，与驱动中的of_device_id表仔细比对，包括大小写和标点。2. 检查内核配置 .config，确认驱动已启用。检查lsmod确认模块已加载。3. 检查设备树节点是否有 status = “disabled”;，改为“okay”。 |
Probe函数返回-EINVAL或-ENODEV | 1. 资源获取失败（reg/interrupts解析错误）。2. 依赖的时钟、复位、pinctrl等资源获取失败。 | 1. 在驱动probe函数开始处添加dev_info(dev, “probing…\n”);，确认被调用。然后逐步调试资源获取函数（platform_get_resource等）的返回值。2. 检查 clocks、resets、pinctrl-*属性引用是否存在且正确。使用devm_系列API的错误信息通常很明确。 |
| 外设功能不正常（如UART无输出） | 1. 时钟未使能或频率错误。 2. 引脚复用（pinctrl）配置错误。 3. reg地址或长度错误，导致寄存器访问错乱。 | 1. 在驱动中检查时钟使能和获取频率的返回值。使用cat /sys/kernel/debug/clk/clk_summary查看时钟状态。2. 这是最常见的原因！反复核对 pinctrl配置中的引脚宏和电气属性值，参考官方开发板的配置。可以暂时在U-Boot中手动配置引脚复用，验证硬件是否正常。3. 对照芯片数据手册的内存映射表，一字不差地核对 reg属性。 |
| 设备树修改后不生效 | 1. 新的DTB文件未正确烧录或加载。 2. 内核缓存了旧的设备树。 | 1. 确认U-Boot加载的DTB文件路径和文件名正确。可以在U-Boot中用fdt addr和fdt print命令检查当前设备树。2. Linux内核在启动后不会重新读取DTB。必须重启系统。 |
4.4 高级调试工具：OF Debugfs
内核的Debugfs提供了更强大的设备树调试接口，需要内核配置CONFIG_OF_DEBUG。
# 挂载debugfs（如果尚未挂载） mount -t debugfs none /sys/kernel/debug # 查看设备树整体信息 cat /sys/kernel/debug/devicetree/base/compatible # 打开设备树解析的详细调试日志（动态生效） echo 1 > /sys/kernel/debug/of/dt_debug打开dt_debug后，内核会在解析设备树节点、属性时打印详细日志，对于追踪复杂的设备树问题非常有帮助。
踩坑实录：我曾经遇到一个I2C设备无法识别的问题，驱动匹配成功，probe也被调用，但读取设备ID总是失败。排查了很久，最后发现是设备树中pinctrl配置的I2C引脚电气属性里，驱动强度设置得太弱，导致信号质量差，在长走线上无法可靠通信。将驱动强度从默认值调高后问题立刻解决。这个教训是：设备树里每一个数字都有其物理意义，不能想当然地拷贝类似配置，必须结合硬件设计（如走线长度、负载）来调整电气参数。
5. 从标准属性到自定义属性：扩展设备树描述能力
标准属性覆盖了大部分通用硬件描述需求。但对于特定驱动或复杂外设，我们可能需要定义和使用自定义属性。
5.1 何时需要自定义属性？
当外设的配置无法用标准属性充分描述时，就需要自定义属性。例如：
- 一个LCD屏幕，除了电源GPIO，还需要配置初始化的指令序列（init code）。
- 一个以太网PHY芯片，需要指定特殊的LED行为模式。
- 一个音频Codec，需要提供额外的偏置电压配置。
5.2 定义与使用自定义属性
在设备树中，自定义属性可以任意添加，只要保证其名称不与标准属性冲突（通常建议加上厂商前缀）。在驱动中，使用of_property_read_*系列函数来读取它们。
设备树示例：
&i2c1 { status = “okay”; touchscreen@38 { compatible = “mycompany,tsc2007”; reg = <0x38>; interrupt-parent = <&gpio1>; interrupts = <5 IRQ_TYPE_EDGE_FALLING>; mycompany,touch-max-x = <800>; // 自定义属性：X方向最大值 mycompany,touch-max-y = <480>; // 自定义属性：Y方向最大值 mycompany,invert-y; // 自定义属性：布尔值，反转Y轴 }; };驱动代码示例：
static int tsc2007_probe(struct i2c_client *client) { struct device *dev = &client->dev; struct device_node *np = dev->of_node; u32 max_x, max_y; bool invert_y = false; // 读取数值属性 if (of_property_read_u32(np, “mycompany,touch-max-x”, &max_x)) max_x = 1024; // 提供默认值 if (of_property_read_u32(np, “mycompany,touch-max-y”, &max_y)) max_y = 1024; // 读取布尔属性（属性存在即为true） invert_y = of_property_read_bool(np, “mycompany,invert-y”); dev_info(dev, “Touchscreen config: max_x=%d, max_y=%d, invert_y=%d\n”, max_x, max_y, invert_y); // ... 其他初始化 }5.3 为自定义属性编写绑定文档
如果你定义的属性会被其他人使用，或者希望提交到上游内核，那么为其编写一份设备树绑定（Device Tree Binding）文档是至关重要的。这份文档通常以YAML格式（.yaml）存在，描述了节点的兼容性字符串、必需属性、可选属性、属性的约束条件等。
内核源码的Documentation/devicetree/bindings/目录下包含了所有官方认可的绑定文档。遵循这个规范，能让你自定义的属性更规范、更易于维护和共享。
最后一点体会：设备树不是魔法，它只是一种硬件描述语言。真正让硬件动起来的，是正确编写并加载的设备树文件，以及与之完美配合的内核驱动。调试设备树问题的过程，本质上是一个“确认信息流是否畅通”的过程：从DTS源文件，到编译后的DTB，到Bootloader加载，再到内核解析，最后到驱动获取资源。任何一个环节出错，硬件都无法正常工作。掌握标准属性，熟练运用调试工具，建立清晰的排查思路，是每一位嵌入式Linux开发者必须修炼的内功。当你能够从容地为一个新板子编写或移植设备树时，你会发现，硬件和软件之间的那堵墙，已经悄然消失。
