Device Tree Overlay Build Workflow¶

Device Tree overlays are used to describe additional hardware configuration without rebuilding the full base Device Tree.

In this project, overlays are commonly used for:

platform driver binding
GPIO mapping
IRQ routing
I2C and SPI device instantiation

Typical Overlay Build Command¶

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

The -@ option is important because overlays require symbol information.

Raspberry Pi Overlay Install Flow¶

sudo cp my-overlay.dtbo /boot/firmware/overlays/
sudo dtoverlay my-overlay

Check the active overlay state and kernel messages:

dmesg | tail -n 50
dtoverlay -l

Typical Overlay Pattern¶

/dts-v1/;
/plugin/;

/ {
    compatible = "brcm,bcm2712";

    fragment@0 {
        target-path = "/";
        __overlay__ {
            my_device: my-device {
                compatible = "myvendor,my-device";
                status = "okay";
            };
        };
    };
};

GPIO Property Naming¶

For descriptor-based GPIO APIs:

devm_gpiod_get(dev, "reset", GPIOD_OUT_LOW);

Device Tree should provide:

reset-gpios = <&gpio 17 GPIO_ACTIVE_HIGH>;

Common Pitfalls¶

missing /plugin/;
missing -@ when compiling the overlay
wrong compatible string
incorrect #address-cells or #size-cells
GPIO controller label mismatch
overlay applied but driver not matched
pin already used by another overlay or driver