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 |
---|---|---|---|---|---|
11 | A/B, Virtual A/B |
Yes | 3* | N/A | No |
A/B, Virtual A/B |
No | 2, 3 | 0, 1, 2, 3 | No | |
non-A/B | Yes | 3 | N/A | Yes | |
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 |
non-A/B | N/A | 1 | 0, 1 | Yes | |
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 running Android 11 or higher and using the Generic Kernel Image (GKI) must use a primary boot header version of 3 to be compatible with the vendor boot partition.
Key points:
A/B devices don't need to specify a recovery image as A/B updates use two sets of partitions (including
boot
anddtbo
) and switch between them during updates, removing the need for a recovery image. 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 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 = (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 or ACPIO (o pages) | o = (recovery_[dtbo|acpio]_size + page_size -
1) / page_size |
For details on the mkbootimg
tool arguments for specifying the boot image
header version and overlay image paths, see Boot Image Header
Versioning.
Implement DTBO
Non-A/B devices running 9 or higher can 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
totrue
: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 therecovery_dtbo
argument of themkbootimg
tool during the creation of recovery image.
If the BOARD_INCLUDE_RECOVERY_DTBO
, BOARD_MKBOOTIMG_ARGS
, and
BOARD_PREBUILT_DTBOIMAGE
variables are set correctly, the Android build system
includes the DTBO specified by the BOARD_PREBUILT_DTBOIMAGE
variable in
recovery.img
.
Implement ACPIO
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
device BoardConfig.mk
:
Set the config
BOARD_INCLUDE_RECOVERY_ACPIO
totrue
: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 therecovery_acpio
argument of themkbootimg
tool during the creation of the recovery image.
If the BOARD_INCLUDE_RECOVERY_ACPIO
, BOARD_MKBOOTIMG_ARGS
, and
BOARD_RECOVERY_ACPIO
variables are set correctly, the Android build system
includes the ACPIO specified by the BOARD_RECOVERY_ACPIO
variable in
recovery.img
.