2. DTS语法入门：节点(node)、属性(property)、标签(label)、包含文件(include)的语法规则

设备树源文件（.dts）是描述硬件拓扑与资源配置的领域特定语言。掌握其核心语法——节点、属性、标签与包含文件——是编写、阅读与调试设备树的基础。本章从这四个基本要素出发，结合实例与常见错误，建立清晰的语法认知。

2.1 节点（node）：硬件拓扑的骨架

节点是设备树的基本组成单元，每个节点代表一个硬件设备、总线、控制器或功能块。节点通过层级嵌套描述硬件之间的从属关系。

2.1.1 节点定义格式

node-name {
    property1 = <value>;
    property2 = "string";
    child-node {
        ...
    };
};

• 节点名称：由字母、数字、连字符、下划线组成，通常使用小写。例如 cpu、uart0、i2c-bus。
• 节点体：用花括号 { } 包裹，内部包含属性与子节点。
• 结束符：节点体后必须紧跟分号 ;。

2.1.2 根节点与特殊节点

2.1.3 节点路径与引用

每个节点在设备树中拥有唯一路径，从根节点开始以斜杠分隔。例如：

/soc/spi@ff110000/display@0

路径用于在 dts 文件内部或 dtsi 包含文件中定位节点，也用于 phandle 引用。

2.2 属性（property）：描述硬件特征

属性是键值对，附着在节点上，用于描述设备的寄存器地址、中断号、时钟频率、兼容性等特征。属性值支持多种数据类型。

2.2.1 属性值类型

2.2.2 标准属性速查

• compatible：驱动匹配的关键，格式为 "厂商,设备型号"，如 "fsl,imx6q-uart"。
• reg：描述地址空间，格式为 <地址 长度>，可重复出现表示多段地址。
• interrupts：描述中断号与触发类型，依赖 interrupt-parent 指定中断控制器。
• clocks：引用时钟源，通常配合 clock-names 使用。
• status：设备状态，常用值 "okay"、"disabled"、"reserved"。

2.3 标签（label）：节点的“别名”

标签为节点定义一个可引用的标识符，用于在 dts 文件内部或通过 &label 语法引用节点，实现节点内容的追加与覆盖。

2.3.1 标签定义

uart0: serial@ff110000 {
    compatible = "ns16550";
    reg = <0xff110000 0x1000>;
    interrupts = <0 33 4>;
};

上例中 uart0 即为标签，节点路径为 /soc/serial@ff110000，但通过标签可快速引用。

2.3.2 标签引用与节点追加

&uart0 {
    clock-frequency = <24000000>;
    status = "okay";
};

上述代码通过 &uart0 引用标签，向原节点追加 clock-frequency 属性和 status 属性。若原节点已存在同名属性，则新值覆盖旧值。

2.3.3 标签的典型用途

• 板级覆盖：在 dtsi 中定义通用节点并加标签，在板级 dts 中通过 &label 调整参数。
• 中断与时钟引用：使用 &label 作为 interrupt-parent 或 clocks 的值。
• 引脚复用配置：引用 pinctrl 节点中的标签，指定引脚功能。

2.4 包含文件（include）：模块化与复用

设备树支持通过 #include 预处理指令引入其他文件，实现硬件描述的分层与复用。包含文件通常使用 .dtsi 扩展名，表示设备树包含文件。

2.4.1 包含语法

#include "soc-common.dtsi"
#include "board-base.dtsi"
#include "pinmux.dtsi"

dtc 编译器在预处理阶段调用 C 预处理器（cpp）处理 #include，因此也支持 #define、#ifdef 等宏定义。

2.4.2 包含文件组织策略

2.4.3 包含文件中的节点覆盖

包含文件定义通用节点，最终 dts 文件通过标签引用覆盖或追加属性：

// soc-common.dtsi
uart0: serial@ff110000 {
    compatible = "ns16550";
    reg = <0xff110000 0x1000>;
    status = "disabled";
};

// board-foo.dts
#include "soc-common.dtsi"

&uart0 {
    clock-frequency = <24000000>;
    status = "okay";
};

编译后 uart0 节点包含 compatible、reg、clock-frequency 和 status = "okay"。

2.5 语法综合示例与SVG结构图

以下是一个完整的设备树片段，展示节点、属性、标签与包含文件的协同使用：

// main.dts
#include "soc.dtsi"
#include "board.dtsi"

/ {
    model = "Example Board v2";
    compatible = "example,board-v2";

    chosen {
        bootargs = "console=ttyS0,115200 root=/dev/mmcblk0p2";
        stdout-path = &uart0;
    };

    memory@80000000 {
        device_type = "memory";
        reg = <0x80000000 0x40000000>;  // 1GB RAM
    };
};

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

2.6 常见语法错误与排查

2.7 本章小结

• 节点是设备树的骨架，通过层级嵌套描述硬件拓扑；根节点 / 是所有节点的起点。
• 属性是节点的数据载体，支持整数、字符串、字节数组等多种类型；compatible 和 reg 是最核心的标准属性。
• 标签为节点提供编译期别名，通过 &label 实现跨文件属性追加与覆盖，是模块化设计的关键。
• 包含文件通过 #include 实现硬件描述的复用，.dtsi 文件按 SoC、板级、引脚复用分层组织。
• 掌握这四个要素的语法规则与常见错误模式，是后续调试与故障分析的基础。