> ## 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 与 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 启动管理器。它实现了
[启动加载程序规范(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) | 包含内核、initrd 和命令行的自包含 EFI 二进制文件 |

在 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)。