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