Starting March 27, 2025, we recommend using android-latest-release instead of aosp-main to build and contribute to AOSP. For more information, see Changes to AOSP.

Deploy GBL

This page explains how to deploy the GBL binary.

Boot firmware requirements

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

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 aspects of Android Verified Boot (AVB), ensuring only authenticated images are loaded.
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.
Compatibility and backward compatibility. The firmware should work on devices with different vendor, SOCs, and maintain backward compatibility with the corresponding Android version.

Boot firmware support

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

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 EFI 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-signed version of GBL and integrate it into your boot chain.

Build and run the GBL

To build and run the 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 EFI app:

./tools/bazel run //bootable/libbootloader:gbl_efi_dist --extra_toolchains=@gbl//toolchain:all

Run the EFI app within Cuttlefish:
```
cvd start --android_efi_loader=path_to_the_EFI_app ...
```
Instead of booting Android directly, this cvd start command uses the EFI 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.