On non-A/B devices, the recovery image should contain information from a device tree blob (DTB) or Advanced Configuration and Power Interface (ACPI) overlay image. When such devices boot into recovery, the bootloader can then load the overlay image that is compatible with the recovery image. Devices that support A/B (seamless) updates should use recovery as boot instead of a separate recovery partition (for details, see Implementing A/B Updates).
The options for including a recovery DTBO/ACPIO as part of the boot/recovery image differ between Android releases.
|Release||Update scheme||GKI compliance||Boot header version (launching devices)||Boot header version (upgrading devices)||Dedicated recovery image required|
|No||2, 3||0, 1, 2, 3||No|
|non-A/B||No||2, 3||0, 1, 2, 3||Yes|
|10 (Q)||A/B||N/A||2||0, 1, 2||No|
|non-A/B||N/A||2||0, 1, 2||Yes|
|9 (P)||A/B||N/A||1||0, 1||No|
|8 (O)||A/B||N/A||N/A (considered 0)||N/A (considered 0)||No|
|non-A/B||N/A||N/A (considered 0)||N/A (considered 0)||Yes|
A/B devices don't need to specify a recovery image as A/B updates use two sets of partitions (including
dtbo) and switch between them during updates, removing the need for a recovery image. If desired, A/B devices can still use a dedicated recovery image.
Non-A/B devices launching with Android 11 or higher and using a boot header version of 3 must explicitly specify a boot header version of 2 of 2 for the recovery image separately. For example:
BOARD_RECOVERY_MKBOOTIMG_ARGS := --header_version 2
For architectures that don't support device trees, the recovery image can include an ACPIO image instead of a DTBO image.
About OTA failures and recovery images
To prevent over-the-air (OTA) failures on non-A/B devices, the recovery image should be self-sufficient and independent of other images. 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 recovery from depending on the DTBO/ACPIO partition during an update, non-A/B devices running Android 9 or higher can specify a recovery DTBO/ACPIO image containing information from the overlay image as a separate section in the boot image format (must use a boot header version of 1 or 2).
Boot image changes
To allow the recovery image to contain the recovery DTBO or ACPIO on non-A/B devices running Android 9 or higher, update the boot image structure as follows.
|Boot image section||Number of pages|
|Boot header (1 page)||1|
|Kernel (l pages)||l = (
|Ramdisk (m pages)||m = (
|Second stage bootloader (n pages)||n = (
|Recovery DTBO or ACPIO (o pages)||o = (
For details on the
mkbootimg tool arguments for specifying the boot image
header version and overlay image paths, see Boot Image Header
Non-A/B devices running 9 or higher can populate the
recovery_dtbo section of the recovery image. To include the
recovery.img, in the device
Set the config
BOARD_INCLUDE_RECOVERY_DTBO := true
BOARD_MKBOOTIMG_ARGSvariable 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_DTBOIMAGEvariable is set to the path of the DTBO image. The Android build system uses the variable to set the
recovery_dtboargument of the
mkbootimgtool during the creation of recovery image.
BOARD_PREBUILT_DTBOIMAGE variables are set correctly, the Android build system
includes the DTBO specified by the
BOARD_PREBUILT_DTBOIMAGE variable in
Non-A/B devices running Android 9 or higher can use
an ACPIO overlay image (instead of a DTBO image) and can populate the
recovery_acpio section (instead of the
recovery_dtbo section) of the
recovery image. To include the
recovery_acpio image in
recovery.img, in the
Set the config
BOARD_INCLUDE_RECOVERY_ACPIO := true
BOARD_MKBOOTIMG_ARGSvariable 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_ACPIOvariable is set to the path of the ACPIO image. The Android build system uses the variable to set the
recovery_acpioargument of the
mkbootimgtool during the creation of the recovery image.
BOARD_RECOVERY_ACPIO variables are set correctly, the Android build system
includes the ACPIO specified by the
BOARD_RECOVERY_ACPIO variable in