Device tree overlays

A device tree (DT) is a data structure of named nodes and properties that describe non-discoverable hardware. Kernels, 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 device tree source (DTS) files, which are compiled into the device tree blob (DTB) file using the device tree compiler. These files are then used by the bootloader. The DTB file contains a binary-formatted flattened device tree.

A device tree overlay (DTO) enables a central DTB to be overlaid on the DT (a device tree blob for overlay (DTBO)). 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.

Updates in Android 9 release

In Android 9, the bootloader must not modify the properties defined in the DTOs before passing the unified DTB to the kernel.

Load a DT

Loading a DT in bootloader involves building, partitioning, and running.

Figure 1. Typical implementation for loading device tree in bootloader.

  1. To create and flash the DTB:

    1a. Use the DTC (dtc) to compile DTS (.dts) into a DTB (.dtb). The DTB is formatted as a flattened DT. 1b. 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:

    Figure 2. Put .dtb in a boot partition by
    appending to image.gz and passing as
    "kernel" to mkbootimg.

    Figure 3. Put .dtb in a unique partition
    (for example, dtb partition).

  3. To load the DTB and start the kernel:

    • Load .dtb from storage into memory.
    • Start kernel using the memory address of the loaded DT.

What's next?

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, how to compile, verify, and optimize your DTO, and how to use multiple DTs. You can also get details on DTO syntax and required DTO and DTBO partition formatting.