Device Tree Compilation, Partitioning, and Runtime Matching Process in Android

This article introduces the Device Tree matching process from two perspectives: compilation & partitioning, and runtime.

1. Compilation and Partitioning

1) Terminology

DTS (DeviceTree Source) refers to the *.dts and *.dtsi files that are edited. The specification can be found at https://www.devicetree.org/specifications/.

DTB (DeviceTree Blob) is the binary file generated by compiling DTS.

DTC (DeviceTree Compiler) is the tool used to compile DTS into DTB.

The variable DTC_EXT can be set to point to an external DTC binary; if not set, the default path is obj/KERNEL_OBJ/scripts/dtc/dtc . Some platforms define it as out/host/linux-x86/bin/dtc .

2) DTS and Partition Changes

Android 8 and earlier : Platform‑related DTS and ODM/OEM‑specific DTS are placed in a single DTS file. The compiled output dtb.img is packaged into boot.img .

If multiple hardware variants need to be supported, several *.dtb files are built and the bootloader selects the appropriate one.

Android 8 and later (DTO introduced) : DTS is split into two parts. The platform‑related part is still compiled into dtb.img and packaged into boot.img . The ODM/OEM‑specific part is compiled into a separate dtbo partition.

Android 11 (kernel 5.4+) : Due to GKI constraints, dtb.img is no longer packaged into boot.img ; it is placed in vendor_boot.img . The bootloader must use BOARD_BOOT_HEADER_VERSION=3 to load it.

3) DTB Generation

If a DTS needs to use configuration macros, include the generated header <generated/autoconf.h> . Additional external macros can be passed to the compiler via -DXXX using the dtc_cpp_flag variable.

The variable DTC_FLAG is used by the DTC; it can enable specific flags for individual DTB files, e.g.:

obj-y += a.dtb
makefile DTC_FLAG_a

The hidden command file .a.dtb.cmd under the out directory contains the exact build command for a.dtb .

Vendor‑specific DTB Specification

1) vendor1

Makefile entries:

dtbo-y+= board1.dtbo
board1.dtbo-base := soc.dtb

dtbo-y+= board2.dtbo
board2.dtbo-base := soc.dtb

A new makefile scripts/Makefile.dtbo is added.

2) vendor2

Configuration flags:

CONFIG_BUILD_ARM64_APPENDED_DTB_IMAGE=y
CONFIG_BUILD_ARM64_DTB_OVERLAY_IMAGE=y
CONFIG_BUILD_ARM64_APPENDED_DTB_IMAGE_NAMES="soc"
CONFIG_BUILD_ARM64_DTB_OVERLAY_IMAGE_NAMES="board1board2"

2. Runtime

Vendor1

(1) XBL : The Configuration Data Table (CDT) defines platform_id and platform_subtype arrays, compiled into xbl.elf or a separate cdt.bin . Different projects generate different cdt.bin files, allowing the bootloader to select the appropriate DTS.

Relevant source file: boot_images\qcompkg\xblloader\Boot_config_flash.c . The function boot_update_config_data_table() decides whether to use cdt.bin or xbl.elf data and passes platform information to ABL via shared memory.

(2) ABL : The function DTBImgCheckAndAppendDT() in bootable/bootloader/edk2/QcomModulePkg/Library/BootLib/BootLinux.c checks the header version (must be 3) and retrieves dtb.img from vendor_boot .

Another file bootable/bootloader/edk2/QcomModulePkg/Library/BootLib/LocateDeviceTree.c reads properties qcom,msm-id , qcom,board-id , qcom,pmic-id from the SOC DTB and selects the most matching one. It then reads the same properties (plus DDR info) from the board DTBO to choose a matching board configuration.

The selected SOC DTB and board DTBs are merged with ufdt_apply_multi_overlay() and the resulting address is passed to the kernel via register R2 .

Vendor2

Similar to vendor1, but the selection of a board DTBO is performed in the LK stage using GPIO or other runtime information via rsc_get_dtbo_index() . The rsc mechanism stands for Run‑time Switchable Configuration.

Vendor2 must implement customized_get_odm_mdtbo_index() to choose the appropriate DTBO. The index corresponds to the list defined by CONFIG_BUILD_ARM64_DTB_OVERLAY_IMAGE_NAMES in the kernel.

Reference

https://source.android.google.cn/devices/architecture/dto