2. DTS语法入门：节点(node)、属性(property)、标签(label)、包含(include)与宏定义

设备树源文件（.dts）是一种结构化的描述语言，用于向操作系统（尤其是Linux内核）传递硬件拓扑、内存布局、外设寄存器地址、中断号等静态信息。掌握DTS语法是编写和修改设备树覆盖（DTO）的基础。本章将系统讲解DTS的核心语法元素：节点、属性、标签、包含机制以及宏定义的使用。

2.1 节点（Node）

节点是设备树的基本组成单元，用于表示一个硬件设备、总线、控制器或功能块。每个节点都有一个名称，并可以包含子节点和属性。节点通过层级结构（树形结构）来描述硬件之间的从属关系。

2.1.1 节点定义语法

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

• 节点名称：通常为小写字母、数字和连字符的组合，如 cpu、i2c0、serial@ff000000。当节点有寄存器地址时，名称后常跟 @address 以区分同类型设备。
• 节点体：由花括号 { } 包裹，内部包含属性和子节点定义。
• 分号：每个属性定义和子节点定义结束后必须加分号 ;。

2.1.2 根节点与标准节点

每个设备树文件有且只有一个根节点，用 / 表示。所有硬件设备都挂载在根节点下。常见的标准节点包括：

2.2 属性（Property）

属性是节点中用于描述硬件特性的键值对。属性值可以是空、整数、整数数组、字符串、字符串列表、二进制数据或对另一个节点的引用（phandle）。

2.2.1 属性值类型与编码

2.2.2 标准属性

设备树规范定义了一系列标准属性，用于描述设备的基本信息：

• compatible：最重要的属性，用于操作系统匹配设备驱动。格式为 "厂商,设备型号"，如 "fsl,imx6q-uart"。
• reg：描述设备的寄存器地址空间，格式为 <address length>。
• interrupts：描述设备使用的中断号，格式取决于中断控制器。
• interrupt-parent：指定该设备连接的中断控制器节点。
• status：设备状态，常用值为 "okay"（启用）或 "disabled"（禁用）。
• clocks：描述设备使用的时钟源。
• pinctrl-0：引脚复用配置。

2.3 标签（Label）

标签是DTS中用于给节点或属性起别名的机制，方便在其他地方引用。标签以冒号 : 结尾，放在节点名称之前。

2.3.1 标签定义与引用

// 定义标签
gic: interrupt-controller@f0001000 {
    compatible = "arm,gic-400";
    reg = <0xf0001000 0x1000>;
    interrupt-controller;
};

// 引用标签
uart0: serial@ff010000 {
    compatible = "ns16550a";
    reg = <0xff010000 0x1000>;
    interrupt-parent = <&gic>;  // 通过 &gic 引用 gic 节点
    interrupts = <0 32 4>;
};

2.3.2 标签的用途

2.4 包含（Include）

DTS支持使用 #include 预处理指令来包含其他文件，实现代码复用和模块化。包含机制基于C预处理器（CPP），因此也支持宏定义。

2.4.1 包含语法

// 包含设备树头文件（.dtsi）
#include "soc.dtsi"
#include "board-common.dtsi"

// 包含头文件（.h），通常用于宏定义
#include 
#include 

/ {
    // 节点定义
};

2.4.2 包含文件类型

2.5 宏定义

由于DTS文件经过C预处理器处理，因此可以使用 #define 宏定义来定义常量，提高代码的可读性和可维护性。宏定义通常放在 .h 头文件中，通过 #include 引入。

2.5.1 宏定义示例

// gpio.h
#define GPIO_ACTIVE_HIGH 0
#define GPIO_ACTIVE_LOW  1

// 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

// board.dts
#include 
#include 

/ {
    gpio-keys {
        compatible = "gpio-keys";
        power-key {
            gpios = <&gpio1 3 GPIO_ACTIVE_LOW>;
            interrupts = <3 IRQ_TYPE_EDGE_FALLING>;
        };
    };
};

2.5.2 宏定义的优势

2.6 综合示例：完整的DTS文件

以下是一个综合示例，展示了节点、属性、标签、包含和宏定义的综合使用：

// soc.dtsi - SoC公共定义
#include 

/ {
    compatible = "arm,cortex-a72";
    
    gic: interrupt-controller@f0001000 {
        compatible = "arm,gic-400";
        reg = <0xf0001000 0x1000>;
        interrupt-controller;
        #interrupt-cells = <3>;
    };
    
    soc {
        #address-cells = <2>;
        #size-cells = <2>;
        
        uart0: serial@ff010000 {
            compatible = "ns16550a";
            reg = <0x0 0xff010000 0x0 0x1000>;
            interrupts = <GIC_SPI 32 IRQ_TYPE_LEVEL_HIGH>;
            interrupt-parent = <&gic>;
            status = "disabled";
        };
    };
};

// board.dts - 板级定制
#include "soc.dtsi"
#include 

/ {
    model = "MyBoard v2";
    compatible = "mycompany,myboard-v2", "mycompany,myboard";
    
    chosen {
        bootargs = "console=ttyS0,115200 root=/dev/mmcblk0p2";
    };
    
    gpio-keys {
        compatible = "gpio-keys";
        #address-cells = <1>;
        #size-cells = <0>;
        
        button@0 {
            label = "Power";
            gpios = <&gpio1 3 GPIO_ACTIVE_LOW>;
            linux,code = <116>;
        };
    };
};

// 覆盖uart0节点，启用并配置
&uart0 {
    status = "okay";
    clock-frequency = <24000000>;
};