device-tree

Device Tree（设备树）

用途

指导 Agent 使用 Linux 设备树源文件（DTS）：语法、绑定、phandle、覆盖层，以及内核 OF（Open Firmware）层如何将硬件描述解析为 platform_device 实例。

适用场景

• 平台驱动未能探测到设备——DT 不匹配
• 添加新的板级 .dts 或片段覆盖层
• 理解 compatible、reg、interrupts、clocks 属性
• 将硬件信息与 skills/kernel-dev/platform-device-model 交叉核对

工作流

1. DTS 结构

/dts-v1/;
#include "soc.dtsi"

/ {
    model = "My Board";
    compatible = "vendor,my-board", "vendor,soc-family";

    soc {
        uart0: serial@40011000 {
            compatible = "vendor,uart";
            reg = <0x40011000 0x400>;
            interrupts = <GIC_SPI 38 IRQ_TYPE_LEVEL_HIGH>;
            clocks = <&clk_uart0>;
            status = "okay";
        };
    };
};

2. 关键属性

属性	含义
compatible	驱动匹配字符串（按具体程度从高到低排列）
reg	MMIO 地址 + 长度（ #address-cells、#size-cells ）
interrupts	IRQ 说明符（中断父节点定义单元格）
clocks / clock-names	指向时钟提供方的 phandle
status	"disabled" 会跳过探测

3. Phandle

clk_uart0: clock-uart {
    compatible = "vendor,clk";
    #clock-cells = <0>;
};

serial@... {
    clocks = <&clk_uart0>;  /* phandle reference */
};

4. 内核解析

OF core reads DTB at boot
├── of_platform_populate() creates platform_devices
└── driver `.of_match_table` matches `compatible`

static const struct of_device_id my_of_match[] = {
    { .compatible = "vendor,uart" },
    { }
};
MODULE_DEVICE_TABLE(of, my_of_match);

5. 编译和检查

dtc -I dts -O dtb -o board.dtb board.dts
dtc -I fs -O dts /proc/device-tree 2>/dev/null | less
ls /sys/firmware/devicetree/base/

绑定信息位于 devicetree.org——提交时务必注明绑定名称。

6. 覆盖层（configfs）

# Runtime overlay apply (when CONFIG_OF_OVERLAY)
mkdir -p /config/device-tree/overlays/my-overlay
cat my-overlay.dtbo > /config/device-tree/overlays/my-overlay/dtbo

7. Agent 用法

/device-tree Write DTS fragment for I2C sensor on i2c1 with interrupt on GPIO5

常见问题

现象	原因	修复方法
驱动未绑定	compatible 拼写错误	与驱动的 of_match_table 匹配
MMIO 地址错误	#address-cells 不匹配	遵循 SoC .dtsi
IRQ 未触发	中断父节点或单元格错误	从正常工作的板级 DTS 复制
探测延迟循环	缺少时钟/稳压器	DT 中的 -EPROBE_DEFER 供应方
覆盖层失败	符号未解析	__fixups__ / 标签导出

相关技能

• skills/kernel-dev/platform-device-model — 探测和 sysfs
• skills/kernel/device-drivers — devm_of_iomap
• skills/baremetal/datasheet-and-refmanual-reading — 从硬件映射到 DT
• skills/embedded/zephyr — Zephyr 设备树（工具链不同）
• skills/kernel-dev/bus-drivers-i2c-spi — 总线节点子节点