3. 设备树基础语法：节点、属性、标签、包含文件（#include）、节点引用与覆盖

设备树（Device Tree，DT）是一种描述硬件资源的数据结构，它使用树形层次结构将系统中的设备、总线、中断、时钟、GPIO 等信息以节点和属性的形式组织起来。对于 SPI 设备配置而言，掌握设备树的基础语法是编写正确设备树文件的前提。本章将系统讲解设备树的五大核心语法要素：节点、属性、标签、包含文件以及节点引用与覆盖。

3.1 节点（Node）：设备树的骨架

节点是设备树的基本组成单元，每个节点代表一个硬件设备、总线、控制器或功能模块。节点通过路径（path）唯一标识，路径从根节点（/）开始，类似文件系统的目录结构。

3.1.1 节点定义语法

// 节点定义格式
[label:] node-name[@unit-address] {
    [property-definitions]
    [child-node-definitions]
};

• node-name：节点名称，描述设备类型，如 spi、gpio、serial。
• @unit-address：可选，通常为设备在总线上的地址（如 SPI 片选号、寄存器基地址）。
• label：可选，节点标签，用于在其他位置引用该节点。
• 花括号 {} 和分号 ;：节点体必须用花括号包裹，并以分号结束。

3.1.2 根节点与子节点

每个设备树文件有且只有一个根节点（/），所有其他节点都是根节点的后代。SPI 控制器节点通常挂接在 SoC 内部总线节点（如 soc、ahb、apb）下，而 SPI 外设节点则作为 SPI 控制器的子节点。

/ {
    model = "Embedded SPI Demo Board";
    compatible = "vendor,spi-board";

    soc {
        spi@ff010000 {
            compatible = "vendor,spi-controller";
            reg = <0xff010000 0x1000>;
            #address-cells = <1>;
            #size-cells = <0>;

            // SPI 外设子节点
            spi-device@0 {
                compatible = "vendor,spi-sensor";
                reg = <0>;  // 片选号 0
                spi-max-frequency = <10000000>;
            };
        };
    };
};

3.2 属性（Property）：描述节点的特征

属性是附着在节点上的键值对，用于描述设备的硬件特性、配置参数和连接关系。属性值可以是字符串、整数、字节数组、字符串列表或二进制数据。

3.2.1 常用属性类型

3.2.2 SPI 设备关键属性

在配置 SPI 外设节点时，以下属性是驱动正确工作的基础：

• compatible：驱动匹配字符串，格式为 "厂商,设备型号"，如 "maxim,ds1307"。
• reg：SPI 片选号（CS），对于 SPI 总线，#address-cells = <1> 时，reg = <0> 表示 CS0。
• spi-max-frequency：设备支持的最大 SPI 时钟频率，单位 Hz。
• spi-cpha / spi-cpol：布尔属性，配置 SPI 模式（CPHA/CPOL）。
• spi-cs-high：布尔属性，片选信号高电平有效（默认低电平）。
• interrupts：中断号，需配合中断控制器使用。

// 完整的 SPI 外设节点属性示例
&spi1 {
    status = "okay";

    temperature-sensor@0 {
        compatible = "ti,lm70";
        reg = <0>;                    // 片选 CS0
        spi-max-frequency = <10000000>; // 10 MHz
        spi-cpha;                      // CPHA = 1
        spi-cpol;                      // CPOL = 1
        // 等效于 SPI 模式 3
        interrupts = <5 2>;           // 中断号 5，触发类型 2（下降沿）
    };
};

3.3 标签（Label）：节点的别名

标签是节点的别名，用于在设备树的其他位置快速引用该节点。标签定义在节点名称之前，使用冒号分隔。标签的主要用途包括：

• 简化引用：避免书写冗长的节点路径。
• 节点覆盖：通过标签引用节点并修改其属性。
• 驱动绑定：驱动代码中通过标签查找节点。

// 定义标签
spi1: spi@ff010000 {
    compatible = "vendor,spi-controller";
    reg = <0xff010000 0x1000>;
    #address-cells = <1>;
    #size-cells = <0>;
};

// 在其他位置通过 &spi1 引用
&spi1 {
    status = "okay";
    pinctrl-0 = <&pinctrl_spi1>;
};

标签的命名规范：

• 使用小写字母、数字和下划线。
• 避免使用关键字（如 compatible、reg）。
• 建议使用设备功能缩写，如 spi1、i2c2、uart3。

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

设备树支持 C 语言预处理器指令 #include，用于包含头文件（.h）或其他设备树源文件（.dtsi）。这是实现设备树模块化和复用性的核心机制。

3.4.1 包含文件的作用

