Effective in 2026, to align with our trunk stable development model and ensure platform stability for the ecosystem, we will publish source code to AOSP in Q2 and Q4. For building and contributing to AOSP, we recommend utilizing android-latest-release instead of aosp-main. The android-latest-release manifest branch will always reference the most recent release pushed to AOSP. For more information, see Changes to AOSP.

Deploy GBL

This page explains how to deploy the Generic Bootloader (GBL) binary.

Boot firmware requirements

To use GBL, the boot firmware must meet the following requirements:

Unified Extensible Firmware Interface (UEFI) compliance. The firmware must implement and use the required UEFI protocols. The firmware must also allow for vendor-specific extensions using defined UEFI protocols.
Security. The firmware must implement all requirements for Android Verified Boot (AVB), enabling GBL to authenticate boot images.
Boot modes. The binary should be able to handle various boot modes, such as normal boot, recovery boot, and fastboot.
Dynamic partitioning. The boot firmware must implement slot selection logic so that it supports reading the correct A/B boot slot and is compatible with dynamic partitions and userdata in super.
OS configuration. The firmware must be capable of modifying the kernel command line, device tree (DTB), and bootconfig with OEM customizations needed to boot the device.
Protected VM loading. The binary should correctly load preverified protected VM firmware before the Android kernel in the presence of protected VMs. For further information, see Microdroid boot sequence.
Memory management. The boot firmware must support the UEFI memory allocation API.

Implementation requirements

For GBL to be correctly implemented on your device, you must meet the following requirements:

Your device must contain two FAT32 partitions that are 4 MB (or larger) named android_esp_a and android_esp_b on a block device accessible by the SOC.
- A block device is a storage device that can be read from or written to in units of blocks. Examples include UFS, eMMC, and SD card devices.
- FAT32 is used because it's a ubiquitous and straightforward file system.
- Both partitions are required for over-the-air (OTA) updates and rollbacks for the duration of this Android version's support window.
- GBL is approximately 2 MB uncompressed. 4 MB is sufficient to account for any growth due to additional features over the next seven years.
- In the event of a GBL update, you must update the entire android_esp_${SLOT_SUFFIX} partition. A GBL-only update isn't supported by Android OTA.
Note: We might require major updates to GBL for critical functionality.
The version of GBL deployed must be the latest certified production build from the corresponding GBL release branch. We recommend that you sign the Google-certified copy of GBL using your preferred signing solution and store the resulting build and signature metadata inside the android_esp_${SLOT_SUFFIX} partition.
- The GBL certificate MUST be left intact by the OEM signature AND there must be no header applied to the binary.
- The developer GBL build is used strictly for development and debug purposes. The build can't be shipped and won't be certified by Google.
GBL must be stored at the path /EFI/BOOT/BOOTAA64.EFI within the FAT32 partition.
Implement the required UEFI and Android UEFI protocols to support GBL. The production build of GBL fails to boot if these interfaces aren't supported.
- EFI_BLOCK_IO_PROTOCOL or EFI_BLOCK_IO2_PROTOCOL fetches the boot images and pvmfw images from disk
- EFI_RNG_PROTOCOL for stack canaries, KASLR seeds, and RNG seeds
- Memory Allocation Services for allocation of scratch memory to do AVB and DICE computations
- EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL provides an option for no-op implementations, but GBL logs through this protocol by default
- GBL_EFI_AVB_PROTOCOL accesses public keys and rollback indexes to verify boot images
- GBL_EFI_BOOT_CONTROL_PROTOCOL acquires slot metadata and boot reasons from the firmware
- GBL_EFI_AVF_PROTOCOL generates AVF config data from the DICE chain
The UEFI protocols that are strongly recommended when integrating GBL are documented in GBL UEFI Protocols.

Boot firmware support

With the modifications necessary to support requirements in the previous section, the following UEFI firmware implementations work with GBL:

EDK2 (Tianocore). A EDK2 is a popular open-source UEFI implementation. GBL support is needed for EDK2-based bootloaders, and UEFI support is already present.
U-Boot. A flexible and widely used open-source bootloader project that is gaining UEFI compatibility for GBL usage.
LittleKernel (LK). An open-source bootloader used by some vendors.

Run GBL

You can obtain a prebuilt GBL binary to run or build your own and run it.

Obtain and run the GBL binary

GBL is distributed as a single UEFI app binary. You can update this binary independently from the device's base firmware using Android's standard update mechanism.

Beginning with Android 16, if you ship a device based on ARM-64 chipset, we strongly recommend that you deploy the latest Google-certified version of GBL and integrate it into your boot chain.

Build GBL

To build GBL:

Verify that you have the repo tool and Bazel bootstrap installed:
```
sudo apt install repo bazel-bootstrap
```

Initialize your current directory for source control using the uefi-gbl-mainline manifest file:

repo init -u https://android.googlesource.com/kernel/manifest -b uefi-gbl-mainline
repo sync -j16

Build the UEFI app:

tools/bazel run //bootable/libbootloader:gbl_efi_dist

Test GBL on the Android Virtual Device

Run GBL within Cuttlefish:
```
cvd start --android_efi_loader=path_to_the_UEFI_app ...
```
Instead of booting Android directly, this cvd start command uses the UEFI app to boot Android.

File bugs and contact the bootloader team

To report a bug for the GBL, navigate to the Android Generic Bootloader component in Buganizer.

For questions, contact the GBL team, send an email to android-gbl@google.com.