3. 设备树基础：DTS 语法入门、节点与属性详解

设备树（Device Tree，DT）是嵌入式 Linux 中用于描述硬件拓扑结构的数据结构。在全志 T113 平台中，SPI 接口的引脚分配、时钟频率、DMA 通道等硬件信息均通过设备树传递给内核驱动。本章将系统讲解 DTS 语法、节点与属性的定义，以及 reg、status、compatible 等关键属性的使用规范。

3.1 设备树文件体系与基本语法

设备树源文件（.dts）通过 dtc 编译器生成二进制 .dtb 文件，由 bootloader 加载并传递给内核。全志 T113 平台通常包含以下文件层次：

DTS 语法采用树形结构，以分号结束语句，使用大括号表示层级。以下是一个典型的节点定义：

/dts-v1/;

#include "sun8iw20p1.dtsi"

/ {
    model = "Allwinner T113 Evaluation Board";
    compatible = "allwinner,t113-evb", "allwinner,sun8iw20p1";

    soc {
        spi0: spi@04026000 {
            compatible = "allwinner,sun8i-spi";
            reg = <0x04026000 0x1000>;
            interrupts = <GIC_SPI 11 IRQ_TYPE_LEVEL_HIGH>;
            clocks = <&ccu CLK_SPI0>, <&ccu CLK_BUS_SPI0>;
            clock-names = "spi", "ahb";
            resets = <&ccu RST_BUS_SPI0>;
            status = "disabled";
            #address-cells = <1>;
            #size-cells = <0>;
        };
    };
};

3.2 节点与属性基础

设备树由节点（node）和属性（property）组成。每个节点代表一个硬件设备或总线，属性描述该设备的配置参数。

3.2.1 节点命名规则

• 节点名称：格式为 node-name@unit-address，例如 spi0@04026000。
• unit-address：与 reg 属性的第一个地址段对应，用于区分同一层级下的相同名称节点。
• 标签（label）：在节点前添加标签，如 spi0:，便于在 .dts 中通过 &spi0 引用。

3.2.2 属性类型与写法

3.3 关键属性详解

3.3.1 compatible 属性——驱动匹配的钥匙

compatible 是设备树中最关键的属性，内核通过该属性查找对应的驱动程序。其值是一个字符串列表，优先级从前往后递减。

// SPI 控制器节点中的 compatible
compatible = "allwinner,sun8i-spi", "allwinner,sun6i-spi";

// 内核驱动匹配表（of_match_table）
static const struct of_device_id sun8i_spi_of_match[] = {
    { .compatible = "allwinner,sun8i-spi", .data = &sun8i_spi_variant },
    { .compatible = "allwinner,sun6i-spi", .data = &sun6i_spi_variant },
    { /* sentinel */ }
};
MODULE_DEVICE_TABLE(of, sun8i_spi_of_match);

3.3.2 reg 属性——地址空间描述

reg 属性描述设备在总线上的地址范围，由 #address-cells 和 #size-cells 决定地址和长度的编码方式。

// 父节点定义地址编码
spi0: spi@04026000 {
    #address-cells = <1>;   // 子节点地址使用 1 个 32 位整数
    #size-cells = <0>;      // 子节点无长度字段

    // 控制器本身的 reg
    reg = <0x04026000 0x1000>;  // 基地址 0x04026000，长度 0x1000

    // SPI 从设备子节点
    spidev@0 {
        reg = <0>;  // 片选号 0，无长度字段
    };
};

3.3.3 status 属性——设备使能开关

status 属性控制设备节点的启用状态。在 .dtsi 中默认设置为 disabled，板级 .dts 中根据需要修改为 okay。

// sun8iw20p1.dtsi 中默认关闭
spi0: spi@04026000 {
    status = "disabled";
};

// 板级 t113-evb.dts 中启用
&spi0 {
    status = "okay";
    pinctrl-0 = <&spi0_pins>;
    pinctrl-names = "default";
};

3.4 中断与时钟属性

3.4.1 interrupts 属性

中断属性描述设备使用的中断号、触发类型等信息。全志 T113 使用 GIC（通用中断控制器），中断描述格式如下：

interrupts = <GIC_SPI 11 IRQ_TYPE_LEVEL_HIGH>;
// GIC_SPI: 共享外设中断类型
// 11: 中断号（SPI 0 的中断号为 11）
// IRQ_TYPE_LEVEL_HIGH: 高电平触发

3.4.2 clocks 与 clock-names 属性

时钟属性为设备提供时钟源，clock-names 用于区分不同的时钟角色。

clocks = <&ccu CLK_SPI0>, <&ccu CLK_BUS_SPI0>;
clock-names = "spi", "ahb";

// 驱动中通过 devm_clk_get 获取时钟
struct spi_master *master = spi_alloc_master(dev, sizeof(struct sun8i_spi));
struct sun8i_spi *sspi = spi_master_get_devdata(master);

sspi->clk = devm_clk_get(dev, "spi");   // 获取 SPI 模块时钟
sspi->bus_clk = devm_clk_get(dev, "ahb"); // 获取 AHB 总线时钟

3.5 引脚复用配置（pinctrl）

全志 T113 的 SPI 引脚通过 pinctrl 子系统配置复用功能。引脚配置在 .dtsi 中预定义，板级文件通过 pinctrl-0 引用。

// sun8iw20p1.dtsi 中的引脚定义
spi0_pins: spi0-pins {
    pins = "PC0", "PC1", "PC2", "PC3";
    function = "spi0";
    drive-strength = <10>;
    bias-pull-up;
};

spi0_cs_pins: spi0-cs-pins {
    pins = "PC4";
    function = "spi0";
    drive-strength = <10>;
    bias-pull-up;
};

// 板级文件引用
&spi0 {
    pinctrl-0 = <&spi0_pins &spi0_cs_pins>;
    pinctrl-names = "default";
    status = "okay";
};

3.6 SPI 从设备子节点配置

在 SPI 控制器节点下，需要添加从设备子节点来描述挂载在 SPI 总线上的外设芯片。

&spi0 {
    status = "okay";
    pinctrl-0 = <&spi0_pins>;
    pinctrl-names = "default";

    spidev@0 {
        compatible = "spidev";
        reg = <0>;               // 片选 0
        spi-max-frequency = <50000000>;  // 50MHz
        spi-cpha;                // 时钟相位模式
        spi-cpol;                // 时钟极性模式
    };

    spidev@1 {
        compatible = "spidev";
        reg = <1>;               // 片选 1
        spi-max-frequency = <10000000>;  // 10MHz
    };
};

3.7 设备树编译与反编译

掌握 dtc 工具的使用是调试设备树的必备技能。

# 编译设备树：.dts -> .dtb
dtc -I dts -O dtb -o sun8iw20p1-t113-evb.dtb sun8iw20p1-t113-evb.dts
# 反编译设备树：.dtb -> .dts
dtc -I dtb -O dts -o sun8iw20p1-t113-evb.dts sun8iw20p1-t113-evb.dtb
# 检查设备树语法错误
dtc -I dts -O dtb -o /dev/null sun8iw20p1-t113-evb.dts
# 查看内核中当前使用的设备树
# 在目标板上执行：
cat /proc/device-tree/model
ls /proc/device-tree/soc/sp
        

            ← 上一章
            📖 返回目录
            下一章 →