Device Tree Overlays

A device tree (DT) is a data structure of named nodes and properties that describe non-discoverable hardware. Operating systems, such as the Linux kernel used in Android, use DTs to support a wide range of hardware configurations used by Android-powered devices. Hardware vendors supply their own DT source files, which Linux then compiles into the Device Tree Blob (DTB) file used by the bootloader.

A device tree overlay (DTO) enables a central DTB to be overlaid on the device tree. A bootloader using DTO can maintain the system-on-chip (SoC) DT and dynamically overlay a device-specific DT, adding nodes to the tree and making changes to properties in the existing tree.

This page details a typical bootloader workflow for loading a DT and provides a list of common DT terms. Other pages in this section describe how to implement bootloader support for DTO, how to compile, verify, and optimize your DTO implementation, and how to use multiple DTs. You can also get details on DTO syntax and recommended DTO/DTBO partition formatting.

Loading a device tree

Loading a device tree in bootloader involves building, partitioning, and running.

Figure 1. Typical implementation for loading device tree in bootloader.
  1. To build:
    • Use the device tree compiler (dtc) to compile device tree source (.dts) into a device tree blob (.dtb), formatted as a flattened device tree.
    • Flash the .dtb file into a bootloader runtime-accessible location (detailed below).
  2. To partition, determine a bootloader runtime-accessible and trusted location in flash memory to put .dtb. Example locations:
    Boot Partition
    Figure 2. Put .dtb in boot partition by appending to image.gz and passing as "kernel" to mkbootimg.
    Unique Partition
    Figure 3. Put .dtb in an unique partition (e.g. dtb partition).
  3. To run:
    • Load .dtb from storage into memory.
    • Start kernel given the memory address of the loaded DT.

Terminology

This section uses the following device tree terms:

DT Device Tree
DTB Device Tree Blob
DTBO Device Tree Blob for Overlay
DTC Device Tree Compiler
DTO Device Tree Overlay
DTS Device Tree Source
FDT Flattened Device Tree, a binary format contained in a .dtb blob file