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

# EFI stub 和启动分区

Qualcomm<sup>®</sup> Linux 在启动时不使用传统的第二阶段引导加载程序。内核
本身使用 EFI boot stub 编译为 EFI 应用程序，UEFI 固件（或 systemd-boot）
直接从 EFI 系统分区（ESP）执行它。

## Qualcomm Linux 内核作为 EFI stub

EFI boot stub 是内置于内核镜像中的一个薄垫层
（`drivers/firmware/efi/libstub/`），它满足 EFI 应用程序入口点约定。当设置
`CONFIG_EFI_STUB=y` 时，内核镜像被格式化为可移植可执行文件/通用目标文件
格式（PE/COFF）二进制文件，以便 UEFI 固件可以直接加载和执行它。

在 AArch64 上，不支持压缩内核（`zImage`）。因此，内核镜像以未压缩的
`Image` 二进制形式发布，被包装在 PE/COFF 容器中并链接了 EFI stub。

在当前 defconfig 或运行中的系统上验证配置：

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

有关上游 EFI stub 文档，请参阅
[The EFI Boot Stub](https://docs.kernel.org/admin-guide/efi-stub.html)。

## EFI 系统分区（ESP）布局

ESP 是一个 FAT32 格式的分区，UEFI 固件和 systemd-boot 将其用作启动组件
的共享存储。在 Qualcomm Linux 设备上，它作为 `efi` 分区（分区标签）可访问，
其内容在 Yocto 构建期间被打包进可烧写的 `efi.bin` 镜像。

### 目录结构

```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)
```

| **路径**                  | **描述**                                                                                         |
| :---------------------- | :--------------------------------------------------------------------------------------------- |
| `EFI/BOOT/BOOTAA64.EFI` | AArch64 的 UEFI 默认启动应用程序。当没有配置显式启动条目时，UEFI 固件会运行它。在 Qualcomm Linux 上，它是 `systemd-boot.efi` 的副本。 |
| `EFI/Linux/*.efi`       | 统一内核镜像（UKI）。systemd-boot 将此目录中的所有 `.efi` 文件枚举为启动条目。                                            |
| `loader/loader.conf`    | 控制 systemd-boot 的超时和默认条目策略。                                                                    |
| `loader/entries/`       | 可选的 Type 1 drop-in `.conf` 条目。在 Qualcomm Linux 上默认不填充。                                         |

### FAT32 要求

UEFI 规范要求 ESP 格式化为 FAT32（较小的分区可使用 FAT12/16）。Yocto 的
`esp-qcom-image.bb` 配方使用正确的 FAT32 参数创建 `efi.bin` 镜像。请勿
使用其他文件系统重新格式化 `efi` 分区，否则 UEFI 固件将无法挂载它。

## 统一内核镜像（UKI）结构

UKI 是一个带有额外 EFI 段的 PE/COFF 二进制文件，这些段携带启动载荷。
在 Qualcomm Linux 构建中，`ukify` 嵌入的段包括：

|  **PE 段**  | **内容**                                  |
| :--------: | :-------------------------------------- |
|  `.linux`  | 未压缩的内核 `Image` 二进制文件                    |
|  `.initrd` | initramfs CPIO 归档（gzip 或 lz4 压缩）        |
| `.cmdline` | 在构建时固化的内核命令行字符串                         |
| `.dtbauto` | （可选）设备树 blob；DTB 通常位于单独分区上的 `dtb.bin` 中 |
|  `.osrel`  | 标识发行版和内核版本的 `os-release` 元数据            |

Qualcomm Linux UKI 将内核命令行存储在 `.cmdline` 中，这意味着命令行在
镜像构建时就已固定。要更改内核参数，必须重新构建 `efi.bin`。有关开发
期间的运行时覆盖，请参阅 `efi-bin-append-update-kernel-cmdline-params`
技能文档。

## DTB 分区镜像（dtb.bin）

设备树 blob 保存在单独的分区（`dtb_a`）中，而不是嵌入在 UKI 里。这样
可以在不重新构建内核镜像的情况下更新 DTB（例如添加新的开发板 overlay）。

Yocto 构建会编译 `KERNEL_DEVICETREE` 中列出的所有设备树，并将它们打包成
`dtb.bin`，这是一个 FIT 镜像，UEFI 固件会查询它，为检测到的硬件选择正确的
DTB。基于 FIT 的选择机制在[设备树架构](./device-tree-architecture)中描述。

## 构建工件汇总

下表将每个与启动相关的工件映射到其分区和角色：

|         **文件**        |   **分区**  | **内容**                                          |
| :-------------------: | :-------: | :---------------------------------------------- |
|       `efi.bin`       |   `efi`   | FAT32 ESP 镜像：systemd-boot + `EFI/Linux/` 中的 UKI |
|       `dtb.bin`       |  `dtb_a`  | 已编译 DTB / DTBO 文件的 FIT 镜像                       |
|       `vmlinux`       |    构建工件   | 带调试符号的未剥离 ELF 内核镜像                              |
|        `Image`        | 嵌入在 UKI 中 | 原始的 AArch64 内核二进制文件                             |
| `initramfs-*.cpio.gz` | 嵌入在 UKI 中 | 早期用户空间文件系统                                      |

## 内核更改后更新 ESP

修改内核源码、配置或设备树后，请重新构建并重新烧写 `efi.bin` 和
`dtb.bin`：

```bash theme={null}
# 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
```

<Note>
  在内核或 DTS 更改后，请始终同时烧写 `efi.bin` 和 `dtb.bin`。只烧写
  其中一个可能导致内核与设备树不同步，从而造成启动失败。
</Note>