DTB images

Android implementations can include a device tree blob (DTB) image for use by the bootloader. The location of the DTB image (and the options for specifying DTB image parameters) differs between Android releases.

In Android 11, devices using the Generic Kernel Image (GKI) must support the vendor boot partition, which includes all vendor-specific information that was relocated from the boot partition. Because the DTB image contains vendor-specific data, it's now part of the vendor boot partition. To specify DTB image parameters, see Vendor boot header.
In Android 10, devices can include the DTB image in the boot partition. To specify DTB image parameters, see Including the DTB image in the boot image.
In Android 9 and lower, the DTB image can exist in its own partition or be appended to the kernel image.gz to create the kernel + DTB image (which is then passed to mkbootimg to create boot.img).

DTB image format

In Android 10 and higher, the DTB image must use one of the following formats:

DT blobs concatenated one after the other. The bootloader uses the totalsize field in each FDT header to read and parse the corresponding blob.
DTB/DTBO partitions. The bootloader has an efficient way to select the correct DT blob by examining the dt_table_entry struct (contains id, rev, and custom fields) that can hold hardware identifying information for the entry. For details, see DTB/DTBO Partitions.

Include the DTB image in the boot image

Devices running Android 10 can include the DTB image in the boot image. This removes the need for Android to support scripts that append the DTB image to image.gz in the kernel, and enables the use of Vendor Test Suite (VTS) test to verify (and standardize) DTB placement.

In addition, for non-A/B devices, it's safer to have the DTB as part of the recovery image rather than in a separate partition to prevent issues caused by interrupted OTAs. During an OTA, if a problem occurs after the DTB partition is updated (but prior to completing the full update), the device tries to boot into recovery mode to complete the OTA; however, because the DTB partition has already been updated, a mismatch could occur with the recovery image (which has not yet been updated). Having the DTB image as part of the boot image format prevents such issues by making the recovery image self sufficient (that is, it doesn't depend on another partition).

Boot image structure

Devices running Android 10 can include a DTB image using the following boot image structure.

Boot image section	Number of pages
Boot header (1 page)	1
Kernel (l pages)	l = (`kernel_size` + `page_size` - 1) / `page_size`
Ramdisk (m pages)	m = (`ramdisk_size` + `page_size` - 1) / `page_size`
Second stage bootloader (n pages)	n = (`second_size` + `page_size` - 1) / `page_size`
Recovery DTBO (o pages)	o = (`recovery_dtbo_size` + `page_size` - 1) / `page_size`
DTB (p pages)	p = (`dtb_size` + `page_size` - 1) / `page_size`

DTB image path

For devices running Android 10, you can use the mkbootimg.py tool and the following arguments to specify the path to the DTB image.

Argument	Description
`dtb`	Path to the DTB image to be included in the boot/recovery images.
`dtb_offset`	When added to the `base` argument, provides the physical load address for the final device tree. For example, if the `base` argument is `0x10000000` and the `dtb_offset` argument is `0x01000000`, the `dtb_addr_field` in the boot image header is populated as `0x11000000`.

The board config variable BOARD_PREBUILT_DTBIMAGE_DIR must be used to specify the path to the DTB image. If more than one file with extension *.dtb is present in the directory BOARD_PREBUILT_DTBIMAGE_DIR, the Android build system concatenates the files to create the final DTB image used in the boot image creation.

To pass the argument dtb to mkbootimg.py with the DTB image from the directory specified by BOARD_PREBUILT_DTBIMAGE_DIR, the board config variable BOARD_INCLUDE_DTB_IN_BOOTIMG must be set to true. For example:

BOARD_INCLUDE_DTB_IN_BOOTIMG := true

You can append the dtb_offset argument to the BOARD_MKBOOTIMG_ARGS board config variable with the other offsets and header version. For example:

BOARD_MKBOOTIMG_ARGS := --ramdisk_offset $(BOARD_RAMDISK_OFFSET) --dtb_offset $(BOARD_DTB_OFFSET) --tags_offset $(BOARD_KERNEL_TAGS_OFFSET) --header_version $(BOARD_BOOTIMG_HEADER_VERSION)

Bootloader support

For VTS to run successfully on devices running Android 10, the bootloader must support the updated boot image and must add the androidboot.dtb_idx kernel command line parameter to indicate the index of the selected device tree (DT). You can specify only one (1) index. For example, the parameter androidboot.dtb_idx=N reports N as the zero-based index of the device tree selected by the bootloader from the set of DTBs present in the boot image.