device-tree

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Device Tree (Devicetree)

设备树（Devicetree）

Purpose

用途

Guide agents through Linux device tree source (DTS): syntax, bindings, phandles, overlays, and how the kernel OF (Open Firmware) layer parses hardware description into

platform_device

instances.

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

platform_device

实例。

When to Use

使用场景

Platform driver not probing — DT mismatch
Adding a new board
```
.dts
```
or fragment overlay
Understanding
```
compatible
```
,
```
reg
```
,
```
interrupts
```
,
```
clocks
```
properties
Cross-checking hardware with
```
skills/kernel-dev/platform-device-model
```

平台驱动未触发探测——设备树不匹配
添加新的单板
```
.dts
```
或片段式设备树覆盖
理解
```
compatible
```
、
```
reg
```
、
```
interrupts
```
、
```
clocks
```
属性
结合
```
skills/kernel-dev/platform-device-model
```
交叉验证硬件

Workflow

工作流程

1. DTS structure

1. DTS结构

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";
        };
    };
};

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. Key properties

2. 关键属性

Property	Meaning
`compatible`	Driver match string (most specific first)
`reg`	MMIO address + length ( `#address-cells` , `#size-cells` )
`interrupts`	IRQ specifier (interrupt parent defines cells)
`clocks` / `clock-names`	phandle to clock provider
`status`	`"disabled"` skips probe

属性	含义
`compatible`	驱动匹配字符串（最具体的放在前面）
`reg`	MMIO地址 + 长度（由 `#address-cells` 、 `#size-cells` 定义格式）
`interrupts`	IRQ描述符（中断父节点定义格式）
`clocks` / `clock-names`	指向时钟提供者的phandle
`status`	设置为 `"disabled"` 会跳过探测

3. Phandles

dts

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

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

dts

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

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

4. Kernel parsing

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);

OF核心在启动时读取DTB
├── of_platform_populate() 创建platform_devices
└── 驱动的`.of_match_table`匹配`compatible`字段

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

5. Compile and inspect

5. 编译与检查

bash

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/

Bindings live at devicetree.org — always cite binding name in commits.

bash

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. Overlays (configfs)

6. 设备树覆盖（configfs）

bash

undefined

bash

undefined

Runtime overlay apply (when CONFIG_OF_OVERLAY)

运行时应用设备树覆盖（需开启CONFIG_OF_OVERLAY配置）

mkdir -p /config/device-tree/overlays/my-overlay cat my-overlay.dtbo > /config/device-tree/overlays/my-overlay/dtbo

undefined

mkdir -p /config/device-tree/overlays/my-overlay cat my-overlay.dtbo > /config/device-tree/overlays/my-overlay/dtbo

undefined

7. Agent usage

7. Agent使用示例

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

/device-tree 编写用于i2c1总线上、中断连接到GPIO5的I2C传感器的DTS片段

Common Problems

常见问题

Symptom	Cause	Fix
Driver not bound	`compatible` typo	Match driver's `of_match_table`
Wrong MMIO	`#address-cells` mismatch	Follow SoC `.dtsi`
IRQ not firing	Wrong interrupt parent/cells	Copy from working board DTS
Probe defer loop	Clock/regulator missing	`-EPROBE_DEFER` supplier in DT
Overlay fails	Symbol unresolved	`__fixups__` / label exports

症状	原因	解决方法
驱动未绑定	`compatible` 字段拼写错误	与驱动的 `of_match_table` 保持一致
MMIO地址错误	`#address-cells` 不匹配	遵循SoC的 `.dtsi` 文件定义
IRQ未触发	中断父节点/格式错误	参考正常工作的单板DTS配置
探测延迟循环	缺少时钟/调节器	在设备树中添加 `-EPROBE_DEFER` 提供者
设备树覆盖应用失败	符号未解析	使用 `__fixups__` /标签导出

device-tree

Original

Translation

Device Tree (Devicetree)

设备树（Devicetree）

Purpose

用途

When to Use

使用场景

Workflow

工作流程

1. DTS structure

1. DTS结构

2. Key properties

2. 关键属性

3. Phandles

3. Phandles

4. Kernel parsing

4. 内核解析流程

5. Compile and inspect

5. 编译与检查

6. Overlays (configfs)

6. 设备树覆盖（configfs）

Runtime overlay apply (when CONFIG_OF_OVERLAY)

运行时应用设备树覆盖（需开启CONFIG_OF_OVERLAY配置）

7. Agent usage

7. Agent使用示例

Common Problems

常见问题

Related Skills

相关技能