Implementing DTOs

Implementing DTO involves dividing the device tree, building, partitioning, and running. After you have a working implementation, you must also maintain compatibility between the two DTs and determine a strategy for ensuring the security of each DT partition.

Dividing the DT

Start by dividing the device tree into two (2) parts:

  • Main DT. The SoC-only part and the default configurations, provided by SoC vendor.
  • Overlay DT. The device-specific configurations, provided by ODM/OEM.

After dividing the device trees, you must ensure compatibility between main DT and overlay DT so that merging main DT and overlay DT results in a complete DT for the device. For details on DTO format and rules, see DTO Syntax. For details on multiple device trees, see Multiple DTs.

Building main & overlay DTs

To build the main DT:

  1. Compile main DT .dts into .dtb file.
  2. Flash .dtb file into a bootloader runtime-accessible partition (detailed below).

To build the overlay DT:

  1. Compile overlay DT .dts into .dtbo file. While this file format is the same as the .dtb file formatted as a flattened device tree, the different file extension distinguishes it from the main DT.
  2. Flash .dtbo file into a bootloader runtime-accessible partition (as detailed below).

For details on compiling with DTC and verifying DTO results on the host, see Compiling & Verifying.

Partitioning DTs

Determine a bootloader runtime-accessible and trusted location in flash memory to put .dtb and .dtbo.

Example locations for the main DT:

  • Part of boot partition, appended to the kernel (image.gz).
  • Separate DT blobs (.dtb) in dedicated partition (dtb).

Example locations for the overlay DT:

Unique Partition
Figure 1. Put .dtbo into a unique partition, e.g. dtbo partition.
ODM Partition
Figure 2. Put .dtbo into odm partition (do this only if your bootloader has capability to load data from the filesystem of odm partition).

Note: The size of the overlay DT partition depends on the device and the amount of changes needed on top of the main DT blob. Typically, 8 MB is more than enough and allows room to grow in the future if required.

For devices that support seamless (A/B) updates, A/B the main DT and overlay DT partitions:

Example 1
Figure 3. DTBO partition A/B, example 1.
Example 2
Figure 4. DTBO partition A/B, example 2.

Running in bootloader

To run:

Figure 5. Typical runtime implementation for device tree overlay in bootloader.
  1. Load .dtb from storage into memory.
  2. Load .dtbo from storage into memory.
  3. Overlay .dtb with .dtbo to be a merged DT.
  4. Start kernel given the memory address of the merged DT.

Maintaining compatibility

The main DTB (from SoC vendor) is treated as an API surface for DTBOs. After separating the device tree into a SoC-common part and a device-specific part, you must keep the two parts mutually compatible in the future, including:

  • DT definition in main DT (e.g. nodes, properties, labels). Any definition change in main DT could trigger changes in overlay DT. For example, to correct a node name in main DT, define an "alias" label that maps to the original node name (to avoid the change of overlay DT).
  • Overlay DT store location (e.g. partition name, store format).

Ensuring security

Bootloader must ensure the DTB/DTBO is secure, unmodified, and uncorrupted. You could use any solution to secure DTB/DTBO, for example, Boot image signature in VBoot 1.0 or AVB HASH footer (VBoot 2.0).

  • If DTB/DTBO is in a unique partition, you can add that partition to the trust chain of AVB. The trust chain starts from a hardware-protected root of trust and goes to the bootloader, which verifies the integrity and authenticity of DTB/DTBO partition.
  • If DTB/DTBO is in an existing partition (such as the odm partition), that partition should be in the trust chain of AVB. (DTBO partition could share a public key with odm partition).

For details, refer to Verified Boot.