Device Tree

Device tree

Contract

Inputs

1. Hardware fact to describe (required): the block or device, its MMIO base, IRQ, clocks, and the bus it sits on.
2. Board context (optional): the SoC .dtsi to include and the board .dts to extend.
3. Failure report (optional): the symptom, such as a driver that never probes or an IRQ that never fires.

Procedure

1. Lay out the node under its bus parent. A board file includes the SoC .dtsi and extends or references its nodes by label.

   /dts-v1/;
   #include "soc.dtsi"
   
   / {
       model = "My Board";
       compatible = "vendor,my-board", "vendor,soc-family";
   
       &uart0 {
           status = "okay";
       };
   };
   

   uart0: serial@40011000 {
       compatible = "vendor,uart";
       reg = <0x40011000 0x400>;
       interrupts = <GIC_SPI 38 IRQ_TYPE_LEVEL_HIGH>;
       clocks = <&clk_uart0>;
       status = "disabled"; /* the board file sets "okay" */
   };
   

   Done when: the node sits under the right bus parent and every cell count matches the parent's #address-cells and #size-cells.

2. Set the load-bearing properties correctly.

   Property	Meaning
   compatible	Driver match strings, most specific first
   reg	MMIO address and length, cells per #address-cells/#size-cells
   interrupts	IRQ specifier, cells defined by the interrupt parent
   clocks / clock-names	Phandles to clock providers
   status	"disabled" keeps the device unprobed

   Done when: each property value traces to the datasheet or the binding document.

3. Wire phandles for cross-node references. A phandle is the label reference the compiler resolves to a number.

   clk_uart0: clock-uart0 {
       compatible = "fixed-clock";
       #clock-cells = <0>;
   };
   
   &uart0 {
       clocks = <&clk_uart0>;
       clock-names = "apb_pclk";
   };
   

   Done when: every &label reference resolves to a node defined in the compiled tree.

4. Match the driver to the node. The OF core parses the DTB at boot; of_platform_populate() creates platform_device instances for bus nodes, and a driver binds when its of_match_table matches compatible.

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

   Done when: the driver's match table names the exact compatible string of the node.

5. Compile and inspect the tree. dtc ships with the kernel in scripts/dtc; make dtbs builds the in-tree boards.

   dtc -I dts -O dtb -o board.dtb board.dts
   dtc -I fs -O dts /proc/device-tree | less   # what the running kernel sees
   ls /sys/firmware/devicetree/base/
   

   Name the binding document (Documentation/devicetree/bindings/, YAML under dt-schema) in the commit that adds or changes a binding. Done when: the compiled DTB matches the running tree, or the delta explains the failure.

6. Apply overlays where the platform supports them. CONFIG_OF_OVERLAY gives the kernel core overlay support. Mainline applies overlays through the bootloader: U-Boot's fdt apply, or fdtoverlay to merge a .dtbo into the kernel FDT at build time. A runtime configfs interface (/sys/kernel/config/device-tree/overlays/) exists only on kernels carrying a vendor patch (CONFIG_OF_CONFIGFS); do not assume it on a mainline kernel. Overlay resolution failures name unresolved symbols in __fixups__; export the target labels as __symbols__ in the base DTB. Done when: the apply path is named for the actual kernel and boot chain.

7. Diagnose a probe failure bottom-up: confirm the node is present in the running tree (/proc/device-tree), confirm status is "okay", confirm the compatible string matches the driver table character for character, then confirm suppliers (clocks, regulators, phys) are available or the driver handles -EPROBE_DEFER. Route deeper work: platform-device-model for probe and driver-model behavior, bus-drivers-i2c-spi for I2C/SPI child nodes, datasheet-and-refmanual-reading for mapping hardware facts to DT properties. Done when: the first broken link in the chain is named.

Failure and recovery

Output

The node or board fragment; the property table with cell arithmetic; the phandle wiring; the driver match snippet; the compile and inspect transcript; the overlay apply path for the actual kernel; the named first broken link in the probe chain.