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
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 |
.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.
