/device-tree

name: device-tree
description: Device tree skill for Linux hardware description. Use when writing DTS/DTSI, bindings, overlays, phandles, or debugging OF platform probe failures. Activates on queries about device tree, DTS syntax, phandle, devicetree bindings, DT overlay, or OF graph.

Device Tree (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.

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`

Workflow

1. DTS structure

/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

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

3. Phandles

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

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

4. Kernel parsing

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. Compile and inspect

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](https://www.devicetree.org/) — always cite binding name in commits.

6. Overlays (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 usage

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

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 |

Related Skills

• `skills/kernel-dev/platform-device-model` — probe and sysfs
• `skills/kernel/device-drivers` — `devm_of_iomap`
• `skills/baremetal/datasheet-and-refmanual-reading` — HW to DT mapping
• `skills/embedded/zephyr` — Zephyr devicetree (different tooling)
• `skills/kernel-dev/bus-drivers-i2c-spi` — bus node children