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

# Qualcomm Linux 上的 U-Boot

## 概述

本页概述了 Qualcomm Linux (QLI) 软件中对 U-Boot（Universal Boot Loader，通用引导加载程序）的支持。

## 支持的 SoC

| SoC 名称          | 是否支持 | 存储   |
| --------------- | ---- | ---- |
| QCS6490         | 是    | UFS  |
| IQ-9075         | 是    | UFS  |
| IQ-615          | 是    | eMMC |
| IQ-8275         | 是    | UFS  |
| CQ-2390/IQ-2390 | 是    | eMMC |

## 构建 U-Boot 镜像

本节介绍如何在 QLI 软件中构建 U-Boot 二进制文件。

### 1. 从 Qualcomm Linux GitHub 仓库构建

#### 前提条件

在执行构建步骤之前，请完成以下操作：

1. 在本地计算机上安装以下软件包：
   ```bash theme={null}
   sudo apt install libgnutls28-dev
   ```

2. 下载并解压 Arm GNU Toolchain：

   ```bash theme={null}
   cd ~  # or your preferred location
   wget https://developer.arm.com/-/media/Files/downloads/gnu/14.2.rel1/binrel/arm-gnu-toolchain-14.2.rel1-x86_64-aarch64-none-linux-gnu.tar.xz
   tar -xf arm-gnu-toolchain-14.2.rel1-x86_64-aarch64-none-linux-gnu.tar.xz
   ```

   <Note>
     * 这将在 `~/arm-gnu-toolchain-14.2.rel1-x86_64-aarch64-none-linux-gnu/` 创建工具链目录。如果您将其解压到其他位置，请相应地调整构建命令中的路径。
     * 仅在 x86 64 位主机计算机上安装该工具链。
     * 有关其他版本，请访问 [Arm GNU Toolchain Downloads](https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads)。
   </Note>

3. 下载 qtestsign 工具：
   ```bash theme={null}
   cd ~  # or your preferred location
   git clone https://github.com/msm8916-mainline/qtestsign qtestsign
   ```

#### 构建步骤

1. 将 U-Boot 仓库从 Qualcomm Linux GitHub 下载到本地工作区，并进入 `u-boot` 文件夹：
   ```bash theme={null}
   git clone https://github.com/qualcomm-linux/u-boot.git
   ```

2. 切换分支：
   ```bash theme={null}
   git switch qcom-next
   ```

3. 检出 QLI 版本的 SRC REV：
   ```bash theme={null}
   git checkout 5ec66cb5c3f29e2da1f55464109cae3fe8545b69
   ```

4. 为您的平台配置构建。此命令会在 `.output` 目录中创建所需的配置文件。请根据您的平台选择相应的命令：

   | SoC             | 命令                                      |
   | --------------- | --------------------------------------- |
   | QCS6490         | `make O=.output qcm6490_defconfig`      |
   | IQ-9075         | `make O=.output qcom_lemans_defconfig`  |
   | IQ-615          | `make O=.output qcom_qcs615_defconfig`  |
   | IQ-8275         | `make O=.output qcom_qcs8300_defconfig` |
   | CQ-2390/IQ-2390 | `make O=.output qcom_shikra_defconfig`  |

5. 使用交叉编译工具链构建 U-Boot：

   ```bash theme={null}
   make -j8 CROSS_COMPILE=~/arm-gnu-toolchain-14.2.rel1-x86_64-aarch64-none-linux-gnu/bin/aarch64-none-linux-gnu- O=.output
   ```

   <Note>
     如果您将工具链解压到了其他位置，请将 `~/arm-gnu-toolchain-14.2.rel1-x86_64-aarch64-none-linux-gnu/` 替换为您实际的工具链安装路径。
   </Note>

   **预期结果：**

   * U-Boot 构建无错误完成。
   * `u-boot.elf` 文件位于 `.output` 目录中。

#### 将 u-boot.elf 转换为 u-boot.mbn

此命令生成刷写所需的已签名 `u-boot.mbn` 文件：

```bash theme={null}
python ~/qtestsign/qtestsign.py -v6 aboot -o .output/u-boot.mbn .output/u-boot.elf
```

<Note>
  如果您将 qtestsign 克隆到了其他位置，请将 `~/qtestsign/` 替换为您实际的 qtestsign 安装路径。
</Note>

### 2. 使用 Yocto 构建

按照 [Build Qualcomm Linux using Yocto](/zh/Key-Documents/Yocto-Guide/build-qualcomm-linux) 页面上的说明操作，并进行以下修改：

* 要生成 U-Boot 二进制文件，请在"构建 BSP 镜像"第 3 步的构建命令中追加 `:meta-qcom/ci/u-boot-qcom.yml` KAS 片段。
* 在构建产物文件夹中，最终的 U-Boot 二进制文件以 `uefi.elf` 的形式生成在 `<workspace-dir>/build/tmp/deploy/images/<MACHINE>/<IMAGE>-<MACHINE>.rootfs.qcomflash/` 目录中。

## 刷写 U-Boot 镜像

### 使用 Qualcomm 工具

按照构建刷写说明，将 U-Boot 二进制文件与 QLI 构建一起刷写，如 [Flash software images](/zh/Key-Documents/Flash-Guide/flash-with-qdl) 中所述。

### 使用 Fastboot

1. 使用以下方法之一进入 fastboot 模式：
   * 从内核：
     ```bash theme={null}
     adb shell reboot bootloader
     ```
   * 从 U-Boot CLI：
     ```
     run fastboot
     ```
