Recovery Images for Non-A/B Devices

To prevent over-the-air (OTA) failures on non-A/B devices, the recovery partition must be self-sufficient and can't depend on other partitions. Device manufacturers can use DeviceTree or Advanced Configuration and Power Interface (ACPI) to describe all nondiscoverable devices.

While booting into recovery, the bootloader must load the Device Tree Blob for Overlay (DTBO) or Advanced Configuration and Power Interface for Overlay (ACPIO) image (overlay image) that is compatible with the recovery image. During an OTA update, if a problem occurs after the overlay image has been updated (but prior to completing the full update), the device tries to boot into recovery mode to complete the OTA update. However, because the overlay partition has already been updated, a mismatch could occur with the recovery image (which hasn't been updated yet).

To prevent this situation, in Android 9 and higher the recovery image must also contain information from the overlay image. The recovery image for a non-A/B device must also contain the device's overlay blob appended to kernel so it doesn't depend on the overlay partition during an update.

Android 10 and higher includes support for architectures that use ACPI instead of DTBO.

Boot image changes

To allow the recovery image to contain the recovery DTBO or ACPIO, the format of the boot image in Android 9 and higher 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 arguments to support these overlays.

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.
recovery_acpio Path to the recovery ACPIO image.

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

DTBO implementation

Although all devices launching with Android 9 and higher 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 that 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 the 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.

ACPIO implementation

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

  • Set the config BOARD_INCLUDE_RECOVERY_ACPIO to true:
    BOARD_INCLUDE_RECOVERY_ACPIO := true
  • Extend the BOARD_MKBOOTIMG_ARGS variable to specify the boot image header version. The variable must be greater than or equal to 1 to support recovery ACPIO.
    BOARD_MKBOOTIMG_ARGS += --header_version $(BOARD_BOOTIMG_HEADER_VERSION)
  • Ensure that the BOARD_RECOVERY_ACPIO variable is set to the path of the ACPIO image. The Android build system uses the variable to set the argument recovery_acpio of the mkbootimg tool during the creation of the recovery image.
  • If the variables BOARD_INCLUDE_RECOVERY_ACPIO, BOARD_MKBOOTIMG_ARGS, and BOARD_RECOVERY_ACPIO are set correctly, the Android build system uses the ACPIO specified by the variable BOARD_RECOVERY_ACPIO to include in recovery.img.

Validation

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