> ## Documentation Index
> Fetch the complete documentation index at: https://dragonwingdocs-staging.qualcomm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# UEFI 与 systemd-boot

Qualcomm<sup>®</sup> Linux 使用 **systemd-boot** 作为 UEFI 启动管理器。Linux 内核在编译时启用了 EFI stub 支持，因此 UEFI 固件和 systemd-boot 可以将其作为 EFI 可执行文件直接加载。启动链中没有 GRUB 或其他第二阶段引导加载程序。

## UEFI 启动管理器概述

UEFI 启动管理器是在固件平台初始化之后运行的程序，负责选择并启动操作系统镜像。在 Qualcomm Linux 上：

1. XBL 固件初始化硬件（DDR、时钟、安全），并将控制权移交给存储在 `abl_a` / `abl_b` 分区中的 UEFI 镜像。
2. UEFI 固件执行 UEFI 平台初始化，发现 EFI 系统分区（ESP），并启动默认的 EFI 应用程序（systemd-boot）。
3. systemd-boot 从 ESP 读取启动条目，必要时显示菜单，并执行所选内核 EFI 二进制文件。

有关 UEFI 规范和启动管理器行为的更多信息，请参阅
[UEFI Boot Manager](https://uefi.org/specs/UEFI/2.10/03_Boot_Manager.html)。

## systemd-boot 行为

systemd-boot 是来自 systemd 项目的一个精简、符合规范的 UEFI 启动管理器。它实现了
[Boot Loader Specification (BLS)](https://uapi-group.org/specifications/specs/boot_loader_specification/)，并同时支持 Type 1 和 Type 2 启动条目。

### 启动条目发现

启动时，systemd-boot 会在 ESP 的以下位置扫描有效条目：

| **位置**                  |   **条目类型**  | **描述**                          |
| :---------------------- | :---------: | :------------------------------ |
| `loader/entries/*.conf` |    Type 1   | 纯文本插入式条目，引用独立的内核、initrd 和选项文件   |
| `EFI/Linux/*.efi`       | Type 2（UKI） | 自包含的 EFI 二进制文件，内含内核、initrd 和命令行 |

在 Qualcomm Linux 上，内核仅以放置在 `EFI/Linux/` 中的 **Type 2 UKI 镜像**形式打包。

### loader.conf

systemd-boot 的全局默认设置存储在 ESP 上的 `loader/loader.conf` 中。Qualcomm Linux 的 Yocto 构建会写入一个精简的 `loader.conf`：

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

|   **键**   |   **值**  | **效果**                                              |
| :-------: | :------: | :-------------------------------------------------- |
| `timeout` |    `0`   | 不显示菜单直接自动启动。设置为正整数（秒）可显示选择菜单。                       |
| `default` | `@saved` | 加载保存在 `LoaderEntryDefault` EFI 变量中的条目，若不存在则回退到自动选择。 |

## 查看启动条目格式

### Type 1 插入式 .conf 文件

Type 1 条目是放置在 ESP 上 `loader/entries/` 中的纯文本 `.conf` 文件。每个文件描述一个启动条目：

```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 在生产环境中不使用 Type 1 条目。此处展示该布局仅供添加自定义条目时参考。
</Note>

### Type 2 统一内核镜像（UKI）

UKI 是单个 EFI 二进制文件，其中嵌入了 Linux 内核镜像、initramfs、内核命令行，以及可选的设备树。UEFI 固件（或 systemd-boot）可以直接执行 UKI，无需任何辅助 `.conf` 文件。

UKI 文件放置在 ESP 上的 `EFI/Linux/` 中，并以 `.efi` 扩展名命名（例如 `linux.efi`、`linux-rt.efi`）。systemd-boot 通过扫描该目录自动识别它们。

有关 UKI 镜像格式规范，请参阅
[Type 2 EFI Unified Kernel Images](https://uapi-group.org/specifications/specs/boot_loader_specification/#type-2-efi-unified-kernel-images)。

## 生成 Yocto ESP 镜像

Yocto 的 `meta-qcom` 层提供了配方
`recipes-kernel/images/esp-qcom-image.bb`，用于组装 ESP 镜像（`efi.bin`）。该配方：

1. 从 `systemd` 软件包构建 systemd-boot，并将 `systemd-boot.efi` 二进制文件复制到 `EFI/BOOT/BOOTAA64.EFI`，即默认的 UEFI 可移动介质启动路径。
2. 使用 `ukify` 将内核、initramfs 和命令行打包成 UKI，并写入 `EFI/Linux/linux.efi`（RT 构建则为 `EFI/Linux/linux-rt.efi`）。
3. 写入包含默认超时和条目策略的 `loader/loader.conf`。
4. 将所有内容格式化为 FAT32 镜像，并作为 `efi.bin` 存储在构建部署目录中。

生成的 `efi.bin` 会被刷写到设备上的 `efi` 分区。
有关刷写说明，请参阅 [安装并启动内核](./install-and-boot-the-kernel)。

有关安全启动集成的更多信息，请参阅
[使用 systemd-boot 和 UKI 配置并实现安全启动](https://dragonwingdocs.qualcomm.com/Key-Documents/Yocto-Guide/configure-and-secure-boot-with-systemd-boot-and-uki)。