3、设备树常用属性详解：compatible、reg、interrupts、clocks、status 等核心属性的含义与用法

设备树（Device Tree）是嵌入式 Linux 驱动与硬件平台之间的“契约文档”。驱动通过解析设备树节点中的属性来获取硬件资源信息，从而避免硬编码。本章将深入解析五个最核心的设备树属性：compatible、reg、interrupts、clocks 和 status，并结合实际案例说明其用法与排查要点。

3.1 compatible 属性：驱动匹配的“身份证”

compatible 属性是设备树节点与驱动之间建立关联的核心纽带。它定义了一个或多个字符串，用于标识设备的具体型号和兼容性。

3.1.1 属性格式与匹配规则

// 设备树节点示例
i2c@1c2a000 {
    compatible = "allwinner,sun8i-h3-i2c", "allwinner,sun6i-a31-i2c";
    reg = <0x01c2a000 0x400>;
    #address-cells = <1>;
    #size-cells = <0>;
    
    eeprom@50 {
        compatible = "atmel,24c02";
        reg = <0x50>;
    };
};

// 驱动端匹配表
static const struct of_device_id sun6i_i2c_of_match[] = {
    { .compatible = "allwinner,sun8i-h3-i2c", .data = &sun8i_h3_i2c_data },
    { .compatible = "allwinner,sun6i-a31-i2c", .data = &sun6i_a31_i2c_data },
    { /* sentinel */ }
};
MODULE_DEVICE_TABLE(of, sun6i_i2c_of_match);

3.1.2 多级兼容与 fallback 机制

当同一 IP 核被多个 SoC 使用时，通常将最具体的型号放在第一位，将通用型号放在后面作为 fallback。驱动可以针对具体型号做优化，同时保留对通用型号的兼容性。

// 设备树：具体型号 + 通用型号
compatible = "ti,am335x-uart", "ns16550a";

// 驱动匹配表：可以同时匹配具体型号和通用型号
static const struct of_device_id ns16550_of_match[] = {
    { .compatible = "ti,am335x-uart", .data = &am335x_uart_data },
    { .compatible = "ns16550a", .data = &ns16550a_data },
    { /* sentinel */ }
};

3.2 reg 属性：硬件地址空间的“地图”

reg 属性描述了设备在系统总线上的地址空间，包括起始地址和长度。它是驱动获取 MMIO（内存映射 I/O）基地址的主要来源。

3.2.1 地址与大小编码规则

reg 属性的解析依赖于父节点的 #address-cells 和 #size-cells 属性：

// 32位地址空间示例
soc {
    #address-cells = <1>;
    #size-cells = <1>;
    
    uart@1c28000 {
        reg = <0x01c28000 0x400>;  // 起始地址 0x01c28000，大小 0x400
    };
};

// 64位地址空间示例
pcie@40000000 {
    #address-cells = <3>;
    #size-cells = <2>;
    
    pcie-ep@0,0 {
        reg = <0x0000 0x0000 0x0000 0x0 0x100000>;  // 3个地址单元 + 2个大小单元
    };
};

3.2.2 多段 reg 与索引访问

一个设备可能拥有多个独立的地址空间段，例如控制寄存器区域和 DMA 描述符区域。驱动通过索引来访问不同的段。

// 设备树：两段 reg
dma@1c02000 {
    compatible = "allwinner,sun8i-h3-dma";
    reg = <0x01c02000 0x1000>,  // 控制寄存器段 (index 0)
          <0x01c03000 0x1000>;  // 描述符段 (index 1)
};

// 驱动端访问
struct resource *res;
void __iomem *base0, *base1;

// 获取第0段
res = platform_get_resource(pdev, IORESOURCE_MEM, 0);
base0 = devm_ioremap_resource(&pdev->dev, res);

// 获取第1段
res = platform_get_resource(pdev, IORESOURCE_MEM, 1);
base1 = devm_ioremap_resource(&pdev->dev, res);

3.3 interrupts 属性：中断资源的“信号线”

interrupts 属性描述了设备使用的中断资源，包括中断号、触发类型和优先级等信息。它依赖于中断控制器（interrupt-controller）的解析规则。

3.3.1 中断属性格式

// GIC 中断控制器定义
gic: interrupt-controller@1c81000 {
    compatible = "arm,gic-400";
    reg = <0x01c81000 0x1000>,
          <0x01c82000 0x2000>;
    interrupt-controller;
    #interrupt-cells = <3>;  // 格式: <中断类型 中断号 触发类型>
};