3.4.2 包含文件实战

// my-board.dts
#include "soc-common.dtsi"       // 包含 SoC 公共定义
#include "pinfuncs.h"            // 包含引脚复用宏

/ {
    model = "My SPI Board";
    compatible = "vendor,my-board";
};

// 引用并覆盖 soc-common.dtsi 中定义的 spi1 节点
&spi1 {
    status = "okay";
    pinctrl-0 = <&pinctrl_spi1>;

    adc@0 {
        compatible = "ti,ads1256";
        reg = <0>;
        spi-max-frequency = <19200000>;
        // 使用头文件中定义的宏
        clocks = <&clks IMX6UL_CLK_SPI1>;
    };
};

3.5 节点引用与覆盖（Reference & Overlay）

节点引用与覆盖是设备树实现“增量修改”的核心机制。通过标签引用一个已存在的节点，可以在不重新定义整个节点的情况下，添加或修改其属性和子节点。

3.5.1 引用语法

// 引用格式：<label> { ... };
&spi1 {
    status = "okay";
    // 添加新属性或覆盖已有属性
    pinctrl-0 = <&pinctrl_spi1>;
};

3.5.2 覆盖规则

3.5.3 覆盖实战：SPI 设备配置

// soc-common.dtsi 中定义 SPI 控制器骨架
spi1: spi@ff010000 {
    compatible = "vendor,spi-controller";
    reg = <0xff010000 0x1000>;
    #address-cells = <1>;
    #size-cells = <0>;
    status = "disabled";  // 默认关闭
};

// my-board.dts 中覆盖配置
#include "soc-common.dtsi"

&spi1 {
    status = "okay";                    // 覆盖为启用
    pinctrl-0 = <&pinctrl_spi1>;        // 添加引脚配置
    cs-gpios = <&gpio1 0 GPIO_ACTIVE_LOW>; // 添加片选 GPIO

    // 添加 SPI 外设子节点
    spi-nor@0 {
        compatible = "jedec,spi-nor";
        reg = <0>;
        spi-max-frequency = <50000000>;
        m25p,fast-read;
    };

    spi-touch@1 {
        compatible = "vendor,touch-controller";
        reg = <1>;
        spi-max-frequency = <10000000>;
        interrupt-parent = <&gpio2>;
        interrupts = <3 IRQ_TYPE_EDGE_FALLING>;
    };
};

3.6 综合示例：完整的 SPI 设备树配置

以下是一个完整的板级设备树文件，综合运用了本章所学的所有语法要素：

// my-spi-board.dts
#include "soc-imx6ull.dtsi"       // SoC 公共定义
#include "imx6ull-pinfunc.h"      // 引脚复用宏

/ {
    model = "My SPI Sensor Board";
    compatible = "vendor,my-spi-board";

    chosen {
        stdout-path = &uart1;
    };

    // 板级 GPIO 按键
    gpio-keys {
        compatible = "gpio-keys";
        button@0 {
            label = "USER-BUTTON";
            gpios = &gpio5 1 GPIO_ACTIVE_LOW;
            linux,code = <KEY_ENTER>;
        };
    };
};

// 引用并覆盖 SPI 控制器
&spi1 {
    status = "okay";
    pinctrl-names = "default";
    pinctrl-0 = <&pinctrl_spi1>;
    cs-gpios = <&gpio4 11 GPIO_ACTIVE_LOW>;

    // SPI 温度传感器
    temp-sensor@0 {
        compatible = "maxim,ds18b20-spi";
        reg = <0>;
        spi-max-frequency = <4000000>;
        spi-cpha;
        spi-cpol;
        resolution = <12>;
    };

    // SPI ADC
    adc@1 {
        compatible = "ti,ads1256";
        reg = <1>;
        spi-max-frequency = <19200000>;
        interrupts = <6 IRQ_TYPE_EDGE_RISING>;
        vref-supply = <®_vref>;
    };
};

// 引脚复用配置
&iomuxc {
    pinctrl_spi1: spi1grp {
        fsl,pins = <
            MX6UL_PAD_CSI_DATA00__GPIO4_IO11  0x10b0  // CS
            MX6UL_PAD_CSI_DATA01__ECSPI1_MISO 0x10b0  // MISO
            MX6UL_PAD_CSI_DATA02__ECSPI1_MOSI 0x10b0  // MOSI
            MX6UL_PAD_CSI_DATA03__ECSPI1_SCLK 0x10b0  // SCLK
        >;
    };
};

// 电源节点
®_vref {
    regulator-name = "vref-3v3";
    regulator-min-microvolt = <3300000>;
    regulator-max-microvolt = <3300000>;
};