2. 设备树语法入门：节点、属性、标签、包含与宏定义

设备树（Device Tree，DT）是一种描述硬件拓扑与资源配置的树形数据结构，由一系列节点（node）、属性（property）、标签（label）、包含（include）与宏定义组成。掌握这些基本语法要素，是编写与调试板级设备树文件（.dts / .dtsi）的前提。

2.1 节点（Node）—— 设备树的骨架

节点是设备树的基本组成单元，每个节点代表一个硬件设备、总线、控制器或功能模块。节点通过路径（path）唯一标识，根节点为 /，子节点通过层级关系组织。

2.1.1 节点语法格式

/dts-v1/;

/ {
    model = "TI AM335x BeagleBone Black";
    compatible = "ti,am335x-bone-black", "ti,am335x-bone", "ti,am33xx";

    cpus {
        #address-cells = <1>;
        #size-cells = <0>;
        cpu@0 {
            compatible = "arm,cortex-a8";
            device_type = "cpu";
            reg = <0x00>;
        };
    };

    memory@80000000 {
        device_type = "memory";
        reg = <0x80000000 0x20000000>;  /* 512 MB */
    };
};

节点命名规则：节点名@单元地址，其中@单元地址可选，用于区分同一父节点下地址不同的同类设备。

2.1.2 节点层级关系 SVG 图

2.2 属性（Property）—— 描述硬件特征

属性是附着在节点上的键值对，用于描述硬件的兼容性、地址、中断、时钟、GPIO等特征。属性值可以是字符串、整数、字节数组、字符串列表或二进制数据。

2.2.1 属性类型与写法

2.2.2 标准属性速查表

2.3 标签（Label）—— 节点引用与复用

标签是设备树中用于引用节点的标识符，语法为 标签名: 节点名 { ... };。标签允许在设备树的其他位置通过 &标签名 引用该节点，实现节点属性的追加或覆盖。

2.3.1 标签定义与引用

// 定义标签
uart0: serial@44e09000 {
    compatible = "ti,am335x-uart";
    reg = <0x44e09000 0x2000>;
    interrupts = <72>;
    status = "disabled";
};

// 在其他文件中引用标签，追加属性
&uart0 {
    pinctrl-names = "default";
    pinctrl-0 = <&uart0_pins>;
    status = "okay";
};

2.3.2 标签的作用域与最佳实践

2.4 包含（Include）—— 模块化与复用

设备树使用 #include 预处理指令引入其他文件，实现硬件描述的模块化。通常 SoC 厂商提供 .dtsi（设备树包含文件），板级 .dts 文件通过 #include 引入 SoC 定义，再覆盖或追加板级特有属性。

2.4.1 包含文件层级结构

// am335x-boneblack.dts
#include "am33xx.dtsi"          // SoC 级定义
#include "am335x-bone-common.dtsi"  // 板级公共定义

/ {
    model = "TI AM335x BeagleBone Black";
    compatible = "ti,am335x-bone-black", "ti,am335x-bone", "ti,am33xx";

    &uart0 {
        status = "okay";
    };
};

2.4.2 包含文件组织原则

2.5 宏定义 —— 增强可读性与可维护性

设备树支持 C 预处理器宏定义，通过 #define 定义常量，在属性值中直接使用。宏定义通常放在 .h 头文件中，配合 #include 引入，使设备树更易读、易维护。

2.5.1 宏定义示例

// dt-bindings/gpio/gpio.h
#define GPIO_ACTIVE_HIGH   0
#define GPIO_ACTIVE_LOW    1

// dt-bindings/interrupt-controller/irq.h
#define IRQ_TYPE_EDGE_RISING     1
#define IRQ_TYPE_EDGE_FALLING    2
#define IRQ_TYPE_LEVEL_HIGH      4
#define IRQ_TYPE_LEVEL_LOW       8

// 在设备树中使用宏
#include <dt-bindings/gpio/gpio.h>
#include <dt-bindings/interrupt-controller/irq.h>

&gpio0 {
    led-red {
        gpios = <&gpio2 4 GPIO_ACTIVE_LOW>;
        interrupts = <IRQ_TYPE_EDGE_RISING>;
    };
};

2.5.2 宏定义 vs 直接数值

2.6 综合语法示例：完整节点结构

以下是一个综合了节点、属性、标签、包含与宏定义的完整设备树片段：

// am335x-boneblack.dts
/dts-v1/;

#include "am33xx.dtsi"
#include "am335x-bone-common.dtsi"
#include <dt-bindings/gpio/gpio.h>
#include <dt-bindings/interrupt-controller/irq.h>

/ {
    model = "TI AM335x BeagleBone Black";
    compatible = "ti,am335x-bone-black", "ti,am335x-bone", "ti,am33xx";

    chosen {
        stdout-path = &uart0;
    };

    leds {
        pinctrl-names = "default";
        pinctrl-0 = <&user_led_pins>;

        led-red {
            label = "beaglebone:red:usr0";
            gpios = <&gpio1 21 GPIO_ACTIVE_HIGH>;
            linux,default-trigger = "heartbeat";
        };

        led-green {
            label = "beaglebone:green:usr1";
            gpios = <&gpio1 22 GPIO_ACTIVE_HIGH>;
            linux,default-trigger = "mmc0";
        };
    };
};

&uart0 {
    status = "okay";
    pinctrl-names = "default";
    pinctrl-0 = <&uart0_pins>;
};

&i2c0 {
    status = "okay";
    clock-frequency = <400000>;

    eeprom@50 {
        compatible = "atmel,24c32";
        reg = <0x50>;
        pagesize = <32>;
    };
};

2.7 语法要素关系 SVG 图

2.8 本章小结

• 节点是设备树的基本单元，通过层级关系组织硬件拓扑。
• 属性以键值对形式描述硬件特征，compatible 和 reg 是最核心的属性。
• 标签提供节点引用机制，支持跨文件属性覆盖与追加。
• 包含实现设备树模块化，SoC 定义与板级定制分离。
• 宏定义提升代码可读性与可维护性，是设备树工程化的关键手段。