Including DTBO in Recovery for Non-A/B Devices

To prevent OTA failures on non-A/B devices, the recovery partition must be self-sufficient and cannot depend on other partitions.

While booting into recovery, the bootloader must load the DTBO image that is compatible with the recovery image. During an OTA, if a problem occurs after the DTBO image has been updated (but prior to completing the full update), the device will try to boot into recovery mode to complete the OTA. However, because the DTBO partition has already been updated, a mismatch could occur with the recovery image (which has not yet been updated).

To prevent this situation, in Android 9 the recovery image must also contain information from the DTBO image. The recovery image for a non-A/B device must also contain the device's DTB appended to kernel so as to not depend on the DTB partition during an update.

Boot image changes

To allow the recovery image to contain the recovery DTBO, the format of boot image in Android 9 is:

Boot header (1 page)
Kernel (l pages)
Ramdisk (m pages)
Second stage (n pages)
Recovery DTBO (o pages)

In addition, the mkbootimg tool that creates boot images includes the following new arguments:

Argument Description
header_version Sets the boot image header version. A boot image with a header version greater than or equal to 1 supports the recovery DTBO section.
recovery_dtbo Path to the recovery DTBO image.

For details on modifications to the legacy boot image header, refer to Boot Image Header Versioning in Android 9.

Implementation

Although all devices launching with Android 9 must use the new boot image header (version 1), only non-A/B devices are required to populate the recovery_dtbo section of the recovery image. To include the recovery_dtbo image in recovery.img, in the device BoardConfig.mk:

  • Set the config BOARD_INCLUDE_RECOVERY_DTBO to true:
    BOARD_INCLUDE_RECOVERY_DTBO := true
  • Extend the BOARD_MKBOOTIMG_ARGS variable to specify the boot image header version:
          BOARD_MKBOOTIMG_ARGS := --ramdisk_offset $(BOARD_RAMDISK_OFFSET) --tags_offset $(BOARD_KERNEL_TAGS_OFFSET) --header_version $(BOARD_BOOTIMG_HEADER_VERSION)
  • Ensure the BOARD_PREBUILT_DTBOIMAGE variable is set to the path of the DTBO image. The Android build system uses the variable to set the argument recovery_dtbo of mkbootimg tool during the creation of recovery image.
  • If the variables BOARD_INCLUDE_RECOVERY_DTBO, BOARD_MKBOOTIMG_ARGS, and BOARD_PREBUILT_DTBOIMAGE are set correctly, the Android build system uses the DTBO specified by the variable BOARD_PREBUILT_DTBOIMAGE to include in recovery.img.

Validation

For all devices launching with Android 9, the Vendor Test Suite (VTS) checks the format of the boot/recovery image to ensure the boot image header uses version 1.