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

## 获取可烧录镜像

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

> [tab] 预构建镜像
>
> 预构建镜像以压缩包形式分发。请从 [获取预构建镜像](https://dragonwingdocs.qualcomm.com/zh/Key-Documents/Flash-Guide/obtain-prebuilts.md)
> 部分下载适用于您设备的压缩包，解压该压缩包，然后进入解压后的目录。
>
> * 解压压缩包：
>
>   ```bash theme={null}
>   unzip <prebuilt-image>.zip
>   ```
>
> * 进入解压后的目录：
>
>   ```bash theme={null}
>   cd <unzipped-image-directory>/images/<machine>/<image>-<machine>
>   ```

> [tab] 编译镜像
>
> 构建成功后，可刷写的镜像目录已存在于
> 您的构建输出中。请直接进入该目录。
>
> ```bash theme={null}
> cd build/tmp/deploy/images/<machine>/<image>-<machine>.rootfs.qcomflash
> ```

> [!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 |
| SHIKRA-EVK | EMMC |

## 配置 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 文件。

> [tab] QCS6490/QCS5430
>
> * qcomflash tarball 中提供了多个 CDT 二进制文件。
>   请为您的套件选择正确的 CDT 二进制文件，并用相应的文件替换默认的
>   `cdt.bin`。
>
>   ```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
>   ```
>
> * 整个刷写过程成功后，您可以通过查看 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] 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] CQ-2390/IQ-2390
>
> * 从 [CodeLinaro](https://artifacts.codelinaro.org/ui/native/codelinaro-le/Qualcomm_Linux/CQ2390/cdt/) 下载 CDT 二进制文件：
>
>   ```bash CQ-2390 EVK theme={null}
>   curl -OL https://artifacts.codelinaro.org/artifactory/codelinaro-le/Qualcomm_Linux/CQ2390/cdt/cq2390-itp.zip
>   ```
>
>   ```bash IQ-2390 EVK theme={null}
>   curl -OL https://artifacts.codelinaro.org/artifactory/codelinaro-le/Qualcomm_Linux/CQ2390/cdt/iq2390-itp.zip
>   ```
>
> * 解压下载的压缩包：
>
>   ```bash theme={null}
>   unzip <cdt-zip-file>.zip
>   ```
>
> * 刷写 CDT：
>
>   ```bash theme={null}
>   qdl --storage emmc prog_firehose_ddr.elf rawprogram1.xml patch1.xml
>   ```
>
> * CDT 刷写完成后，终端会显示 `flashed "cdt" successfully`。

> [tab] 其他套件
>
> * 对于 IQ-9075、IQ-8275 和 IQ-615 套件，qcomflash tarball 中包含的默认
>   `cdt.bin` 已经是适用于您套件的正确 CDT。在刷写之前无需
>   执行任何操作来选择 CDT。

## 将设备切换到 EDL 模式

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

> [tab] QCS6490/QCS5430
>
> * 按住 **F\_DL** 按钮。
>
>   ![图：RB3Gen2\_device](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)
> * 将设备连接到 **+12 V 壁式电源**。
> * 通过 USB Type-C 接口将设备连接到主机系统。
> * 松开 **F\_DL** 按钮。设备现在处于 EDL 模式。
> * 整个刷写过程完成后，拔下电源线以退出 EDL 模式。

> [tab] IQ-9075
>
> > [tab] IQ-9 Beta Evaluation Kit (EVK)
> >
> > * 将设备连接到 **+12 V 壁式电源**。。
> > * 通过 USB Type-C 接口将设备连接到主机系统。
> > * 打开拨码开关 S5-4，使设备进入 EDL 模式。
> >
> >   ![图：qcs9075\_qdl\_mode\_manual](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)
> > * 整个刷写过程完成后，关闭 S5-4 拨码开关。
>
> > [tab] IQ-9075 EVK
> >
> > * 将设备连接到 **+12 V 壁式电源**。
> > * 通过 USB Type-C 接口将设备连接到主机系统。
> > * 打开拨码开关 SW2-3，使设备进入 EDL 模式。
> >
> >   ![图：IQ\_9075\_EVK](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)
> > * 整个刷写过程完成后，关闭 SW2-3 拨码开关。

> [tab] IQ-8275
>
> > [tab] IQ-8 Beta Evaluation Kit (EVK)
> >
> > * 将设备连接到 **+12 V 壁式电源**。
> > * 通过 USB Type-C 接口将设备连接到主机系统。
> > * 打开拨码开关 S5-4，使设备进入 EDL 模式。
> >
> >   ![图：qcs9075\_qdl\_mode\_manual](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)
> > * 整个刷写过程完成后，关闭 S5-4 拨码开关。
>
> > [tab] IQ-8275 EVK
> >
> > * 将设备连接到 **+12 V 壁式电源**。
> > * 通过 USB Type-C 接口将设备连接到主机系统。
> > * 打开拨码开关 S2-8，使设备进入 EDL 模式。
> >
> >   ![图：IQ\_9075\_EVK](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)
> > * 整个刷写过程完成后，关闭 S2-8 拨码开关。

> [tab] IQ-615
>
> * 将设备连接到 **+12 V 壁式电源**。
> * 通过 USB Type-C 接口将设备连接到主机系统。
> * 关闭 SW 开关并打开拨码开关 SW3-4，使设备进入 EDL 模式。
>
>   ![图：qcs615\_qdl\_mode\_manual](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)
> * 整个刷写过程完成后，打开 SW 开关并关闭 SW3-4 拨码开关。

> [tab] IQ-X7181/IQ-X5121
>
> * 将设备连接到 **+12 V 壁式电源**。
> * 通过 USB Type-C 接口将设备连接到主机系统。
> * 打开 S2-4 开关，使设备进入 EDL 模式。
>
>   ![图：x7181\_edl\_mode\_manual](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)
> * 整个刷写过程完成后，关闭 S2-4 拨码开关。

> [tab] CQ-2390/IQ-2390
>
> > [tab] CQ-2390 EVK
> >
> > * 打开 S1011-1 DIP 开关，使设备进入 EDL 模式。
> >
> >   ![图：cq2390\_edl\_mode\_manual](https://mintcdn.com/qualcomm-prod/MqkP8ZsZP3_uOdBD/Key-Documents/Flash-Guide/media/k2c-qli-build-ga/cq2390_edl_mode_manual.png?fit=max\&auto=format\&n=MqkP8ZsZP3_uOdBD\&q=85\&s=bf9355210cd8de81bd029f9dc48da6a4)
> > * 将设备连接到 **+12 V 壁式电源**。
> > * 通过 USB Type-C 接口将设备连接到主机系统。
> > * 整个刷写过程完成后，关闭 S1011-1 DIP 开关。
>
> > [tab] IQ-2390 EVK
> >
> > * 打开 S1011-1 DIP 开关，使设备进入 EDL 模式。
> >
> >   ![图：iq2390\_edl\_mode\_manual](https://mintcdn.com/qualcomm-prod/MqkP8ZsZP3_uOdBD/Key-Documents/Flash-Guide/media/k2c-qli-build-ga/iq2390_edl_mode_manual.png?fit=max\&auto=format\&n=MqkP8ZsZP3_uOdBD\&q=85\&s=93144ed0b284ab965155e416ca353330)
> > * 将设备连接到 **+12 V 壁式电源**。
> > * 通过 USB Type-C 接口将设备连接到主机系统。
> > * 按下 **SYS\_ON** 电源按钮。
> >
> >   ![图：iq2390\_sys\_on\_power\_button](https://mintcdn.com/qualcomm-prod/MqkP8ZsZP3_uOdBD/Key-Documents/Flash-Guide/media/k2c-qli-build-ga/iq2390_sys_on_power_button.png?fit=max\&auto=format\&n=MqkP8ZsZP3_uOdBD\&q=85\&s=42c3cf7e9dbf13d003a920080b4e00e4)
> > * 整个刷写过程完成后，关闭 S1011-1 DIP 开关。在 IQ-2390S EVK 上，关闭 DIP 开关后按下 **SYS\_ON** 电源按钮。

运行以下命令验证设备是否处于 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，从而分别存储不同类型的数据。这
提高了访问效率和系统组织性。

在 Qualcomm 硬件上，UFS 默认已完成配置，因此只有在自定义 LUN 布局时才需要重新配置。由于 Qualcomm 提供的 `provision.zip` 与自定义布局不对应，您必须提供自己的 provision 文件。以下命令演示了如何运行重新配置流程。

> [!NOTE]
>
> UFS 配置不适用于 CQ-2390/IQ-2390。

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

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

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

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

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

* 配置 UFS：

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

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

## 烧录 SAIL

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

> [!NOTE]
>
> Safety Island (SAIL) 仅适用于 Qualcomm Dragonwing™ IQ-9075
> 和 Qualcomm Dragonwing™ IQ-8275 开发套件。如果您使用的不是
> 这些开发套件之一，请跳过本节。

* 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 连接时，
  它可能会尝试将设备作为 modem 进行管理，从而干扰 QDL。请在连接设备之前
  将其禁用。在基于 systemd 的系统上，使用以下命令：
  ```bash theme={null}
  sudo systemctl stop ModemManager
  ```

* 通过选择相应的存储选项，使用 QDL 刷写软件镜像：

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

* 如果您在终端窗口中看到可引导分区消息，则表明刷写成功：

  ```text UFS theme={null}
  partition 1 is now bootable
  ```

  ```text EMMC theme={null}
  partition 0 is now bootable
  ```

  ```text UFS/SPINOR theme={null}
  11 patches applied
  ```

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

## 相关主题

* [如何使用 PCAT 烧录镜像？](./flash-with-pcat)
* [如何使用 UART 切换到 EDL 模式？](./how-to-trigger-edl-with-uart)
* [如何使用 ADB 切换到 EDL 模式？](./how-to-trigger-edl-with-adb)
* [如何为 Yocto BSP 构建配置存储类型？](https://dragonwingdocs.qualcomm.com/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)
