1# A/B Boot Flow in GBL 2 3This document explains the A/B boot flows implemented by GBL and its 4interaction with EFI protocol 5[GBL_EFI_AB_SLOT_PROTOCOL](./gbl_efi_ab_slot_protocol.md). 6 7| **Status** | Work in progress | 8|:------------|-----------------:| 9| **Created** | 2024-12-3 | 10 11## Android 12 13For Android, GBL supports the following two configurations of A/B boot: 14 151. Slotless bootloader + A/B Android. 161. A/B bootloader + A/B Android. 17 18At run time, GBL detects the configuration by checking the return value of 19[GBL_EFI_AB_SLOT_PROTOCOL.GetCurrentSlot()](./gbl_efi_ab_slot_protocol.md#gbl_efi_ab_slot_protocolgetcurrentslot). 20If the return is error `EFI_UNSUPPORTED`, GBL considers bootloader to be 21slotless and proceeds with the 22[Slotless bootloader + A/B Android](#slotless-bootloader--ab-android) boot 23flow. Otherwise it proceeds with the 24[A/B/ bootloader + A/B Android](#ab-bootloader--ab-android) boot flow. 25 26Note: The boot flow supports >2 slots. We use A/B simply as an example for 27illustration. 28 29### Slotless Bootloader + A/B Android 30 31#### Platform Setup 32 33This configuration corresponds to the following platform setup. 34 35 36 37Device has a single slot GBL bootloader and A/B slot Android OS. Vendor 38firmware hands off to the single GBL slot which then make A/B decision for 39Android OS. 40 41#### Boot Flow 42 43The boot flow is summarized in the following diagram 44 45 46 47GBL will make exactly one call to 48[GBL_EFI_AB_SLOT_PROTOCOL.GetNextSlot()](./gbl_efi_ab_slot_protocol.md) 49with boolean argument `mark_boot_attempt` set to true for getting the target 50slot to boot. When Vendor UEFI firmware sees `mark_boot_attempt=true`, it 51should update slot metadata such as derementing retry counter. If the slot is 52loaded and verified successfully, GBL proceeds to boot the slot. Otherwise it 53triggers a reboot. 54 55### A/B Bootloader + A/B Android 56 57#### Platform Setup 58 59This configuration corresponds to the following platform setup. 60 61 62 63Device has A/B GBL bootloader and A/B Android OS. Vendor firmware makes A/B 64slot decision and boots to the correponding GBL slot. GBL simply continues to 65boot the same Android OS slot. 66 67#### Boot Flow 68 69The boot flow is summarized in the following diagram. 70 71 72 73GBL queries the current bootloader slot by calling 74[GBL_EFI_AB_SLOT_PROTOCOL.GetCurrentSlot()](./gbl_efi_ab_slot_protocol.md#gbl_efi_ab_slot_protocolgetcurrentslot). 75It also tracks whether 76[GBL_EFI_AB_SLOT_PROTOCOL.SetActiveSlot()](./gbl_efi_ab_slot_protocol.md#gbl_efi_ab_slot_protocolsetactiveslot) 77has been called to change the next active slot to a different slot, i.e. by 78`fastboot set_active`. If it has, GBL considers that the user intends to boot 79to a different slot than the current one and will trigger a reboot. If not, GBL 80proceeds to load and verify the same slot Android OS. If all operations are 81successful, GBL boots from it. Otherwise it triggers a reboot. Note that in 82this flow, vendor firmware is responsible for updating slot metadata such as 83decrementing retry counters before booting GBL. 84
