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

# 烧录软件镜像

## 简介

将预构建镜像烧录到设备上。虽然 Qualcomm 硬件通常预装了镜像，但您可以使用此流程更新到较新的软件版本，或部署从源码构建的镜像。

要烧录预构建镜像，需要执行以下步骤：

* 下载烧录镜像所需的软件包 – [下载所需软件包](#download-required-packages)
* 获取可烧录镜像 – [获取可烧录镜像](#obtain-flashable-image)
* 确定设备的存储配置 – [确定存储配置](#identify-storage-configuration)
* 更新主机系统上的 udev 规则 – [配置 udev 规则](#configure-udev-rules)
* 根据参考套件选择合适的 CDT – [配置 CDT](#configure-cdt)
* 将设备切换到 EDL 模式 – [将设备切换到 EDL 模式](#switch-device-to-edl-mode)
* 预配 UFS – [预配 UFS](#provision-ufs)
* 烧录 SAIL – [烧录 SAIL](#flash-sail)
* 烧录软件镜像 – [烧录软件镜像](#flash-software-image)

## 下载所需软件包

QDL 是一款软件实用工具，用于与处于紧急下载 (EDL)
模式的 Qualcomm USB 设备通信，使你能够上传
刷写加载程序并将软件镜像烧录到设备上。按照
以下步骤在你的系统上下载并设置 QDL：

* 访问 [QDL 发布页面](https://github.com/linux-msm/qdl/releases/latest)，
  并根据你的机器和架构找到合适的二进制文件链接。

* 使用以下命令下载 QDL 二进制文件：

  ```bash theme={null}
  wget <qdl-binary-download-url> -O qdl.zip
  ```

* 解压下载的归档文件：

  ```bash theme={null}
  unzip qdl.zip
  ```

* 为 QDL 二进制文件授予执行权限：

  ```bash theme={null}
  chmod +x "$PWD/<unzipped-qdl-directory>/qdl"
  ```

* 将 QDL 可执行文件添加到系统 PATH：

  ```bash theme={null}
  export PATH="$PATH:$PWD/<unzipped-qdl-directory>"
  ```

* 验证 QDL 可执行文件是否可访问：

  ```bash theme={null}
  qdl --version
  ```

## 获取可烧录镜像

在烧写之前，您的主机上需要有一个可烧写的镜像目录。
根据获取镜像的方式，选择以下路径之一。

<Tabs>
  <Tab title="预构建镜像">
    预构建镜像以压缩包的形式分发。从[获取预构建镜像](/zh/Key-Documents/Flash-Guide/obtain-prebuilts)
    部分下载适用于您设备的压缩包，解压后进入解压出的目录。

    * 解压压缩包：

      ```bash theme={null}
      unzip <prebuilt-image>.zip
      ```

    * 进入解压后的目录：

      ```bash theme={null}
      cd <unzipped-image-directory>/images/<machine>/<image>-<machine>
      ```
  </Tab>

  <Tab title="编译的镜像">
    构建成功后，可烧写的镜像目录已存在于您的构建输出中。直接进入该目录即可。

    ```bash theme={null}
    cd build/tmp/deploy/images/<machine>/<image>-<machine>.rootfs.qcomflash
    ```
  </Tab>
</Tabs>

<Warning>
  除非另有说明，后续所有指令都应在此目录中运行。
</Warning>

## 确定存储配置

机器配置默认启用 UFS 或 eMMC 存储，这些设置也反映在预构建镜像中。如果需要修改存储类型，则必须更新配置并重新构建镜像，因为预构建二进制文件中无法更改此设置。

支持平台的默认存储配置如下

| 机器           | 存储类型       |
| :----------- | :--------- |
| IQ-9075-EVK  | UFS        |
| IQ-8275-EVK  | UFS        |
| QCS6490      | UFS        |
| IQ-615-EVK   | EMMC       |
| IQ-X7181-EVK | UFS/SPINOR |
| IQ-X5121-EVK | UFS/SPINOR |

## 配置 udev 规则

主机系统必须配置正确的 `udev` 规则，以允许正常的 USB
设备访问。仅在设置新的主机环境时，或在通过 USB 检测设备时遇到
权限问题时，才需要执行此步骤。

* 运行以下命令，在 Linux 主机上为 Qualcomm 制造厂商 ID **05c6**
  配置 `udev` USB 规则：
  ```bash theme={null}
  echo 'SUBSYSTEMS=="usb", ATTRS{idVendor}=="05c6", ATTRS{idProduct}=="9008", MODE="0666", GROUP="plugdev"' | sudo tee /etc/udev/rules.d/51-qcom-usb.rules
  ```

* 重启 `udev` 服务使更改生效：
  ```bash theme={null}
  sudo systemctl restart udev
  ```

* 如果 USB 线缆已连接到主机，请拔下并重新连接，以使更新后的规则生效。

## 配置 CDT

配置数据表 (CDT) 包含正确进行平台初始化所需的
设备特定信息。刷写之前，你需要根据参考套件
选择正确的 CDT 文件。

<Tabs>
  <Tab title="QCS6490/QCS5430">
    * qcomflash tarball 中提供了多个 CDT 二进制文件。
      为你的套件选择正确的 CDT 二进制文件，并用它替换默认的
      `cdt.bin`。

          <CodeGroup>
            ```bash Rb3Gen2 Core Kit theme={null}
            cp cdt_core_kit.bin cdt.bin
            ```

            ```bash Rb3Gen2 Vision Kit theme={null}
            cp cdt_vision_kit.bin cdt.bin
            ```

            ```bash Rb3Gen2 Industrial Kit theme={null}
            cp cdt_industrial_kit.bin cdt.bin
            ```

            ```bash Rb3Gen2 Industrial Mezz Kit theme={null}
            cp cdt_industrial_mezz_kit.bin cdt.bin
            ```
          </CodeGroup>

    * 整个刷写过程成功完成后，你可以通过查看 UEFI 串口日志
      来验证是否加载了正确的 CDT。使用 *Subtype* 字段来识别
      加载到设备上的 CDT。

      ```text Sample output theme={null}
      Platform Init [ 1966] BDS
      Platform : IOT
      Subtype : 2
      Boot Device : UFS
      Chip Name : QCS6490
      Chip Ver : 1.0
      ```

      | Subtype | 平台描述                     |
      | ------- | ------------------------ |
      | 2       | Vision Kit（Moselle 连接）   |
      | 5       | RB3Gen2 Core Kit（HSP 连接） |
      | 7       | Vision Kit（HSP 连接）       |
      | 9       | Industrial Kit           |
      | 13      | Industrial Mezz Kit      |
  </Tab>

  <Tab title="IQ-X7181/IQ-X5121">
    * 从 [CodeLinaro](https://artifacts.codelinaro.org/ui/native/codelinaro-le/Qualcomm_Linux/X1E80100/cdt/) 下载 CDT 二进制文件：

      ```bash theme={null}
      curl -OL https://artifacts.codelinaro.org/artifactory/codelinaro-le/Qualcomm_Linux/X1E80100/cdt/IQ-X.1.4-EVK-CDT.tar.gz
      ```

    * 解压 tarball 归档文件：

      ```bash theme={null}
      tar -xzf IQ-X.1.4-EVK-CDT.tar.gz
      ```

    * 进入解压后的目录：

      ```bash theme={null}
      cd IQ-X.1.4-EVK-CDT
      ```

    * 刷写 CDT：

      ```bash theme={null}
      qdl --storage spinor xbl_s_devprg_ns.melf rawprogram0_BLANK_GPT.xml
      qdl --storage spinor xbl_s_devprg_ns.melf rawprogram0_WIPE_PARTITIONS.xml
      qdl xbl_s_devprg_ns.melf rawprogram0.xml patch0.xml
      ```

    * 返回上一级目录：
      ```bash theme={null}
      cd ..
      ```
  </Tab>

  <Tab title="其他套件">
    * 对于 IQ-9075、IQ-8275 和 IQ-615 套件，qcomflash tarball 中
      包含的默认 `cdt.bin` 已经是适用于你的套件的正确 CDT。刷写前
      无需执行任何选择 CDT 的操作。
  </Tab>
</Tabs>

## 将设备切换到 EDL 模式

在刷写软件镜像之前，设备必须处于 EDL 模式。
默认情况下，Qualcomm 支持的设备在上电后如果设备上没有
镜像或镜像已损坏，会进入 EDL 模式。按照以下
步骤强制设备进入 EDL 模式。

<Tabs>
  <Tab title="QCS6490/QCS5430">
    * 按住 **F\_DL** 按钮。
          <img src="https://mintcdn.com/qualcomm-prod/yUQ5Z3Vx_Ib3ymoN/Key-Documents/Flash-Guide/media/k2c-qli-build-ga/RB3Gen2_device.png?fit=max&auto=format&n=yUQ5Z3Vx_Ib3ymoN&q=85&s=17b1e6d34fbe1bf9db626195064faead" alt="Figure: RB3Gen2_device" width="1001" height="710" data-path="Key-Documents/Flash-Guide/media/k2c-qli-build-ga/RB3Gen2_device.png" />
    * 将设备连接到 **+12 V 壁式电源**。
    * 通过 USB Type-C 接口将设备连接到主机系统。
    * 松开 **F\_DL** 按钮。设备此时处于 EDL 模式。
    * 整个刷写过程完成后，拔下电源线以退出 EDL 模式。
  </Tab>

  <Tab title="IQ-9075">
    <Tabs>
      <Tab title="IQ-9 Beta 评估套件 (EVK)">
        * 将设备连接到 **+12 V 壁式电源**。
        * 通过 USB Type-C 接口将设备连接到主机系统。
        * 打开拨码开关 S5-4，使设备进入 EDL 模式。
                  <img src="https://mintcdn.com/qualcomm-prod/yUQ5Z3Vx_Ib3ymoN/Key-Documents/Flash-Guide/media/k2c-qli-build-ga/qcs9075_qdl_mode_manual.png?fit=max&auto=format&n=yUQ5Z3Vx_Ib3ymoN&q=85&s=92813b6ee0591d3d6b88d2426a141c7e" alt="Figure: qcs9075_qdl_mode_manual" width="1094" height="305" data-path="Key-Documents/Flash-Guide/media/k2c-qli-build-ga/qcs9075_qdl_mode_manual.png" />
        * 整个刷写过程完成后，关闭 S5-4 拨码开关。
      </Tab>

      <Tab title="IQ-9075 EVK">
        * 将设备连接到 **+12 V 壁式电源**。
        * 通过 USB Type-C 接口将设备连接到主机系统。
        * 打开拨码开关 SW2-3，使设备进入 EDL 模式。
                  <img src="https://mintcdn.com/qualcomm-prod/yUQ5Z3Vx_Ib3ymoN/Key-Documents/Flash-Guide/media/k2c-qli-build-ga/IQ_9075_EVK.png?fit=max&auto=format&n=yUQ5Z3Vx_Ib3ymoN&q=85&s=eea5c7a7f4461b6d662d37f42d40595b" alt="Figure: IQ_9075_EVK" width="1131" height="318" data-path="Key-Documents/Flash-Guide/media/k2c-qli-build-ga/IQ_9075_EVK.png" />
        * 整个刷写过程完成后，关闭 SW2-3 拨码开关。
      </Tab>
    </Tabs>
  </Tab>

  <Tab title="IQ-8275">
    <Tabs>
      <Tab title="IQ-8 Beta 评估套件 (EVK)">
        * 将设备连接到 **+12 V 壁式电源**。
        * 通过 USB Type-C 接口将设备连接到主机系统。
        * 打开拨码开关 S5-4，使设备进入 EDL 模式。
                  <img src="https://mintcdn.com/qualcomm-prod/yUQ5Z3Vx_Ib3ymoN/Key-Documents/Flash-Guide/media/k2c-qli-build-ga/qcs9075_qdl_mode_manual.png?fit=max&auto=format&n=yUQ5Z3Vx_Ib3ymoN&q=85&s=92813b6ee0591d3d6b88d2426a141c7e" alt="Figure: qcs9075_qdl_mode_manual" width="1094" height="305" data-path="Key-Documents/Flash-Guide/media/k2c-qli-build-ga/qcs9075_qdl_mode_manual.png" />
        * 整个刷写过程完成后，关闭 S5-4 拨码开关。
      </Tab>

      <Tab title="IQ-8275 EVK">
        * 将设备连接到 **+12 V 壁式电源**。
        * 通过 USB Type-C 接口将设备连接到主机系统。
        * 打开拨码开关 S2-8，使设备进入 EDL 模式。
                  <img src="https://mintcdn.com/qualcomm-prod/yUQ5Z3Vx_Ib3ymoN/Key-Documents/Flash-Guide/media/k2c-qli-build-ga/IQ_9075_EVK.png?fit=max&auto=format&n=yUQ5Z3Vx_Ib3ymoN&q=85&s=eea5c7a7f4461b6d662d37f42d40595b" alt="Figure: IQ_9075_EVK" width="1131" height="318" data-path="Key-Documents/Flash-Guide/media/k2c-qli-build-ga/IQ_9075_EVK.png" />
        * 整个刷写过程完成后，关闭 S2-8 拨码开关。
      </Tab>
    </Tabs>
  </Tab>

  <Tab title="IQ-615">
    * 将设备连接到 **+12 V 壁式电源**。
    * 通过 USB Type-C 接口将设备连接到主机系统。
    * 关闭 SW 开关并打开拨码开关 SW3-4，使设备进入 EDL 模式。
          <img src="https://mintcdn.com/qualcomm-prod/yUQ5Z3Vx_Ib3ymoN/Key-Documents/Flash-Guide/media/k2c-qli-build-ga/qcs615_qdl_mode_manual.png?fit=max&auto=format&n=yUQ5Z3Vx_Ib3ymoN&q=85&s=c212e427805d9a1f5e3125e14e008681" alt="Figure: qcs615_qdl_mode_manual" width="800" height="667" data-path="Key-Documents/Flash-Guide/media/k2c-qli-build-ga/qcs615_qdl_mode_manual.png" />
    * 整个刷写过程完成后，打开 SW 开关并关闭 SW3-4 拨码开关。
  </Tab>

  <Tab title="IQ-X7181/IQ-X5121">
    * 将设备连接到 **+12 V 壁式电源**。
    * 通过 USB Type-C 接口将设备连接到主机系统。
    * 打开 S2-4 开关，使设备进入 EDL 模式。
          <img src="https://mintcdn.com/qualcomm-prod/Im5W2pUR5LdqxAI6/Key-Documents/Flash-Guide/media/k2c-qli-build-ga/x7181_edl_mode_manual.png?fit=max&auto=format&n=Im5W2pUR5LdqxAI6&q=85&s=9f8837fbba10eeb06d35967ed4db2a57" alt="Figure: x7181_edl_mode_manual" width="1429" height="718" data-path="Key-Documents/Flash-Guide/media/k2c-qli-build-ga/x7181_edl_mode_manual.png" />
    * 整个刷写过程完成后，关闭 S2-4 拨码开关。
  </Tab>
</Tabs>

运行以下命令，验证设备是否处于 EDL 模式：

```bash theme={null}
lsusb
```

```text Expected output theme={null}
Bus 002 Device 014: ID 05c6:9008 Qualcomm, Inc. Gobi Wireless Modem (QDL mode)
```

## 预配 UFS

通用闪存存储（UFS）配置（provisioning）有助于将存储划分为多个 LUN，
以分别存储不同类型的数据。这样可以提高访问效率和系统组织性。

UFS 默认已完成配置。如果 LUN 有任何更改，则必须重新配置 UFS。
要检查 UFS 是否需要重新配置，
请参阅[版本特定信息](/zh/Key-Documents/Software-Release-Notes/release-specific-information#ufs-provision)文档中的
*UFS Provision* 表格。

* 从 Qualcomm 的工件服务器下载配置文件：

  <CodeGroup>
    ```bash IQ-9075-EVK theme={null}
    wget https://artifacts.codelinaro.org/artifactory/codelinaro-le/Qualcomm_Linux/QCS9100/provision.zip
    ```

    ```bash IQ-8275-EVK theme={null}
    wget https://artifacts.codelinaro.org/artifactory/codelinaro-le/Qualcomm_Linux/QCS8300/provision.zip
    ```

    ```bash QCS6490 theme={null}
    wget https://artifacts.codelinaro.org/artifactory/codelinaro-le/Qualcomm_Linux/QCS6490/provision.zip
    ```

    ```bash IQ-X7181 theme={null}
    wget https://artifacts.codelinaro.org/artifactory/codelinaro-le/Qualcomm_Linux/X1E80100/provision_default.zip
    ```

    ```bash IQ-X5121 theme={null}
    wget https://artifacts.codelinaro.org/artifactory/codelinaro-le/Qualcomm_Linux/X1E80100/provision_default.zip
    ```
  </CodeGroup>

* 解压下载的压缩包：
  ```bash theme={null}
  unzip provision.zip -d provision
  ```

* 进入解压后的目录：
  ```bash theme={null}
  cd provision
  ```

* 配置 UFS：

  <CodeGroup>
    ```bash IQ-9075-EVK theme={null}
    qdl --storage ufs prog_firehose_ddr.elf provision_1_2.xml
    ```

    ```bash IQ-8275-EVK theme={null}
    qdl --storage ufs prog_firehose_ddr.elf provision_1_3.xml
    ```

    ```bash QCS6490 theme={null}
    qdl --storage ufs prog_firehose_ddr.elf provision_1_3.xml
    ```

    ```bash IQ-X7181 theme={null}
    qdl --storage ufs xbl_s_devprg_ns.melf provision.xml
    ```

    ```bash IQ-X5121 theme={null}
    qdl --storage ufs xbl_s_devprg_ns.melf provision.xml
    ```
  </CodeGroup>

* 返回上一级目录：
  ```bash theme={null}
  cd ..
  ```

## 烧录 SAIL

Safety Island (SAIL) 镜像包含隔离的安全关键固件，该固件运行在专用的 safety
island 上，以确保安全启动和可靠的系统运行独立于主处理器。

<Note>
  Safety Island (SAIL) 仅适用于 Qualcomm Dragonwing™ IQ-9075
  和 Qualcomm Dragonwing™ IQ-8275 开发套件。如果您使用的不是这两款
  开发套件之一，请跳过本节。
</Note>

* SAIL 工件位于解压后的 qcomflash 目录中的 `sail_nor` 目录下。
  进入以下目录：
  ```bash theme={null}
  cd sail_nor
  ```

* 烧写 SAIL：
  ```bash theme={null}
  qdl --storage spinor prog_firehose_ddr.elf rawprogram0.xml patch0.xml
  ```

* 返回上一级目录：
  ```bash theme={null}
  cd ..
  ```

## 烧录软件镜像

本节介绍如何使用 QDL 刷写镜像，
以及如何验证刷写过程是否成功。

* 确保 ModemManager 服务未在运行，因为当设备通过 USB 连接时，
  它可能会尝试将设备作为调制解调器进行管理，从而干扰 QDL。请在
  连接设备之前禁用它。在基于 systemd 的系统上，使用以下命令：
  ```bash theme={null}
  sudo systemctl stop ModemManager
  ```

* 选择合适的存储选项，使用 QDL 刷写软件镜像：

  <CodeGroup>
    ```bash UFS theme={null}
    qdl --storage ufs prog_firehose_ddr.elf rawprogram*.xml patch*.xml
    ```

    ```bash EMMC theme={null}
    qdl --storage emmc prog_firehose_ddr.elf rawprogram*.xml patch*.xml
    ```

    ```bash UFS/SPINOR theme={null}
    cd spinor
    qdl --storage spinor xbl_s_devprg_ns.melf rawprogram*.xml patch*.xml
    cd ..
    qdl --storage ufs xbl_s_devprg_ns.melf rawprogram*.xml patch*.xml
    ```
  </CodeGroup>

* 如果在终端窗口中看到如下消息所示的 *partition 1 is now bootable*，
  则表示刷写成功：
  ```text Sample output theme={null}
  partition 1 is now bootable
  ```

* 如果刷写失败，请执行以下步骤后重试刷写流程：
  * 关闭设备电源
  * 断开与主机的连接
  * 重启主机

## 相关主题

* [如何使用 PCAT 烧录镜像？](./flash-with-pcat)
* [如何使用 UART 切换到 EDL 模式？](./how-to-trigger-edl-with-uart)
* [如何使用 ADB 切换到 EDL 模式？](./how-to-trigger-edl-with-adb)
* [如何为 Yocto BSP 构建配置存储类型？](/zh/Key-Documents/Yocto-Guide/how-to-configure-storage-type)
* [如何连接 WiFi？](./how-to-connect-to-wifi)
* [如何使用 SSH 登录？](./how-to-sign-in-with-ssh)
* [如何配置带 RJ45 端口的以太网？](./how-to-configure-ethernet-rj45-port)
* [如何更新 USB 和以太网控制器固件？](./how-to-update-usb-ethernet-controller-firmware)
* [如何配置设备驱动程序？](./how-to-configure-device-drivers)