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

# UEFI and systemd-boot

Qualcomm<sup>®</sup> Linux uses **systemd-boot** as the UEFI boot manager. The Linux kernel
is compiled with EFI stub support so that UEFI firmware and systemd-boot can
load it directly as an EFI executable. There is no GRUB or other second-stage
boot loader in the chain.

## UEFI boot manager overview

A UEFI boot manager is a program that runs after firmware platform
initialization and is responsible for selecting and launching an OS image.
On Qualcomm Linux:

1. The XBL firmware initialises hardware (DDR, clocks, security) and hands off to
   a UEFI image stored in the `abl_a` / `abl_b` partitions.
2. UEFI firmware performs UEFI platform initialization, discovers the EFI System
   Partition (ESP), and launches the default EFI application (systemd-boot).
3. systemd-boot reads boot entries from the ESP, displays a menu if needed, and
   executes the selected kernel EFI binary.

For more information on the UEFI specification and boot manager behavior, see
[UEFI Boot Manager](https://uefi.org/specs/UEFI/2.10/03_Boot_Manager.html).

## systemd-boot behavior

systemd-boot is a minimal, spec-compliant UEFI boot manager from the systemd
project. It implements the
[Boot Loader Specification (BLS)](https://uapi-group.org/specifications/specs/boot_loader_specification/)
and supports both Type 1 and Type 2 boot entries.

### Boot entry discovery

On startup, systemd-boot scans the ESP for valid entries in the following
locations:

| **Location**            | **Entry type** | **Description**                                                                   |
| :---------------------- | :------------: | :-------------------------------------------------------------------------------- |
| `loader/entries/*.conf` |     Type 1     | Plain-text drop-in entries referencing separate kernel, initrd, and options files |
| `EFI/Linux/*.efi`       |  Type 2 (UKI)  | Self-contained EFI binaries containing the kernel, initrd, and command line       |

On Qualcomm Linux, kernels are packaged exclusively as **Type 2 UKI images**
placed in `EFI/Linux/`.

### loader.conf

Global defaults for systemd-boot are stored in `loader/loader.conf` on the ESP.
The Qualcomm Linux Yocto build writes a minimal `loader.conf`:

```text theme={null}
timeout 0
default @saved
```

|  **Key**  | **Value** | **Effect**                                                                                             |
| :-------: | :-------: | :----------------------------------------------------------------------------------------------------- |
| `timeout` |    `0`    | Auto-boot without displaying the menu. Set to a positive integer (seconds) to show the selection menu. |
| `default` |  `@saved` | Load the entry saved in the `LoaderEntryDefault` EFI variable, falling back to automatic selection.    |

## View Boot entry formats

### Type 1 drop-in .conf files

Type 1 entries are plain-text `.conf` files placed in `loader/entries/` on the
ESP. Each file describes one boot entry:

```text theme={null}
# loader/entries/linux.conf
title   Qualcomm Linux 6.18
linux   /EFI/Linux/linux.efi
options root=PARTUUID=xxxxxxxx-xxxx rw quiet
```

<Note>
  Qualcomm Linux does not use Type 1 entries in production. The layout is shown
  here for reference when adding custom entries.
</Note>

### Type 2 Unified Kernel Images (UKI)

A UKI is a single EFI binary that embeds the Linux kernel image, initramfs,
kernel command line, and optionally a device tree. UEFI firmware (or
systemd-boot) can execute a UKI directly without any supporting `.conf` file.

UKI files are placed in `EFI/Linux/` on the ESP and named with an `.efi`
extension (for example `linux.efi`, `linux-rt.efi`). systemd-boot identifies
them automatically by scanning that directory.

For the UKI image format specification, see
[Type 2 EFI Unified Kernel Images](https://uapi-group.org/specifications/specs/boot_loader_specification/#type-2-efi-unified-kernel-images).

## Generate Yocto ESP image

The Yocto `meta-qcom` layer provides the recipe
`recipes-kernel/images/esp-qcom-image.bb` that assembles the ESP image
(`efi.bin`). The recipe:

1. Builds systemd-boot from the `systemd` package and copies the
   `systemd-boot.efi` binary to `EFI/BOOT/BOOTAA64.EFI` which is the default UEFI
   removable media boot path.
2. Packages the kernel, initramfs, and command line into a UKI using
   `ukify` and writes it to `EFI/Linux/linux.efi` (or `EFI/Linux/linux-rt.efi`
   for RT builds).
3. Writes `loader/loader.conf` with the default timeout and entry policy.
4. Formats everything into a FAT32 image and stores it as `efi.bin` in the
   build deploy directory.

The resulting `efi.bin` is flashed to the `efi` partition on the device.
For flashing instructions, see [Install & boot the kernel](./install-and-boot-the-kernel).

For more information about the secure boot integration, see
[Configure and secure boot with systemd-boot and UKI](https://dragonwingdocs.qualcomm.com/Key-Documents/Yocto-Guide/configure-and-secure-boot-with-systemd-boot-and-uki).