> ## 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 与启动分区

Qualcomm<sup>®</sup> Linux 的启动无需传统的第二阶段引导加载程序。内核本身借助 EFI boot stub 被编译为一个 EFI 应用程序,UEFI 固件(或 systemd-boot)直接从 EFI 系统分区(ESP)执行它。

## 作为 EFI stub 的 Qualcomm Linux 内核

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 附加 `.conf` 启动项。Qualcomm Linux 默认不填充此目录。                                             |

### FAT32 要求

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

## 统一内核镜像(UKI)结构

UKI 是一个带有额外 EFI 节(section)的 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` skill 文档。

## DTB 分区镜像(dtb.bin)

设备树 blob 维护在单独的分区(`dtb_a`)中,而不是嵌入到 UKI 中。这样无需重新构建内核镜像即可更新 DTB(例如添加新的单板覆盖)。

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>