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

# 使用 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>

## 所需物品

* IQ-8275 EVK 及 12 V 电源
* 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. 下载 [QDL Linux (x64) 版工具](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-staging/5j1H6H_NhFpsAqlq/Ubuntu/images/update-software/EDL_mode_dipSwitch.png?fit=max&auto=format&n=5j1H6H_NhFpsAqlq&q=85&s=7666336098a794613ac56cb983d2b763" 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-staging/5j1H6H_NhFpsAqlq/Ubuntu/images/update-software/iq9075-flashsetup.png?fit=max&auto=format&n=5j1H6H_NhFpsAqlq&q=85&s=d11911775c7c31ca0a9f187387aec95c" 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(Universal Flash Storage)分区配置将内部存储划分为独立的逻辑单元号(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 固件

    Safety Island(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. 下载 [QDL Windows 版工具](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-staging/zh/Ubuntu/images/update-software/win_bat.png" alt="运行 install_driver.bat" />

    ### 使设备进入 EDL 模式

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

           <img src="https://mintcdn.com/qualcomm-staging/5j1H6H_NhFpsAqlq/Ubuntu/images/update-software/EDL_mode_dipSwitch.png?fit=max&auto=format&n=5j1H6H_NhFpsAqlq&q=85&s=7666336098a794613ac56cb983d2b763" 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-staging/5j1H6H_NhFpsAqlq/Ubuntu/images/update-software/iq9075-flashsetup.png?fit=max&auto=format&n=5j1H6H_NhFpsAqlq&q=85&s=d11911775c7c31ca0a9f187387aec95c" 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-staging/5j1H6H_NhFpsAqlq/Ubuntu/images/update-software/dm_IQ9075_enum.jpg?fit=max&auto=format&n=5j1H6H_NhFpsAqlq&q=85&s=555275a3a782cc9199167679a5405853" alt="设备管理器 — 确认 EDL 模式" width="1027" height="848" data-path="Ubuntu/images/update-software/dm_IQ9075_enum.jpg" />

    ### 配置 UFS(Provision)

    UFS(Universal Flash Storage)分区配置将内部存储划分为独立的逻辑单元号(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 固件

    Safety Island(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. 下载 [QDL macOS(Apple Silicon)版工具](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-staging/5j1H6H_NhFpsAqlq/Ubuntu/images/update-software/EDL_mode_dipSwitch.png?fit=max&auto=format&n=5j1H6H_NhFpsAqlq&q=85&s=7666336098a794613ac56cb983d2b763" 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-staging/5j1H6H_NhFpsAqlq/Ubuntu/images/update-software/iq9075-flashsetup.png?fit=max&auto=format&n=5j1H6H_NhFpsAqlq&q=85&s=d11911775c7c31ca0a9f187387aec95c" 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(Universal Flash Storage)分区配置将内部存储划分为独立的逻辑单元号(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 固件

    Safety Island(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 和显示。