What are device tree overlays?
Short answer: An overlay (.dtbo) is a device tree fragment applied on top of a base tree to add or modify nodes, usually by the bootloader (fdt apply in U-Boot, dtoverlay= in the Raspberry Pi firmware) before the kernel starts. Overlays are used for add-on boards (HATs, capes, mezzanines), optional peripherals and per-product variants without rebuilding the base DTB.
/dts-v1/;
/plugin/;
&i2c1 {
#address-cells = <1>;
#size-cells = <0>;
status = "okay";
rtc@68 {
compatible = "dallas,ds1307";
reg = <0x68>;
};
};
Build and apply
dtc -@ -I dts -O dtb -o rtc.dtbo rtc-overlay.dts # -@ keeps symbols for &label references
# U-Boot
fdt addr ${fdt_addr_r}; fdt resize 8192
load mmc 0:1 ${loadaddr} rtc.dtbo; fdt apply ${loadaddr}
The base DTB must also be compiled with -@ so it contains a __symbols__ node that overlays can reference.
Run-time overlays: applying overlays after boot (configfs overlay interface) is not in mainline in a general form because removing hardware descriptions safely is hard; it exists in vendor kernels and for FPGA manager use cases.
Alternatives: separate DTBs per variant selected by the bootloader, FIT images with multiple configurations, or U-Boot board code that patches the tree (ft_board_setup).