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.