3. 设备树常用属性详解

设备树中的属性（property）是描述硬件设备特征、连接关系和资源需求的核心载体。每个节点通过一组键值对（key-value）向内核传递硬件信息。本章将逐一拆解嵌入式开发中最常用的 7 类属性，包括它们的语法、语义、典型取值和常见陷阱。

3.1 compatible —— 设备与驱动的匹配钥匙

compatible 是设备树中最重要的属性之一，它指定了设备与内核驱动之间的匹配名称。内核通过遍历设备树节点，将节点的 compatible 值与驱动注册时声明的 of_device_id 表进行比对，从而找到正确的驱动程序。

语法格式：

compatible = "manufacturer,model", "generic-model";

匹配规则：

• 内核优先使用列表中的第一个字符串进行精确匹配。
• 如果第一个字符串未匹配成功，则依次尝试后续字符串（回退机制）。
• 字符串格式通常为 "厂商名,器件型号"，确保全局唯一性。

temp_sensor: tmp117@48 {
    compatible = "ti,tmp117", "ti,tmp116";
    reg = <0x48>;
};

3.2 reg —— 设备地址空间与片选信息

reg 属性用于描述设备在总线上的地址空间或片选（chip select）信息。它由一个或多个地址/长度对组成，每个对称为一个“region”。对于内存映射设备，reg 指定了基地址和映射长度；对于 I²C/SPI 设备，则指定从设备地址。

语法格式：

reg = <address1 length1 address2 length2 ...>;

不同总线下的含义：

display_controller: display@1e00000 {
    compatible = "vendor,display";
    reg = <0x01e00000 0x100000    /* 控制寄存器块 */
           0x01f00000 0x200000>;  /* 帧缓冲块 */
};

3.3 interrupts —— 中断信号描述

interrupts 属性描述设备产生的中断信号，包括中断控制器、中断号和触发类型。它通常与 interrupt-parent 配合使用，后者指定设备所连接的中断控制器节点。

语法格式：

interrupt-parent = <&gic>;
interrupts = <0 89 4>;

中断描述符字段含义（以 GICv2 为例）：

interrupts = <0 33 4>, <0 34 4>;

3.4 status —— 设备启用状态控制

status 属性用于控制设备节点的启用或禁用状态。它允许在不修改硬件描述的情况下，通过设备树动态启用或禁用某个外设。这在多板型复用同一 .dtsi 文件时非常有用。

可选值：

// 在 SoC 级 .dtsi 中：
&uart2 {
    status = "disabled";
};

// 在板级 .dts 中：
&uart2 {
    status = "okay";
    pinctrl-0 = <&uart2_pins>;
};

3.5 clocks —— 时钟资源绑定

clocks 属性描述设备所需的时钟源，包括时钟控制器、时钟 ID 和时钟标志。它通常与 clock-names 配合使用，后者为每个时钟提供语义化名称，方便驱动通过名称获取时钟句柄。

语法格式：

clocks = <&clk_ctrl CLK_ID1>, <&clk_ctrl CLK_ID2>;
clock-names = "bus", "core";

时钟标志位（可选）：

struct clk *bus_clk, *core_clk;

bus_clk = devm_clk_get(dev, "bus");
core_clk = devm_clk_get(dev, "core");

clk_prepare_enable(bus_clk);
clk_prepare_enable(core_clk);

3.6 gpios —— GPIO 资源描述

gpios 属性用于描述设备使用的 GPIO 引脚，包括 GPIO 控制器、引脚编号和 GPIO 标志。与时钟类似，gpio-names 可以为每个 GPIO 提供语义化名称。

语法格式：

gpios = <&gpio1 15 GPIO_ACTIVE_HIGH>,
        <&gpio2 7  GPIO_ACTIVE_LOW>;
gpio-names = "reset", "irq";

GPIO 标志位：

keypad: keypad@0 {
    compatible = "vendor,keypad";
    gpios = <&gpio1 15 GPIO_ACTIVE_LOW>,  /* 复位引脚 */
            <&gpio2 7  GPIO_ACTIVE_HIGH>; /* 中断引脚 */
    gpio-names = "reset", "irq";
    interrupt-parent = <&gpio2>;
    interrupts = <7 IRQ_TYPE_EDGE_RISING>;
};

3.7 属性综合对比与选择指南

以下表格总结了 7 类核心属性的用途、数据类型和典型场景，方便在实际开发中快速查阅：

3.8 属性编写最佳实践

基于多年嵌入式开发经验，总结以下属性编写原则：

• 完整性原则： 每个设备节点至少应包含 compatible 和 reg（或 interrupts）属性，确保内核能够识别和访问设备。
• 层次化原则： 将 SoC 级通用描述放在 .dtsi 中，板级差异（如 status、pinctrl）放在 .dts 中覆盖。
• 命名规范原则： compatible 使用 "厂商,型号" 格式；clock-names 和 gpio-names 使用有意义的英文单词。
• 最小化原则： 只添加驱动实际需要的属性，避免冗余描述导致解析错误。
• 验证原则： 每次修改设备树后，使用 dtc -I dtb -O dts 反编译检查，并使用 dt-validate 工具进行 schema 校验。

spi@ff110000 {
    compatible = "vendor,spi-controller";
    reg = <0xff110000 0x1000>;
    interrupts = <0 56 4>;
    clocks = <&clk_ctrl SPI_CLK>;
    clock-names = "spi_clk";
    pinctrl-0 = <&spi_pins>;
    pinctrl-names = "default";
    status = "okay";

    adc@0 {
        compatible = "ti,ads1256";
        reg = <0>;  /* CS0 */
        spi-max-frequency = <10000000>;
        gpios = <&gpio3 12 GPIO_ACTIVE_LOW>;
        gpio-names = "drdy";
    };
};