Device Tree Overlay (DTO)¶

Overview¶

Device Tree Overlay is a mechanism used to modify an existing Device Tree without rebuilding the base DTB.

Instead of editing the main Device Tree file, a small overlay file can be applied during boot to enable or modify hardware configuration.

Conceptually:

Base Device Tree
      +
Device Tree Overlay
      ↓
Final Device Tree used by kernel

Overlay acts like a patch applied to the base Device Tree.

Why Device Tree Overlay Exists¶

Without overlays, enabling a new peripheral would require:

1. Modify base Device Tree source (.dts)
2. Recompile DTB
3. Replace DTB
4. Reboot system

This is inconvenient for users.

With overlays:

Base DTB remains unchanged
Overlay adds or modifies nodes

This allows hardware modules to be enabled easily.

Example:

dtoverlay=spi0-1cs

This enables SPI without modifying the main Device Tree.

Overlay File Location (Raspberry Pi)¶

On Raspberry Pi OS, overlays are stored in:

/boot/firmware/overlays

Example files:

spi0-1cs.dtbo
i2c1.dtbo
uart2.dtbo
vc4-kms-v3d.dtbo

.dtbo is the compiled binary form of an overlay.

Enabling an Overlay¶

Overlays are enabled through the boot configuration file:

/boot/firmware/config.txt

Example configuration:

dtoverlay=spi0-1cs
dtoverlay=i2c1

During boot, the firmware will:

1. Load base Device Tree (.dtb)
2. Apply overlays
3. Pass the final Device Tree to the kernel

The kernel only sees the final merged Device Tree.

What an Overlay Changes¶

Most overlays modify properties inside existing nodes.

Example: enabling SPI controller.

Without overlay:

spi@7e204000 {
    status = "disabled";
};

After overlay:

spi@7e204000 {
    status = "okay";
};

This allows the kernel driver to initialize the SPI controller.

Overlay Source Example¶

Overlay source files are written in DTS format.

Example simplified overlay:

/dts-v1/;
/plugin/;

/ {
    fragment@0 {
        target = <&spi0>;

        __overlay__ {
            status = "okay";
        };
    };
};

Explanation:

Element	Meaning
`/plugin/`	indicates this file is an overlay
`fragment@0`	a modification block
`target`	reference to existing node
`__overlay__`	properties to modify

This example enables the spi0 node.

Compiling an Overlay¶

Overlay source file:

spi-overlay.dts

Compile using the Device Tree Compiler:

dtc -@ -I dts -O dtb -o spi-overlay.dtbo spi-overlay.dts

Important option:

Option	Meaning
`-@`	enable symbol support required for overlays

The output .dtbo file can then be loaded during boot.

Boot Flow with Overlay¶

On Raspberry Pi systems, the boot sequence is:

Boot ROM
   ↓
start.elf (GPU firmware)
   ↓
Load base Device Tree (.dtb)
   ↓
Apply overlays (.dtbo)
   ↓
Pass final Device Tree to kernel
   ↓
Kernel initialization

Overlays are applied before the kernel starts.

Practical Use Cases¶

Device Tree overlays are widely used for enabling hardware modules.

Examples:

Hardware	Overlay
SPI devices	spi overlay
I2C peripherals	i2c overlay
CAN controller	mcp2515 overlay
camera module	camera overlay
display driver	vc4 overlay

This allows a single kernel image to support many hardware configurations.

Key Concept¶

In Embedded Linux:

Hardware configuration → Device Tree
Driver implementation → Kernel
Runtime hardware modification → Device Tree Overlay

Overlays provide a flexible method to adapt the hardware configuration without modifying the base Device Tree.