device-tree

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.