EFI stub and boot partitions - Qualcomm Dragonwing Documentation

Qualcomm^® Linux boots without a conventional second-stage boot loader. The kernel itself is compiled as an EFI application using the EFI boot stub, and the UEFI firmware (or systemd-boot) executes it directly from the EFI System Partition (ESP).

Qualcomm Linux kernel as the EFI stub

The EFI boot stub is a thin shim built into the kernel image (drivers/firmware/efi/libstub/) that satisfies the EFI application entry point contract. When CONFIG_EFI_STUB=y is set, the kernel image is formatted as a Portable Executable / Common Object File Format (PE/COFF) binary so that UEFI firmware can load and execute it directly. On AArch64, compressed kernel support (zImage) is not available. The kernel image therefore ships as an uncompressed Image binary wrapped in the PE/COFF container with the EFI stub linked in. Verify the configuration in the active defconfig or a running system:

# From kernel source
grep CONFIG_EFI_STUB arch/arm64/configs/defconfig

# On target
zcat /proc/config.gz | grep CONFIG_EFI_STUB
# Expected: CONFIG_EFI_STUB=y

For the upstream EFI stub documentation, see The EFI Boot Stub.

EFI System Partition (ESP) layout

The ESP is a FAT32-formatted partition that UEFI firmware and systemd-boot use as the shared storage for boot components. On Qualcomm Linux devices it is accessible as the efi partition (partition label) and its contents are packaged into the efi.bin flashable image during the Yocto build.

Directory structure

ESP/
├── EFI/
│   ├── BOOT/
│   │   └── BOOTAA64.EFI          ← systemd-boot (default UEFI removable-media path)
│   └── Linux/
│       ├── linux.efi             ← Standard kernel UKI (Type 2 boot entry)
│       └── linux-rt.efi          ← Real-time kernel UKI (present when RT image built)
└── loader/
    ├── loader.conf               ← systemd-boot global configuration
    └── entries/                  ← Type 1 drop-in entries (unused by default)

Path	Description
`EFI/BOOT/BOOTAA64.EFI`	The UEFI default boot application for AArch64. UEFI firmware runs this when no explicit boot entry is configured. On Qualcomm Linux this is a copy of `systemd-boot.efi`.
`EFI/Linux/*.efi`	Unified kernel image(s). systemd-boot enumerates all `.efi` files in this directory as boot entries.
`loader/loader.conf`	Controls systemd-boot timeout and default entry policy.
`loader/entries/`	Optional Type 1 drop-in `.conf` entries. Not populated by default on Qualcomm Linux.

FAT32 requirements

The UEFI specification requires the ESP to be formatted with FAT32 (or FAT12/16 for smaller partitions). The Yocto esp-qcom-image.bb recipe creates the efi.bin image with the correct FAT32 parameters. Do not reformat the efi partition with a different file system else UEFI firmware will fail to mount it.

Unified kernel image (UKI) structure

A UKI is a PE/COFF binary with additional EFI sections that carry the boot payload. The sections embedded by ukify in the Qualcomm Linux build are:

PE section	Contents
`.linux`	The uncompressed kernel `Image` binary
`.initrd`	The initramfs CPIO archive (gzip or lz4 compressed)
`.cmdline`	Kernel command-line string baked in at build time
`.dtbauto`	(Optional) Device tree blob; DTBs are normally in `dtb.bin` on a separate partition
`.osrel`	`os-release` metadata identifying the distribution and kernel version

The Qualcomm Linux UKI stores the kernel command line in .cmdline, which means the command line is fixed at image build time. To change kernel parameters you must rebuild efi.bin. For runtime overrides during development, see the efi-bin-append-update-kernel-cmdline-params skill documentation.

DTB partition image (dtb.bin)

Device tree blobs are maintained in a separate partition (dtb_a) rather than embedded in the UKI. This allows DTB updates (for example, adding a new board overlay) without rebuilding the kernel image. The Yocto build compiles all device trees listed in KERNEL_DEVICETREE and packages them into dtb.bin which is a FIT image that UEFI firmware interrogates to select the correct DTB for the detected hardware. The FIT-based selection mechanism is described in Device tree architecture.

Build artifacts summary

The following table maps each boot-relevant artifact to its partition and role:

File	Partition	Contains
`efi.bin`	`efi`	FAT32 ESP image: systemd-boot + UKI(s) in `EFI/Linux/`
`dtb.bin`	`dtb_a`	FIT image of compiled DTB / DTBO files
`vmlinux`	Build artifact	Unstripped ELF kernel image with debug symbols
`Image`	Embedded in UKI	Raw AArch64 kernel binary
`initramfs-*.cpio.gz`	Embedded in UKI	Early userspace file system

Updating the ESP after a kernel change

After modifying the kernel source, configuration, or device tree, rebuild and reflash both efi.bin and dtb.bin:

# 1. Rebuild inside the kas shell
kas shell meta-qcom/ci/<board>.yml:meta-qcom/ci/qcom-distro.yml
bitbake qcom-multimedia-image

# 2. Navigate to the deploy directory
cd build/tmp/deploy/images/<Machine>/<Image>-*.rootfs.qcomflash/

# 3. Flash both partitions
fastboot flash efi efi.bin
fastboot flash dtb_a dtb.bin
fastboot reboot

Always flash efi.bin and dtb.bin together after a kernel or DTS change. Flashing only one can leave the kernel and device tree out of sync, causing boot failures.

​Qualcomm Linux kernel as the EFI stub

​EFI System Partition (ESP) layout

​Directory structure

​FAT32 requirements

​Unified kernel image (UKI) structure

​DTB partition image (dtb.bin)

​Build artifacts summary

​Updating the ESP after a kernel change

Qualcomm Linux kernel as the EFI stub

EFI System Partition (ESP) layout

Directory structure

FAT32 requirements

Unified kernel image (UKI) structure

DTB partition image (dtb.bin)

Build artifacts summary

Updating the ESP after a kernel change