Device Tree Explained: Describing Hardware to Linux

A PC discovers its hardware through firmware tables and buses that enumerate themselves. Most embedded boards have neither: an I2C sensor or a GPIO-driven LED cannot announce itself. Linux on Arm, RISC-V and other embedded architectures therefore reads a device tree, a data structure describing the hardware, which the bootloader passes to the kernel at boot. This article explains how it is organised and used.

At a glance

.dts
Device tree source: the human-readable text file describing a board.
.dtb
The compiled binary blob the bootloader passes to the kernel.
compatible
The property the kernel matches against drivers to decide which one handles a node.
Overlay
A fragment applied on top of a base tree, used for add-on boards and options.

The problem

A device tree error rarely produces a clear message. A wrong interrupt number, a misspelt compatible string or a node left disabled simply means a driver never probes, and the symptom is a missing device with nothing obvious in the log.

Copying nodes from another board is the usual cause. Pin multiplexing, clock assignments and regulator references differ between boards even with the same processor, and a node correct on the evaluation board can be quietly wrong on yours.

The device tree is the board schematic written for the kernel. Review it against the schematic, line by line.

How it fits together

The processor vendor provides an include file describing the system-on-chip: every peripheral with its address, interrupts and clocks, mostly marked disabled. The board file includes it, enables the peripherals the board uses, sets their pin multiplexing and adds child nodes for external devices such as a sensor on an I2C bus.

The device tree compiler turns the source into a binary blob. At boot the kernel walks the tree and, for each enabled node, looks for a driver whose match table lists the same compatible string. The bindings documentation in the kernel source defines which properties each compatible string requires, and most bindings are now machine-checkable schemas.

What good looks like

Start from the vendor include file and the evaluation board file, then create your own board file rather than editing theirs.

Enable each peripheral the schematic uses, check its pins and supplies against the schematic, and add nodes for external devices with their bus addresses and interrupts.

Validate the tree against the bindings with the kernel schema checks, then confirm on hardware that each driver probes.

From source to running drivers

  1. SoC .dtsi: Vendor describes the chip
  2. Board .dts: Enables and wires peripherals
  3. dtc: Compiles to a .dtb blob
  4. Bootloader: Loads the blob, passes it on
  5. Kernel: Matches nodes to drivers
The device tree is data: it is compiled, loaded and read, never executed.
Properties found in most nodes
PropertyMeaning
compatibleIdentifies the device so the kernel can pick a driver
regRegister address and size, or the address on a bus
interruptsThe interrupt line or lines the device uses
clocksThe clock inputs the device needs
pinctrl-0The pin multiplexing configuration to apply
statusokay enables the node; disabled leaves it off
Standard properties from the Devicetree Specification and common kernel bindings.

What it changes

Faster Bring-Up

Each interface works when its driver is enabled, or fails with a clear cause.

Fewer Kernel Patches

Board differences live in data, not in modified driver code.

Reusability

Board variants share a common include file and differ only where the hardware does.

Upstream Readiness

A tree that follows the bindings can be submitted alongside mainline support.

Where to go next

Use overlays for genuinely optional hardware, such as plug-in modules, instead of near-identical board files.

When a device does not appear, check its driver probe messages and the running tree under /proc/device-tree before changing code.

Problems this prevents

  • Drivers that never probe, with no error shown
  • Nodes copied from a board with different wiring
  • Edits made directly to the vendor board file
  • Near-duplicate trees for every variant

Discuss your project

Email support@aavico.com or use Get in Touch when the website finishes loading.