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 device tree blob (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.

DTBO Device Tree Blob for Overlay

Updates in Android 9 Release

In Android 9, the bootloader must not modify the properties defined in the device tree overlays before passing the unified device tree blob to the kernel.

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 create and flash the device tree blob:

    1a. Use the device tree compiler (dtc>) to compile device tree source (.dts) into a device tree blob (.dtb). The device tree blob is formatted as a flattened device tree. 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:

    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 load the device tree blob and start the kernel:

    3a. Load .dtb from storage into memory. 3b. 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/DTBO partition formatting.