> ## Documentation Index
> Fetch the complete documentation index at: https://dragonwingdocs.qualcomm.com/llms.txt
> Use this file to discover all available pages before exploring further.
# EFI stub and boot partitions
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:
```bash theme={null}
# 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](https://docs.kernel.org/admin-guide/efi-stub.html).
## 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
```text theme={null}
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](./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`:
```bash theme={null}
# 1. Rebuild inside the kas shell
kas shell meta-qcom/ci/.yml:meta-qcom/ci/qcom-distro.yml
bitbake qcom-multimedia-image
# 2. Navigate to the deploy directory
cd build/tmp/deploy/images//-*.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.