Implement OTA updates

To implement the over-the-air (OTA) updates, the bootloader must be able to access a recovery RAM disk during boot. If the device uses an unmodified AOSP recovery image, the bootloader reads the first 32 bytes on the misc partition; if the data there matches boot-recovery, the bootloader boots into the recovery image. This method enables any pending recovery work (for example, applying an OTA or removing data) to continue to completion.

For details on the content of a block in flash used for communications by recovery and the bootloader, refer to bootable/recovery/bootloader_message/bootloader_message.h.

Devices with A/B updates

To support OTA updates on devices that use A/B updates, ensure that the device bootloader meets the following criteria.

General criteria

  • All partitions updated through an OTA should be updatable while the main system is booted (and not updated in recovery).

  • To boot the system partition, the bootloader passes the following value on kernel command line: ro root=/dev/[node] rootwait init=/init.

  • It's the responsibility of the Android framework to call markBootSuccessful from the HAL. The bootloader should never mark a partition as successfully booted.

Support for boot control HAL

The bootloader must support the boot_control HAL as defined in hardware/libhardware/include/hardware/boot_control.h. The updater queries the boot control HAL, updates the boot slot not in use, changes the active slot using the HAL, and reboots into the updated operating system. For details, see Implementing the boot control HAL.

Support for slots

The bootloader must support functionality related to partitions and slots, including:

  • Partition names must include a suffix that identifies which partitions belong to a particular slot in the bootloader. For each such partition, there's a corresponding variable has-slot:partition base name with a value of yes. Slots are named alphabetically as a, b, c, etc. corresponding to partitions with the suffix _a, _b, _c, etc. The bootloader should inform the operating system which slot was booted using the command line property androidboot.slot_suffix. This property is set through bootconfig for devices launching with Android 12 or higher.

  • The slot-retry-count value is reset to a positive value (usually 3), either by the boot control HAL through the setActiveBootSlot callback or through the fastboot set_active command. When modifying a partition that's part of a slot, the bootloader clears "successfully booted" and resets the retry count for the slot.

The bootloader should also determine which slot to load. The figure shows an example decision process.

Bootloader slotting flow
Figure 1. Bootloader slotting flow

  1. Determine which slot to attempt. Don't attempt to load a slot marked slot-unbootable. This slot should be consistent with the values returned by fastboot, and is referred to as the current slot.

  2. If the current slot isn't marked as slot-successful and has a slot-retry-count = 0, mark the current slot as slot-unbootable. Then select a different slot that is not marked unbootable and is marked as slot-successful; this slot is now the selected slot. If no current slot is available, boot to recovery or display a meaningful error message to the user.

  3. Select the appropriate boot.img and include the path to correct system partition on the kernel command line.

  4. Populate the kernel command line slot_suffix parameter.

  5. Boot. If not marked slot-successful, decrement slot-retry-count.

The fastboot utility determines which partition to flash when running any flash commands. For example, running the fastboot flash system system.img command first queries the current-slot variable then concatenates the result to system to generate the name of the partition that should be flashed (system_a, system_b, etc.).

When setting the current slot using the fastboot set_active command or the boot control HAL setActiveBootSlot command, the bootloader should update the current slot, clear slot-unbootable and slot-successful, and reset the retry count (this is the only way to clear slot-unbootable).

Devices without A/B updates

To support OTA updates on devices that don't use A/B updates (see Non-A/B updatable devices), ensure that the device bootloader meets the following criteria.

  • The recovery partition should contain an image that is capable of reading a system image from some supported partition (cache, userdata) and writing it to the system partition.

  • The bootloader should support booting directly into recovery mode.

  • If radio image updates are supported, the recovery partition should also be able to flash the radio. This can be accomplished in one of two ways:

    • The bootloader flashes the radio. In this case, it should be possible to reboot from the recovery partition back into the bootloader to complete the update.

    • The recovery image flashes the radio. This functionality can be provided as a binary library or utility.