// 设备使用中断
uart@1c28000 {
    compatible = "ns16550a";
    reg = <0x01c28000 0x400>;
    interrupts = <0 29 4>;  // SPI 中断，中断号 29，高电平触发
    interrupt-parent = <&gic>;
};

// 驱动端获取中断
int irq_num;
irq_num = platform_get_irq(pdev, 0);  // 获取第0个中断号
if (irq_num < 0) {
    dev_err(&pdev->dev, "failed to get IRQ\n");
    return irq_num;
}

// 使用中断名称获取
int rx_irq = platform_get_irq_byname(pdev, "rx");

3.3.2 中断触发类型编码

3.4 clocks 属性：时钟资源的“电源开关”

clocks 属性描述了设备所需的时钟源，包括时钟控制器 phandle 和时钟索引。驱动通过时钟框架（CCF）来使能、关闭或调整时钟频率。

3.4.1 时钟属性结构

// 时钟控制器定义
ccu: clock-controller@1c20000 {
    compatible = "allwinner,sun8i-h3-ccu";
    reg = <0x01c20000 0x400>;
    #clock-cells = <1>;  // 1个时钟索引单元
};

// 设备使用时钟
mmc@1c0f000 {
    compatible = "allwinner,sun8i-h3-mmc";
    reg = <0x01c0f000 0x1000>;
    clocks = <&ccu CLK_BUS_MMC0>, <&ccu CLK_MMC0>;
    clock-names = "ahb", "mmc";
};

// 驱动端获取时钟
struct clk *ahb_clk, *mmc_clk;

ahb_clk = devm_clk_get(&pdev->dev, "ahb");
if (IS_ERR(ahb_clk))
    return PTR_ERR(ahb_clk);

mmc_clk = devm_clk_get(&pdev->dev, "mmc");
if (IS_ERR(mmc_clk))
    return PTR_ERR(mmc_clk);

// 使能时钟
clk_prepare_enable(ahb_clk);
clk_prepare_enable(mmc_clk);

3.5 status 属性：设备的“开关”

status 属性控制设备节点的启用状态，是设备树覆盖（overlay）和板级适配中最常用的属性之一。

3.5.1 状态值定义

// SoC dtsi 中默认禁用
uart1: serial@1c28400 {
    compatible = "ns16550a";
    reg = <0x01c28400 0x400>;
    interrupts = <0 30 4>;
    status = "disabled";
};

// 板级 dts 中启用
&uart1 {
    pinctrl-0 = <&uart1_pins>;
    pinctrl-names = "default";
    status = "okay";
};

3.6 核心属性综合关系图

下图展示了设备树节点与驱动之间的核心属性交互关系：

3.7 属性排查速查表

3.8 综合案例：UART 设备树适配

以下是一个完整的 UART 设备树节点及其驱动适配示例，展示了上述属性的综合应用：

// 设备树节点 (dts)
uart0: serial@1c28000 {
    compatible = "ns16550a";
    reg = <0x01c28000 0x400>;
    interrupts = <0 29 4>;
    interrupt-parent = <&gic>;
    clocks = <&ccu CLK_BUS_UART0>, <&ccu CLK_UART0>;
    clock-names = "apb", "uart";
    pinctrl-0 = <&uart0_pins>;
    pinctrl-names = "default";
    status = "disabled";
};

// 板级启用
&uart0 {
    status = "okay";
};

// 驱动 probe 函数片段
static int ns16550_probe(struct platform_device *pdev)
{
    struct resource *res;
    void __iomem *base;
    int irq;
    struct clk *apb_clk, *uart_clk;
    
    // 1. 获取 MMIO 基址
    res = platform_get_resource(pdev, IORESOURCE_MEM, 0);
    base = devm_ioremap_resource(&pdev->dev, res);
    if (IS_ERR(base))
        return PTR_ERR(base);
    
    // 2. 获取中断号
    irq = platform_get_irq(pdev, 0);
    if (irq < 0)
        return irq;
    
    // 3. 获取时钟
    apb_clk = devm_clk_get(&pdev->dev, "apb");
    if (IS_ERR(apb_clk))
        return PTR_ERR(apb_clk);
    
    uart_clk = devm_clk_get(&pdev->dev, "uart");
    if (IS_ERR(uart_clk))
        return PTR_ERR(uart_clk);
    
    // 4. 使能时钟
    clk_prepare_enable(apb_clk);
    clk_prepare_enable(uart_clk);
    
    // 5. 注册中断处理
    devm_request_irq(&pdev->dev, irq, uart_isr, 0, "ns16550", port);
    
    // 6. 注册串口驱动
    uart_add_one_port(&ns16550_driver, port);
    
    return 0;
}