Skip to content

Device Tree Overlay

Device Tree describes hardware that cannot be discovered automatically. On Raspberry Pi and many embedded Linux platforms, overlays are used to enable or modify hardware descriptions without rebuilding the full base Device Tree.

What Problem It Solves

Kernel drivers need to know which hardware exists and how it is wired. Device Tree provides this information through nodes and properties:

  • compatible selects the matching driver.
  • reg describes addresses or bus-specific device IDs.
  • gpios properties describe GPIO mappings.
  • interrupts describes interrupt lines and trigger types.
  • bus nodes such as I2C and SPI describe child devices.

Overlay Flow

DTS overlay source
    ↓ dtc
DTBO overlay blob
    ↓ load by bootloader or dtoverlay
merged Device Tree
    ↓ compatible match
platform / i2c / spi driver probe

Driver Binding Flow

Device Tree node
    compatible = "myvendor,mydevice"
        ↓
of_device_id match table
        ↓
driver probe()
        ↓
resource lookup and device initialization

Common Properties

Property Purpose
compatible Driver matching identifier.
reg Address or bus-specific device address.
gpios / xxx-gpios GPIO resource mapping.
interrupt-parent Interrupt controller reference.
interrupts Interrupt line and trigger type.
status Enables or disables a node.

Common Pitfalls

  • Node names do not control driver matching; compatible does.
  • Device Tree labels are only internal DTS references.
  • devm_gpiod_get(dev, "led", ...) looks for led-gpios.
  • I2C and SPI devices should be placed under the correct bus node.
  • Overlay warnings often come from incorrect #address-cells, #size-cells, or reg formatting.