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.

Develop Android bootloader features

This page describes how to build, run, and develop Android bootloader features on a Cuttlefish device.

AOSP sources

To develop Android bootloader features, use the Cuttlefish configuration of U-boot with Cuttlefish in the latest release branch (android16-release) or on generic system image (GSI) branches for Android 11 or higher. The following are the sources in AOSP:

Manifest for the Cuttlefish configuration of U-boot (u-boot-mainline).
U-boot bootloader source.
x86 Cuttlefish default bootloader.
aarch64 Cuttlefish default bootloader.
QEMU bootloaders (arm, aarch64, x86_64, riscv)

Develop a bootloader

To build, run, and develop bootloader features locally, follow these steps:

Clone the manifest for the Android fork of U-boot:

$ mkdir u-boot-mainline
$ cd u-boot-mainline
$ repo init -u https://android.googlesource.com/kernel/manifest -b u-boot-mainline
$ repo sync -j$(nproc) -q

Build the bootloader target appropriate for your Cuttlefish architecture. For example:
- x86_64
```
$ tools/bazel run //u-boot:crosvm_x86_64_dist
```
- aarch64
```
$ tools/bazel run //u-boot:crosvm_aarch64_dist
```
The resulting bootloader binary (u-boot.bin for arm64 and u-boot.rom for x86_64) is found in $PATH_TO_REPO/out/u-boot-mainline/dist.
Launch the Cuttlefish device with the bootloader. Include the pause_in_bootloader parameter to disable autoboot and let you interact with the bootloader.
```
$ launch_cvd \
    -bootloader /$PATH/$TO/u-boot-mainline/out/u-boot-mainline/dist/u-boot.rom \
    -pause_in_bootloader -console=true
```
Note: If on aarch64, use u-boot.bin instead of u-boot.rom.
To interact with the bootloader, connect to the bootloader console.
```
$ screen ~/cuttlefish_runtime/console
```
When done with bootloader interactions, continue the boot by typing boot into the console.

Test bootloader flow with different kernels

To test the bootloader flow with different kernels or kernel modules, pass in the target artifacts (kernel and kernel modules) using the --kernel_path and --initramfs_path arguments. The assembler repacks the boot images based on the artifacts passed in the arguments.

cvd create \
    -kernel_path=/$PATH/$TO/common-android14-6.1/out/android14-6.1/dist/bzImage \
    -initramfs_path=/$PATH/$TO/common-android14-6.1/out/android14-6.1/dist/initramfs.img

For more information, see Develop Android Kernels.