2. 从主机刷写所需的镜像。例如，要刷写 U-Boot 镜像：
   ```bash theme={null}
   fastboot flash uefi_a u-boot.mbn
   ```
3. 重启设备：
   ```bash theme={null}
   fastboot reboot
   ```

## 支持的 U-Boot 命令

下表列出了在支持的平台上可用的一些关键 U-Boot 命令。这些命令涵盖启动管理、环境管理、存储访问和硬件外设控制。可用命令可能因平台支持情况而异。

<Note>
  * 在 QCS6490 中，Watchdog 由 Hypervisor 使用；因此，Watchdog 命令在 QCS6490 上不起作用。
</Note>

| 命令                                | 说明                                              |
| --------------------------------- | ----------------------------------------------- |
| **启动**                            |                                                 |
| `run bootcmd`                     | 运行 `bootcmd` 中定义的默认启动命令序列                       |
| `bootefi bootmgr`                 | 根据 BootOrder/BootXXXX 变量加载并启动 EFI 负载            |
| `bootflow scan [-abeGl] [bdev]`   | 扫描有效的 bootflow（`-l` 列出，`-a` 全部，`-e` 错误，`-b` 启动） |
| `bootflow list [-e]`              | 列出已扫描的 bootflow（`-e` 包含错误）                      |
| `bootflow select [<num>\|<name>]` | 按编号或名称选择 bootflow                               |
| `bootflow info [-ds]`             | 显示当前 bootflow 的信息（`-d` 转储 bootflow）             |
| `bootflow boot`                   | 启动当前的 bootflow                                  |
| `bootdev list [-p]`               | 列出所有可用的启动设备（`-p` 探测）                            |
| `bootdev info [-p]`               | 显示有关当前启动设备的信息（`-p` 探测）                          |
| **常规**                            |                                                 |
| `printenv`                        | 打印环境变量                                          |
| `saveenv`                         | 保存环境变量                                          |
| `version`                         | 打印监视器、编译器和链接器版本                                 |
| `run fastboot`                    | 进入 fastboot 模式并等待来自主机的 fastboot 命令请求            |
| `reset -edl`                      | 进入 EDL（紧急下载）模式                                  |
| **SCSI**                          |                                                 |
| `scsi scan`                       | 扫描 SCSI 总线                                      |
| `scsi info`                       | 显示可用的 SCSI 设备                                   |
| `scsi device [dev]`               | 显示或设置当前设备（`dev` 应为 0、1、2、3、4、5、...）             |
| `scsi part [dev]`                 | 打印一个或所有 SCSI 设备的分区表                             |
| `scsi read [addr] [blk#] [cnt]`   | 从块 `blk#` 开始读取 `cnt` 个块到内存地址 `addr`             |
| `scsi write [addr] [blk#] [cnt]`  | 从内存地址 `addr` 开始向块 `blk#` 写入 `cnt` 个块            |
| **MMC**                           |                                                 |
| `mmc list`                        | 列出可用的 MMC 设备                                    |
| `mmc info`                        | 显示当前 MMC 设备信息                                   |
| `mmc dev [dev]`                   | 显示或设置当前 MMC 设备                                  |
| `mmc part`                        | 打印当前 MMC 设备的分区表                                 |
| `mmc read [addr] [blk#] [cnt]`    | 从 MMC 的块 `blk#` 开始读取 `cnt` 个块到内存地址 `addr`       |
| `mmc write [addr] [blk#] [cnt]`   | 从内存地址 `addr` 开始向 MMC 的块 `blk#` 写入 `cnt` 个块      |
| **稳压器 (Regulator)**               |                                                 |
| `regulator list`                  | 列出 UCLASS 稳压器设备                                 |
| `regulator dev [regulator-name]`  | 显示或设置当前操作的稳压器设备                                 |
| `regulator info`                  | 打印约束信息                                          |
| `regulator status [-a]`           | 打印工作状态（使用 `-a` 显示全部）                            |
| `regulator value [val] [-f]`      | 打印或设置电压值（单位为 µV，使用 `-f` 强制设置）                   |
| `regulator enable`                | 启用稳压器输出                                         |
| `regulator disable`               | 禁用稳压器输出                                         |
| **看门狗 (WDT)**                     |                                                 |
| `wdt list`                        | 列出可用的看门狗设备                                      |
| `wdt dev [devname]`               | 显示或设置当前看门狗设备                                    |
| `wdt start <timeout_ms>`          | 以指定的超时时间（毫秒）启动看门狗计时器                            |
| `wdt stop`                        | 停止看门狗计时器                                        |

## UEFI 安全启动

U-Boot 支持 UEFI 安全启动，它在执行之前使用基于平台密钥 (PK)、密钥交换密钥 (KEK)、签名数据库 (db) 和禁止签名数据库 (dbx) 的信任链，验证 EFI 镜像（例如内核和引导加载程序）的真实性。

有关生成密钥、预置变量存储、签名 EFI 镜像以及在启用 `CONFIG_EFI_SECURE_BOOT` 的情况下构建 U-Boot 的完整步骤，请参阅 U-Boot 文档中的 [EFI Secure Boot](https://github.com/qualcomm-linux/u-boot/blob/qcom-next/doc/usage/efi_secureboot.rst)。

## 另请参阅

* [使用 U-Boot 日志进行故障排查](./troubleshoot-using-uboot-log)
* [EFI Secure Boot（U-Boot 上游文档）](https://github.com/qualcomm-linux/u-boot/blob/qcom-next/doc/usage/efi_secureboot.rst)