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

# 使用 QDL 烧写 Ubuntu

> 使用 Qualcomm Device Loader (QDL) 命令行工具，从 Ubuntu、Windows 或 macOS 主机将 Ubuntu 烧写到 IQ-8275 EVK。

**Qualcomm Device Loader (QDL)** 是适用于 Qualcomm 设备的跨平台命令行烧写工具。当您需要完全控制烧写过程、在无图形界面环境中运行或希望编写自动化烧写脚本时，请使用此方法。

如需基于 GUI 的替代方案，请参阅[**使用 Qualcomm Launcher 烧写 Ubuntu**](./flash-using-qualcomm-launcher)。

<Warning>
  烧写会擦除设备上的所有数据。开始前请备份所有重要内容。
</Warning>

## 所需物品

* 带 12 V 电源的 IQ-8275 EVK
* USB Type-C 线缆（EVK 上的 USB0 端口 → 主机计算机）
* 运行 Ubuntu、Windows 或 macOS 的主机计算机

## 选择您的主机操作系统并按完整流程操作

从 [**Qualcomm Software Center**](https://softwarecenter.qualcomm.com/catalog/item/Qualcomm_Device_Loader) 为您的主机操作系统下载 QDL。

<Tabs>
  <Tab title="Ubuntu">
    ### 下载 Ubuntu 镜像

    从 [**Canonical Ubuntu 网站**](https://ubuntu.com/download/qualcomm-iot#evaluation-kit)下载预构建的 Ubuntu 镜像和启动固件。

    <Note>
      请务必在 Canonical Ubuntu 网站上确认最新构建的可用性。以下链接固定为最新验证过的版本。
    </Note>

    1. 运行以下脚本下载并组装可烧写的镜像文件夹。根据所需镜像传入 `--server` 或 `--desktop`：

       ```shell theme={null}
       ./prepare_iq8275_ubuntu_flashable.sh --server
       ```

       ```shell theme={null}
       ./prepare_iq8275_ubuntu_flashable.sh --desktop
       ```

       这会在 `iq8275_flash_prep_work/IQ8275_ubuntu_images` 中生成可烧写的镜像 — 下文称为 `<path-to-image>`。

           <Note>
             要更新到新的 Canonical 版本，请编辑脚本中的 `CANONICAL_BASE`、`SERVER_IMG_XZ`、`DESKTOP_IMG_XZ` 和 `BOOT_FW_URL_DEFAULT`。
           </Note>

           <Accordion title="prepare_iq8275_ubuntu_flashable.sh（完整脚本）">
             ```bash theme={null}
             #!/usr/bin/env bash
             set -euo pipefail

             FLAVOR="${FLAVOR:-server}"     # server | desktop
             OUT_DIR="${OUT_DIR:-IQ8275_ubuntu_images}"
             WORK_DIR="${WORK_DIR:-$PWD/iq8275_flash_prep_work}"

             CANONICAL_BASE="https://people.canonical.com/~platform/images/qualcomm-iot/ubuntu-24.04/ubuntu-24.04-x08"
             SERVER_DIR="${CANONICAL_BASE}/ubuntu-server-24.04"
             DESKTOP_DIR="${CANONICAL_BASE}/ubuntu-desktop-24.04"

             SERVER_IMG_XZ="iot-qualcomm-dragonwing-classic-server-2404-x08-20260210.4096b.img.xz"
             DESKTOP_IMG_XZ="iot-qualcomm-dragonwing-classic-desktop-2404-x08-20260210.4096b.img.xz"

             BOOT_FW_URL_DEFAULT="https://artifacts.codelinaro.org/artifactory/qli-ci/flashable-binaries/ubuntu-fw/QCS8300/QLI.1.7-Ver.1.1/QLI.1.7-Ver.1.1-ubuntu-QCS8300-nhlos-bins.tar.gz"
             BOOT_FW_URL="${BOOT_FW_URL:-$BOOT_FW_URL_DEFAULT}"

             usage() {
               cat <<EOF
             Usage: $(basename "$0") [--server|--desktop] [--out <folder>] [--work <folder>]

             Examples:
               ./prepare_iq8275_ubuntu_flashable.sh --server
               ./prepare_iq8275_ubuntu_flashable.sh --desktop --out IQ8275_ubuntu_images_desktop

             Environment overrides:
               FLAVOR=server|desktop
               OUT_DIR=...
               WORK_DIR=...
               BOOT_FW_URL=...
             EOF
             }

             while [[ $# -gt 0 ]]; do
               case "$1" in
                 --server)  FLAVOR="server"; shift ;;
                 --desktop) FLAVOR="desktop"; shift ;;
                 --out)     OUT_DIR="$2"; shift 2 ;;
                 --work)    WORK_DIR="$2"; shift 2 ;;
                 -h|--help) usage; exit 0 ;;
                 *) echo "Unknown option: $1"; usage; exit 1 ;;
               esac
             done

             need_cmd() { command -v "$1" >/dev/null 2>&1 || { echo "ERROR: missing '$1'"; exit 1; }; }
             need_cmd curl; need_cmd tar; need_cmd unxz; need_cmd file
             need_cmd find; need_cmd cp; need_cmd head; need_cmd ls; need_cmd mkdir; need_cmd rm

             download() {
               local url="$1" dst="$2"
               echo "Downloading: $url"
               curl -L --fail --retry 3 --retry-delay 2 -o "$dst" "$url"
             }

             mkdir -p "$WORK_DIR" "$OUT_DIR"
             cd "$WORK_DIR"

             if [[ "$FLAVOR" == "server" ]]; then
               BASE_DIR="$SERVER_DIR"; IMG_XZ="$SERVER_IMG_XZ"
             elif [[ "$FLAVOR" == "desktop" ]]; then
               BASE_DIR="$DESKTOP_DIR"; IMG_XZ="$DESKTOP_IMG_XZ"
             else
               echo "ERROR: FLAVOR must be 'server' or 'desktop'"; exit 1
             fi

             IMG_URL="${BASE_DIR}/${IMG_XZ}"
             DTB_URL="${BASE_DIR}/dtb.bin"
             RAWPROGRAM_URL="${BASE_DIR}/rawprogram0.xml"

             download "$IMG_URL" "$IMG_XZ"
             echo "Extracting OS image: $IMG_XZ"
             unxz -f "$IMG_XZ"
             IMG="${IMG_XZ%.xz}"

             download "$DTB_URL" "dtb.bin"
             download "$RAWPROGRAM_URL" "rawprogram0.xml"

             BOOT_FW_TAR="$(basename "$BOOT_FW_URL")"
             download "$BOOT_FW_URL" "$BOOT_FW_TAR"

             if file "$BOOT_FW_TAR" | grep -qi "HTML"; then
               echo "ERROR: Boot firmware download is HTML, not a tar.gz. Use the direct /artifactory/ endpoint."; exit 1
             fi

             if ! tar -tzf "$BOOT_FW_TAR" >/dev/null 2>&1; then
               echo "ERROR: Boot firmware is not a valid gzip tarball."; exit 1
             fi

             BOOT_FW_EXTRACT_DIR="$WORK_DIR/boot_fw_extract"
             rm -rf "$BOOT_FW_EXTRACT_DIR"; mkdir -p "$BOOT_FW_EXTRACT_DIR"
             tar -xzf "$BOOT_FW_TAR" -C "$BOOT_FW_EXTRACT_DIR"

             mapfile -t TOP_LEVEL_DIRS < <(find "$BOOT_FW_EXTRACT_DIR" -mindepth 1 -maxdepth 1 -type d)
             TOP_DIR="${#TOP_LEVEL_DIRS[@]}" && [[ ${#TOP_LEVEL_DIRS[@]} -eq 1 ]] && TOP_DIR="${TOP_LEVEL_DIRS[0]}" || TOP_DIR="$BOOT_FW_EXTRACT_DIR"
             cp -a "$TOP_DIR"/. "$OUT_DIR"/
             cp -a "dtb.bin" "$OUT_DIR"/ && cp -a "rawprogram0.xml" "$OUT_DIR"/ && cp -a "$IMG" "$OUT_DIR"/

             echo "✅ Flashable folder ready: $(realpath "$OUT_DIR")"
             ls -lh "$OUT_DIR" | sed -n '1,200p'
             ```
           </Accordion>

    ### 下载 QDL

    1. 下载 [Linux (x64) 版 QDL 工具](https://softwarecenter.qualcomm.com/catalog/item/Qualcomm_Device_Loader)并解压。解压后的文件夹包含 `qdl` 二进制文件 — 下文称为 `<qdl_dir>`。

    2. 安装所需的库（如已安装可跳过）：

       ```shell theme={null}
       sudo apt-get install libxml2-dev libudev-dev libusb-1.0-0-dev
       ```

           <Note>
             我们建议将镜像文件夹和 QDL 解压到同一个父文件夹中。这样所有路径都在同一个根目录下。
           </Note>

    ### 设置 QDL 驱动

    Ubuntu 需要一条 udev 规则，以便内核在设备进入 EDL 模式时授予您的用户与设备通信的权限。

    1. 检查规则是否已存在：
       ```shell theme={null}
       ls /etc/udev/rules.d/51-qcom-usb.rules
       ```

    2. 如果文件**不存在**，用一条命令创建它：
       ```shell theme={null}
       echo 'SUBSYSTEMS=="usb", ATTRS{idVendor}=="05c6", ATTRS{idProduct}=="9008", MODE="0664", GROUP="plugdev"' | sudo tee /etc/udev/rules.d/51-qcom-usb.rules
       ```
       如果文件**已存在**，确认规则已包含在内：
       ```shell theme={null}
       cat /etc/udev/rules.d/51-qcom-usb.rules
       ```

    3. 重新加载 udev 以应用规则：
       ```shell theme={null}
       sudo systemctl restart udev
       ```
       如果 USB 线缆已经连接，请断开并重新连接。

    ### 设置 QDL 路径

    1. 使 QDL 可执行：
       ```shell theme={null}
       chmod +x <qdl_dir>/qdl
       ```

    2. 验证 QDL 是否正常工作：
       ```shell theme={null}
       <qdl_dir>/qdl --help
       ```
       您应看到 QDL 的用法输出。如果出现错误，请检查路径。

    ### 使设备进入 EDL 模式

    1. **打开** SW2-3 DIP 开关 — 向上推。

           <img src="https://mintcdn.com/qualcomm-prod/kAKe9NmJg3DGZBpB/Ubuntu/images/update-software/EDL_mode_dipSwitch.png?fit=max&auto=format&n=kAKe9NmJg3DGZBpB&q=85&s=f5764a27d34ffd1dd36f97bb81a5a2bf" alt="SW2-3 DIP 开关位置" width="1131" height="318" data-path="Ubuntu/images/update-software/EDL_mode_dipSwitch.png" />

    2. 将 **12 V 电源**连接到 EVK。

    3. 将 **USB Type-C 线缆**从 EVK 上的 **USB0** 连接到您的主机。

           <img src="https://mintcdn.com/qualcomm-prod/kAKe9NmJg3DGZBpB/Ubuntu/images/update-software/iq9075-flashsetup.png?fit=max&auto=format&n=kAKe9NmJg3DGZBpB&q=85&s=62735e8fd3f1b3cdb680ae392a222625" alt="烧写设置 — USB 和电源连接" width="926" height="672" data-path="Ubuntu/images/update-software/iq9075-flashsetup.png" />

    4. 拨动**电源开关**打开设备。

    5. 确认设备处于 EDL 模式：
       ```shell theme={null}
       lsusb
       ```
       **预期输出：**
       ```text theme={null}
       Bus 002 Device 014: ID 05c6:9008 Qualcomm, Inc. Gobi Wireless Modem (QDL mode)
       ```
       如果设备未出现，请重新检查 SW2-3 和 USB-C 线缆。

    ### 配置 UFS（Provision）

    UFS（通用闪存存储）配置将内部存储划分为独立的逻辑单元号（LUN）。从 Qualcomm Linux 切换到 Ubuntu 时需要此步骤。

    如果满足以下任一情况，请运行 UFS 配置：

    * 这是一块**从未烧写过的全新板卡**。
    * 您正在**升级到新的镜像版本**。
    * 您正在**切换发行版**（Qualcomm Linux ↔ Ubuntu）。

    1. 下载并解压 provision 文件：
       ```shell theme={null}
       wget https://artifacts.codelinaro.org/artifactory/codelinaro-le/Qualcomm_Linux/QCS8300/provision.zip
       unzip provision.zip
       ```

    2. 在解压后的 provision 目录中执行 UFS 配置：
       ```shell theme={null}
       cd provision
       <qdl_dir>/qdl --storage ufs prog_firehose_ddr.elf provision_1_3.xml
       ```
       **预期输出：**
       ```text theme={null}
       UFS provisioning succeeded
       ```

    <Note>
      UFS 配置完成后，设备会与 USB 断开连接。在继续之前，请关闭再打开电源开关，使其重新启动进入 EDL 模式。
    </Note>

    ### 烧写 CDT

    CDT 提供驱动和固件用于正确初始化平台的平台相关数据。

    1. 下载并解压 CDT 文件：
       ```shell theme={null}
       wget https://artifacts.codelinaro.org/artifactory/codelinaro-le/Qualcomm_Linux/QCS8300/cdt/qcs8275-iq-8275-evk-pro-sku.zip
       unzip qcs8275-iq-8275-evk-pro-sku.zip
       ```

    2. 在解压后的目录中烧写 CDT：
       ```shell theme={null}
       <qdl_dir>/qdl prog_firehose_ddr.elf rawprogram3.xml patch3.xml
       ```
       **预期输出：**
       ```text theme={null}
       flashed "cdt" successfully
       13 patches applied
       ```

    <Note>
      CDT 烧写完成后，设备会与 USB 断开连接。在继续之前，请关闭再打开电源开关，使其重新启动进入 EDL 模式。
    </Note>

    ### 烧写 SAIL 固件

    安全岛（SAIL）是一个独立、隔离的处理器，独立于主应用处理器处理安全关键功能。其固件位于专用的 **spinor** 闪存分区上。

    1. 进入镜像文件夹内的 `sail_nor` 子文件夹：
       ```shell theme={null}
       cd <path-to-image>/sail_nor
       ```

    2. 烧写 SAIL 固件：
       ```shell theme={null}
       <qdl_dir>/qdl --storage spinor prog_firehose_ddr.elf rawprogram0.xml patch0.xml
       ```
       **预期输出：**
       ```text theme={null}
       flashed "SAIL_HYP" successfully
       flashed "SAIL_SW1" successfully
       flashed "SAIL_HYP_BKUP" successfully
       flashed "SAIL_SW1_BKUP" successfully
       11 patches applied
       ```

    ### 烧写 Ubuntu

    1. 进入主镜像文件夹：
       ```shell theme={null}
       cd <path-to-image>
       ```

    2. 烧写镜像：
       ```shell theme={null}
       <qdl_dir>/qdl prog_firehose_ddr.elf rawprogram0.xml rawprogram1.xml rawprogram2.xml rawprogram3.xml rawprogram4.xml patch1.xml patch2.xml patch3.xml patch4.xml
       ```
       当最后一行显示如下内容时，烧写完成：
       ```text theme={null}
       partition 1 is now bootable
       ```
  </Tab>

  <Tab title="Windows">
    ### 下载 Ubuntu 镜像

    从 [**Canonical Ubuntu 网站**](https://ubuntu.com/download/qualcomm-iot#evaluation-kit)下载预构建的 Ubuntu 镜像和启动固件。

    <Note>
      请务必在 Canonical Ubuntu 网站上确认最新构建的可用性。以下链接固定为最新验证过的版本。
    </Note>

    1. 运行以下脚本下载并组装可烧写的镜像文件夹。传入 `server` 或 `desktop` 作为参数：

       ```shell theme={null}
       prepare_iq8275_windows_flashable.bat server
       ```

       ```shell theme={null}
       prepare_iq8275_windows_flashable.bat desktop
       ```

       这会在 `IQ8275_ubuntu_images` 中生成可烧写的镜像 — 下文称为 `<path-to-image>`。

           <Note>
             要更新到新的 Canonical 版本，请编辑脚本中的 `CANONICAL_BASE`、`SERVER_IMG_XZ`、`DESKTOP_IMG_XZ` 和 `BOOT_FW_URL`。
           </Note>

           <Accordion title="prepare_iq8275_windows_flashable.bat（完整脚本）">
             ```bash theme={null}
             @echo on
             setlocal EnableExtensions EnableDelayedExpansion

             set "FLAVOR=server"
             set "OUT_DIR_NAME=IQ8275_ubuntu_images"
             set "SCRIPT_ROOT=%CD%"
             set "WORK_DIR=%SCRIPT_ROOT%\iq8275_flash_prep_work"
             set "OUT_DIR=%SCRIPT_ROOT%\%OUT_DIR_NAME%"
             set "CURL_FLAGS=--ssl-no-revoke -L --fail --retry 3 --retry-delay 2"

             if not "%~1"=="" (
               if /I "%~1"=="server"  set "FLAVOR=server"
               if /I "%~1"=="desktop" set "FLAVOR=desktop"
             )

             set "CANONICAL_BASE=https://people.canonical.com/~platform/images/qualcomm-iot/ubuntu-24.04/ubuntu-24.04-x08"
             set "SERVER_DIR=%CANONICAL_BASE%/ubuntu-server-24.04"
             set "DESKTOP_DIR=%CANONICAL_BASE%/ubuntu-desktop-24.04"

             set "SERVER_IMG_XZ=iot-qualcomm-dragonwing-classic-server-2404-x08-20260210.4096b.img.xz"
             set "DESKTOP_IMG_XZ=iot-qualcomm-dragonwing-classic-desktop-2404-x08-20260210.4096b.img.xz"

             set "BOOT_FW_URL=https://artifacts.codelinaro.org/artifactory/qli-ci/flashable-binaries/ubuntu-fw/QCS8300/QLI.1.7-Ver.1.1/QLI.1.7-Ver.1.1-ubuntu-QCS8300-nhlos-bins.tar.gz"
             set "BOOT_FW_TAR=QLI.1.7-Ver.1.1-ubuntu-QCS8300-nhlos-bins.tar.gz"

             if /I "%FLAVOR%"=="server" (
               set "BASE_DIR=%SERVER_DIR%" & set "IMG_XZ=%SERVER_IMG_XZ%"
             ) else (
               set "BASE_DIR=%DESKTOP_DIR%" & set "IMG_XZ=%DESKTOP_IMG_XZ%"
             )

             set "IMG_URL=%BASE_DIR%/%IMG_XZ%"
             set "DTB_URL=%BASE_DIR%/dtb.bin"
             set "RAWPROGRAM_URL=%BASE_DIR%/rawprogram0.xml"

             where curl >nul 2>&1 || (echo ERROR: curl.exe not found & goto :FAIL)
             where tar >nul 2>&1  || (echo ERROR: tar.exe not found & goto :FAIL)
             where robocopy >nul 2>&1 || (echo ERROR: robocopy not found & goto :FAIL)

             set "SEVENZIP="
             if exist "%ProgramFiles%\7-Zip\7z.exe" set "SEVENZIP=%ProgramFiles%\7-Zip\7z.exe"
             if exist "%ProgramFiles(x86)%\7-Zip\7z.exe" set "SEVENZIP=%ProgramFiles(x86)%\7-Zip\7z.exe"

             if not exist "%WORK_DIR%" mkdir "%WORK_DIR%"
             if not exist "%OUT_DIR%"  mkdir "%OUT_DIR%"
             pushd "%WORK_DIR%"

             curl %CURL_FLAGS% -o "%IMG_XZ%" "%IMG_URL%"
             if errorlevel 1 (echo ERROR: download system image failed & popd & goto :FAIL)

             set "IMG=%IMG_XZ:.xz=%"
             if defined SEVENZIP (
               "%SEVENZIP%" x -y "%IMG_XZ%"
             ) else (
               tar -xf "%IMG_XZ%"
               if errorlevel 1 (echo ERROR: tar could not extract .xz; install 7-Zip and rerun & popd & goto :FAIL)
             )
             if not exist "%IMG%" (echo ERROR: expected image not found & popd & goto :FAIL)

             curl %CURL_FLAGS% -o "dtb.bin" "%DTB_URL%"
             if errorlevel 1 (echo ERROR: download dtb.bin failed & popd & goto :FAIL)

             curl %CURL_FLAGS% -o "rawprogram0.xml" "%RAWPROGRAM_URL%"
             if errorlevel 1 (echo ERROR: download rawprogram0.xml failed & popd & goto :FAIL)

             curl %CURL_FLAGS% -o "%BOOT_FW_TAR%" "%BOOT_FW_URL%"
             if errorlevel 1 (echo ERROR: download boot firmware failed & popd & goto :FAIL)

             findstr /I /M "<html" "%BOOT_FW_TAR%" >nul 2>&1
             if not errorlevel 1 (echo ERROR: boot firmware is HTML, not tar.gz & popd & goto :FAIL)

             set "BOOT_EXTRACT=%WORK_DIR%\boot_fw_extract"
             if exist "%BOOT_EXTRACT%" rmdir /S /Q "%BOOT_EXTRACT%"
             mkdir "%BOOT_EXTRACT%"
             tar -xf "%BOOT_FW_TAR%" -C "%BOOT_EXTRACT%"
             if errorlevel 1 (echo ERROR: extract boot firmware failed & popd & goto :FAIL)

             set "TOPDIR=" & set "DIRCOUNT=0"
             for /f "delims=" %%D in ('dir /b /ad "%BOOT_EXTRACT%"') do (
               set /a DIRCOUNT+=1
               if "!DIRCOUNT!"=="1" set "TOPDIR=%BOOT_EXTRACT%\%%D"
             )
             if "%DIRCOUNT%"=="1" (
               robocopy "%TOPDIR%" "%OUT_DIR%" /E /COPY:DAT /R:2 /W:2
             ) else (
               robocopy "%BOOT_EXTRACT%" "%OUT_DIR%" /E /COPY:DAT /R:2 /W:2
             )
             if %errorlevel% GEQ 8 (echo ERROR: robocopy failed & popd & goto :FAIL)

             copy /Y "dtb.bin" "%OUT_DIR%\" & copy /Y "rawprogram0.xml" "%OUT_DIR%\" & copy /Y "%IMG%" "%OUT_DIR%\"
             popd

             echo SUCCESS. Flashable folder ready: %OUT_DIR%
             dir "%OUT_DIR%" /A:-D
             pause
             exit /b 0

             :FAIL
             echo FAILED. Check messages above.
             pause
             exit /b 1
             ```
           </Accordion>

    ### 下载 QDL

    1. 下载 [Windows 版 QDL 工具](https://softwarecenter.qualcomm.com/#/catalog/item/Qualcomm_Device_Loader)并解压。解压后的文件夹包含 `qdl.exe` — 下文称为 `<qdl_dir>`。

           <Note>
             我们建议将镜像文件夹和 QDL 解压到同一个父文件夹中（例如 `C:\Users\you\Downloads\qualcomm-flash\`）。这样所有路径都在同一个根目录下。
           </Note>

    ### 设置 QDL 驱动

    1. 卸载所有现有的 Qualcomm USB 驱动（QUD）— 它们与 QDL 驱动冲突。打开**设备管理器**，找到您的设备并卸载所有现有驱动。设备**不应**出现在 COM 端口下。

    2. 从解压后的 QDL 文件夹中运行 `install_driver.bat` 以安装 WinUSB 驱动。

           <img src="https://mintlify.s3.us-west-1.amazonaws.com/qualcomm-prod/zh/Ubuntu/images/update-software/win_bat.png" alt="运行 install_driver.bat" />

    ### 使设备进入 EDL 模式

    1. **打开** SW2-3 DIP 开关 — 向上推。

           <img src="https://mintcdn.com/qualcomm-prod/kAKe9NmJg3DGZBpB/Ubuntu/images/update-software/EDL_mode_dipSwitch.png?fit=max&auto=format&n=kAKe9NmJg3DGZBpB&q=85&s=f5764a27d34ffd1dd36f97bb81a5a2bf" alt="SW2-3 DIP 开关位置" width="1131" height="318" data-path="Ubuntu/images/update-software/EDL_mode_dipSwitch.png" />

    2. 将 **12 V 电源**连接到 EVK。

    3. 将 **USB Type-C 线缆**从 EVK 上的 **USB0** 连接到您的主机。

           <img src="https://mintcdn.com/qualcomm-prod/kAKe9NmJg3DGZBpB/Ubuntu/images/update-software/iq9075-flashsetup.png?fit=max&auto=format&n=kAKe9NmJg3DGZBpB&q=85&s=62735e8fd3f1b3cdb680ae392a222625" alt="烧写设置 — USB 和电源连接" width="926" height="672" data-path="Ubuntu/images/update-software/iq9075-flashsetup.png" />

    4. 拨动**电源开关**打开设备。

    5. 打开**设备管理器**并确认出现一个 Qualcomm USB 设备（不在 COM 端口下）。

           <img src="https://mintcdn.com/qualcomm-prod/kAKe9NmJg3DGZBpB/Ubuntu/images/update-software/dm_IQ9075_enum.jpg?fit=max&auto=format&n=kAKe9NmJg3DGZBpB&q=85&s=5f3e7876ccd247d6bb2d22f28bdbefc2" alt="设备管理器 — 确认 EDL 模式" width="1027" height="848" data-path="Ubuntu/images/update-software/dm_IQ9075_enum.jpg" />

    ### 配置 UFS（Provision）

    UFS（通用闪存存储）配置将内部存储划分为独立的逻辑单元号（LUN）。从 Qualcomm Linux 切换到 Ubuntu 时需要此步骤。

    如果满足以下任一情况，请运行 UFS 配置：

    * 这是一块**从未烧写过的全新板卡**。
    * 您正在**升级到新的镜像版本**。
    * 您正在**切换发行版**（Qualcomm Linux ↔ Ubuntu）。

    1. 下载 [**provision.zip**](https://artifacts.codelinaro.org/artifactory/codelinaro-le/Qualcomm_Linux/QCS8300/provision.zip) 并解压。

    2. 进入解压后的 provision 文件夹并执行 UFS 配置：

       **命令提示符：**

       ```shell theme={null}
       "<qdl_dir>\qdl.exe" --storage ufs prog_firehose_ddr.elf provision_1_3.xml
       ```

       **PowerShell：**

       ```shell theme={null}
       & "<qdl_dir>\qdl.exe" --storage ufs prog_firehose_ddr.elf provision_1_3.xml
       ```

       **预期输出：**

       ```text theme={null}
       UFS provisioning succeeded
       ```

    <Note>
      UFS 配置完成后，设备会与 USB 断开连接。在继续之前，请关闭再打开电源开关，使其重新启动进入 EDL 模式。
    </Note>

    ### 烧写 CDT

    CDT 提供驱动和固件用于正确初始化平台的平台相关数据。

    1. 下载 [**IQ8275 CDT**](https://artifacts.codelinaro.org/artifactory/codelinaro-le/Qualcomm_Linux/QCS8300/cdt/qcs8275-iq-8275-evk-pro-sku.zip) 并解压。

    2. 在解压后的目录中烧写 CDT：

       **命令提示符：**

       ```shell theme={null}
       "<qdl_dir>\qdl.exe" prog_firehose_ddr.elf rawprogram3.xml patch3.xml
       ```

       **PowerShell：**

       ```shell theme={null}
       & "<qdl_dir>\qdl.exe" prog_firehose_ddr.elf rawprogram3.xml patch3.xml
       ```

       **预期输出：**

       ```text theme={null}
       flashed "cdt" successfully
       13 patches applied
       ```

    <Note>
      CDT 烧写完成后，设备会与 USB 断开连接。在继续之前，请关闭再打开电源开关，使其重新启动进入 EDL 模式。
    </Note>

    ### 烧写 SAIL 固件

    安全岛（SAIL）是一个独立、隔离的处理器，独立于主应用处理器处理安全关键功能。其固件位于专用的 **spinor** 闪存分区上。

    1. 进入镜像文件夹内的 `sail_nor` 子文件夹：
       ```shell theme={null}
       cd <path-to-image>\sail_nor
       ```

    2. 烧写 SAIL 固件：

       **命令提示符：**

       ```shell theme={null}
       "<qdl_dir>\qdl.exe" --storage spinor prog_firehose_ddr.elf rawprogram0.xml patch0.xml
       ```

       **PowerShell：**

       ```shell theme={null}
       & "<qdl_dir>\qdl.exe" --storage spinor prog_firehose_ddr.elf rawprogram0.xml patch0.xml
       ```

       **预期输出：**

       ```text theme={null}
       flashed "SAIL_HYP" successfully
       flashed "SAIL_SW1" successfully
       flashed "SAIL_HYP_BKUP" successfully
       flashed "SAIL_SW1_BKUP" successfully
       11 patches applied
       ```

    ### 烧写 Ubuntu

    1. 进入主镜像文件夹：
       ```shell theme={null}
       cd <path-to-image>
       ```

    2. 烧写镜像（Windows 不支持通配符 — 需显式列出所有文件）：

       **命令提示符：**

       ```shell theme={null}
       "<qdl_dir>\qdl.exe" prog_firehose_ddr.elf rawprogram0.xml rawprogram1.xml rawprogram2.xml rawprogram3.xml rawprogram4.xml patch1.xml patch2.xml patch3.xml patch4.xml
       ```

       **PowerShell：**

       ```shell theme={null}
       & "<qdl_dir>\qdl.exe" prog_firehose_ddr.elf rawprogram0.xml rawprogram1.xml rawprogram2.xml rawprogram3.xml rawprogram4.xml patch1.xml patch2.xml patch3.xml patch4.xml
       ```

       当最后一行显示如下内容时，烧写完成：

       ```text theme={null}
       partition 1 is now bootable
       ```
  </Tab>

  <Tab title="macOS">
    ### 下载 Ubuntu 镜像

    从 [**Canonical Ubuntu 网站**](https://ubuntu.com/download/qualcomm-iot#evaluation-kit)下载预构建的 Ubuntu 镜像和启动固件。

    <Note>
      请务必在 Canonical Ubuntu 网站上确认最新构建的可用性。以下链接固定为最新验证过的版本。
    </Note>

    1. 运行以下脚本下载并组装可烧写的镜像文件夹。根据所需镜像传入 `--server` 或 `--desktop`：

       ```shell theme={null}
       ./prepare_iq8275_ubuntu_flashable.sh --server
       ```

       ```shell theme={null}
       ./prepare_iq8275_ubuntu_flashable.sh --desktop
       ```

       这会在 `iq8275_flash_prep_work/IQ8275_ubuntu_images` 中生成可烧写的镜像 — 下文称为 `<path-to-image>`。完整脚本请参见 Ubuntu 选项卡。

    ### 下载 QDL

    1. 下载 [macOS (Apple Silicon) 版 QDL 工具](https://softwarecenter.qualcomm.com/catalog/item/Qualcomm_Device_Loader)并解压。解压后的文件夹包含 `qdl` 二进制文件 — 下文称为 `<qdl_dir>`。

           <Note>
             我们建议将镜像文件夹和 QDL 解压到同一个父文件夹中。这样所有路径都在同一个根目录下。
           </Note>

    ### 设置 QDL 路径

    1. 通过 Homebrew 安装所需的库（如已安装可跳过）：
       ```shell theme={null}
       brew install libusb libxml2
       ```

    2. 使 QDL 可执行并清除 macOS 隔离标记，以便 Gatekeeper 允许其运行：
       ```shell theme={null}
       chmod +x <qdl_dir>/qdl
       sudo xattr -dr com.apple.quarantine <qdl_dir>
       ```
           <Note>
             需要 `sudo`，因为部分捆绑的库是只读的。如果此步骤后 macOS 仍然阻止该工具，请在**系统设置 → 隐私与安全性**中允许它。
           </Note>

    3. 验证 QDL 是否正常工作：
       ```shell theme={null}
       <qdl_dir>/qdl --help
       ```
       您应看到 QDL 的用法输出。如果出现错误，请检查路径。

    ### 使设备进入 EDL 模式

    1. **打开** SW2-3 DIP 开关 — 向上推。

           <img src="https://mintcdn.com/qualcomm-prod/kAKe9NmJg3DGZBpB/Ubuntu/images/update-software/EDL_mode_dipSwitch.png?fit=max&auto=format&n=kAKe9NmJg3DGZBpB&q=85&s=f5764a27d34ffd1dd36f97bb81a5a2bf" alt="SW2-3 DIP 开关位置" width="1131" height="318" data-path="Ubuntu/images/update-software/EDL_mode_dipSwitch.png" />

    2. 将 **12 V 电源**连接到 EVK。

    3. 将 **USB Type-C 线缆**从 EVK 上的 **USB0** 连接到您的主机。

           <img src="https://mintcdn.com/qualcomm-prod/kAKe9NmJg3DGZBpB/Ubuntu/images/update-software/iq9075-flashsetup.png?fit=max&auto=format&n=kAKe9NmJg3DGZBpB&q=85&s=62735e8fd3f1b3cdb680ae392a222625" alt="烧写设置 — USB 和电源连接" width="926" height="672" data-path="Ubuntu/images/update-software/iq9075-flashsetup.png" />

    4. 拨动**电源开关**打开设备。

    5. 确认设备处于 EDL 模式：
       ```shell theme={null}
       system_profiler SPUSBDataType | grep -A4 -i qualcomm
       ```
       **预期输出：**
       ```text theme={null}
       Product ID: 0x9008
       Vendor ID: 0x05c6  (Qualcomm, Inc)
       Manufacturer: Qualcomm CDMA Technologies MSM
       ```
       `Product ID: 0x9008` 确认设备处于 EDL 模式。如果未出现，请重新检查 SW2-3 和 USB-C 线缆。

    ### 配置 UFS（Provision）

    UFS（通用闪存存储）配置将内部存储划分为独立的逻辑单元号（LUN）。从 Qualcomm Linux 切换到 Ubuntu 时需要此步骤。

    如果满足以下任一情况，请运行 UFS 配置：

    * 这是一块**从未烧写过的全新板卡**。
    * 您正在**升级到新的镜像版本**。
    * 您正在**切换发行版**（Qualcomm Linux ↔ Ubuntu）。

    1. 下载 [**provision.zip**](https://artifacts.codelinaro.org/artifactory/codelinaro-le/Qualcomm_Linux/QCS8300/provision.zip) 并解压。

    2. 将 provision 文件和 QDL 二进制文件移动到同一个文件夹中，然后在该文件夹中运行：

           <Note>
             在 macOS 上，`qdl` 二进制文件及其支持库必须与 provision 文件位于同一目录。将 provision 文件复制到 `<qdl_dir>` 中，然后在那里运行命令。
           </Note>

       ```shell theme={null}
       <qdl_dir>/qdl --storage ufs prog_firehose_ddr.elf provision_1_3.xml
       ```

       **预期输出：**

       ```text theme={null}
       UFS provisioning succeeded
       ```

    <Note>
      UFS 配置完成后，设备会与 USB 断开连接。在继续之前，请关闭再打开电源开关，使其重新启动进入 EDL 模式。
    </Note>

    ### 烧写 CDT

    CDT 提供驱动和固件用于正确初始化平台的平台相关数据。

    1. 下载 [**IQ8275 CDT**](https://artifacts.codelinaro.org/artifactory/codelinaro-le/Qualcomm_Linux/QCS8300/cdt/qcs8275-iq-8275-evk-pro-sku.zip) 并解压。

    2. 在解压后的目录中烧写 CDT：
       ```shell theme={null}
       <qdl_dir>/qdl prog_firehose_ddr.elf rawprogram3.xml patch3.xml
       ```
       **预期输出：**
       ```text theme={null}
       flashed "cdt" successfully
       13 patches applied
       ```

    <Note>
      CDT 烧写完成后，设备会与 USB 断开连接。在继续之前，请关闭再打开电源开关，使其重新启动进入 EDL 模式。
    </Note>

    ### 烧写 SAIL 固件

    安全岛（SAIL）是一个独立、隔离的处理器，独立于主应用处理器处理安全关键功能。其固件位于专用的 **spinor** 闪存分区上。

    1. 进入镜像文件夹内的 `sail_nor` 子文件夹：
       ```shell theme={null}
       cd <path-to-image>/sail_nor
       ```

    2. 烧写 SAIL 固件：
       ```shell theme={null}
       <qdl_dir>/qdl --storage spinor prog_firehose_ddr.elf rawprogram0.xml patch0.xml
       ```
       **预期输出：**
       ```text theme={null}
       flashed "SAIL_HYP" successfully
       flashed "SAIL_SW1" successfully
       flashed "SAIL_HYP_BKUP" successfully
       flashed "SAIL_SW1_BKUP" successfully
       11 patches applied
       ```

    ### 烧写 Ubuntu

    1. 进入主镜像文件夹：
       ```shell theme={null}
       cd <path-to-image>
       ```

    2. 烧写镜像：
       ```shell theme={null}
       <qdl_dir>/qdl prog_firehose_ddr.elf rawprogram0.xml rawprogram1.xml rawprogram2.xml rawprogram3.xml rawprogram4.xml patch1.xml patch2.xml patch3.xml patch4.xml
       ```
       当最后一行显示如下内容时，烧写完成：
       ```text theme={null}
       partition 1 is now bootable
       ```
  </Tab>
</Tabs>

<Note>
  如果烧写在任何环节失败，请断开 USB 线缆和电源，重新连接后从 EDL 模式步骤开始重试。
</Note>

## 完成

1. **关闭** SW2-3 DIP 开关 — 向下推。
2. 对设备断电重启。它将启动进入新烧写的 Ubuntu 镜像。

## 后续步骤

继续前往[**设置设备**](../set-up-the-device)以连接串口控制台、验证软件版本，并启用网络、SSH 和显示。