Recovery images

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
10 (Q)	non-A/B	N/A	2	0, 1, 2	Yes
9 (P)	A/B	N/A	1	0, 1	No
9 (P)	non-A/B	N/A	1	0, 1	Yes
8 (O)	A/B	N/A	N/A (considered 0)	N/A (considered 0)	No
8 (O)	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 and dtbo) 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 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 recovery_dtbo argument of the mkbootimg 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 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 recovery_acpio argument of the mkbootimg 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.