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:
- Compile main DT
.dtbfile into a bootloader runtime-accessible partition (detailed below).
To build the overlay DT:
- Compile overlay DT
.dtbofile. While this file format is the same as the
.dtbfile formatted as a flattened device tree, the different file extension distinguishes it from the main DT.
.dtbofile 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.
Determine a bootloader runtime-accessible and trusted location in flash
memory to put
Example locations for the main DT:
- Part of boot partition, appended to the kernel (
- Separate DT blobs (
.dtb) in dedicated partition (
Example locations for the overlay DT:
odmpartition (do this only if your bootloader has capability to load data from the filesystem of
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:
Running in bootloader
.dtbfrom storage into memory.
.dtbofrom storage into memory.
.dtboto be a merged DT.
- Start kernel given the memory address of the merged DT.
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).
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
odmpartition), that partition should be in the trust chain of AVB. (DTBO partition could share a public key with
For details, refer to Verified Boot.