百科.dev
全部条目在线工具AI 编程趋势榜开源项目技术资讯提交条目
登录
< 返回工具列表
Q

qdl

> 编程语言
开源

通过 USB 紧急下载(EDL) 模式在 Qualcomm 设备上闪出固件的命令行工具

398 stars0 点赞1 次浏览
访问官网GitHub

工具介绍

通过 USB 紧急下载(EDL) 模式在 Qualcomm 设备上闪出固件的命令行工具

Qualcomm Download

This tool communicates with Qualcomm EDL USB devices (Vendor ID 05c6, Product IDs 9008, 900e, 901d, 90db) to upload a flash loader and use it to flash images.

Build

Linux

bash
sudo apt install libxml2-dev libusb-1.0-0-dev libzip-dev meson ninja-build help2man
meson setup build
meson compile -C build

MacOS

For Homebrew users:

bash
brew install libxml2 libusb libzip meson ninja help2man
meson setup build
meson compile -C build

For MacPorts users:

bash
sudo port install libxml2 libusb libzip meson ninja help2man
meson setup build
meson compile -C build

Windows

First, install the MSYS2 environment. Then, run the MSYS2 MinGW64 terminal (located at \mingw64.exe) and install additional packages needed for QDL compilation using the pacman tool:

bash
pacman -S base-devel --needed
pacman -S git
pacman -S help2man
pacman -S mingw-w64-x86_64-gcc
pacman -S mingw-w64-x86_64-meson
pacman -S mingw-w64-x86_64-ninja
pacman -S mingw-w64-x86_64-libusb
pacman -S mingw-w64-x86_64-libxml2
pacman -S mingw-w64-x86_64-libzip

Then use the meson tool to build QDL:

bash
meson setup build
meson compile -C build

Build options

libzip is only needed for zip container support - flashing directly from zip archives and the create-zip subcommand. The feature is enabled by default, so configuring fails if libzip is missing. To build a leaner QDL without it, explicitly disable the zip-container feature:

bash
meson setup build -Dzip-container=disabled

Use QDL

EDL mode

The device intended for flashing must be booted into Emergency Download (EDL) mode. EDL is a special boot mode available on Qualcomm-based devices that provides low-level access for firmware flashing and recovery. It bypasses the standard boot process, allowing operations such as flashing firmware even on unresponsive devices or those with locked bootloaders.

Please consult your device's documentation for instructions on how to enter EDL mode.

Flashing from WSL2 (usbipd-win)

[!WARNING] This is unreliable with current usbipd-win.

See:

On Windows, QDL can run inside a WSL2 distribution, but WSL2 does not see USB devices by default - they must be forwarded from the Windows host with usbipd-win. Install it on the Windows side (winget install usbipd), then forward the EDL device into WSL.

EDL devices enumerate under Vendor ID 05c6 with Product ID 9008 (Firehose), 900e (crash dump), 90db (diag dump), or 901d. From a Windows terminal, list the connected devices and note the BUSID of the EDL device:

powershell
usbipd list

Each device must be bound once before it can be attached. Binding requires an elevated (Administrator) PowerShell, but it persists across reboots, so this is a one-time step per device:

powershell
usbipd bind --busid 

Attaching the device to WSL does not require Administrator and can be run from inside WSL by calling the Windows binary:

bash
usbipd.exe attach --wsl --busid 

Once attached, the device appears in WSL (check with lsusb for 05c6:9008) and QDL can flash it as usual.

Re-attaching after EDL re-enumeration

The EDL device is a USB gadget that only exists while the board is in EDL mode. Whenever the board re-enters EDL - including after QDL finishes and the target reboots - the USB device is torn down and re-created. The bind persists, but the attach is dropped, and the host may assign a different BUSID than before. A QDL run that reports no device found is almost always this: the device simply needs to be re-attached.

After each entry into EDL, re-detect the BUSID and attach again. This can be scripted from WSL so the BUSID does not have to be looked up by hand:

bash
BUSID=$(usbipd.exe list | grep -iE '9008|900e|901d|90db' |
        awk '{print $1}' | tr -d '\r')
usbipd.exe attach --wsl --busid "$BUSID"

If you flash repeatedly, run this re-attach step before every qdl invocation.

Flash device

Run QDL with the --help option to view detailed usage information.

Below is an example of how to invoke QDL to flash a FLAT build:

bash
qdl prog_firehose_ddr.elf rawprogram*.xml patch*.xml

If you have multiple boards connected to the host, provide the serial number of the board to flash through the --serial option:

bash
qdl --serial=0AA94EFD prog_firehose_ddr.elf rawprogram*.xml patch*.xml

Flashing installer packages

If you have an installer package instead of individual binaries and XML definitions, you can flash this using the flash subcommand:

bash
qdl flash 

If the installer package is unpacked it can be installed as:

bash
qdl flash flashmap.json

These can of course be combined with e.g. --serial.

A subset of the installer package can be selected for installation by appending a ::storage1[,storage2...] suffix to the file name.

If a flashmap contains multiple layouts, select the desired layout by appending ::layout-name. The layout selector can be combined with storage filters using ::layout-name/storage1[,storage2...], for example:

bash
qdl flash installer.zip::layout1/ufs

Flashing contents.xml

QDL also supports flashing builds described by contents.xml files:

bash
qdl flash contents.xml

As the contents XML can describe the content for multiple storage types and multiple flavors, it might be necessary to select which content to flash. This is done by appending the ::specifier1,specifier2... suffix to the file name. The specifier is matched against storage types and flavors. At most one resolved specifier per storage is allowed, and only the selected parts are flashed. As an example:

bash
qdl flash contents.xml::ufs,safe_rtos

will flash the UFS storage with the only applicable flavor, and will flash safe_rtos onto the spinor.

Creating installer packages

QDL can also create installer packages from builds described by contents.xml files. The generated zip contains a flashmap.json, the selected programmer images, and the referenced rawprogram, patch, and image files:

bash
qdl create-zip installer.zip contents.xml

When the contents XML describes multiple storage or flavor combinations, select the desired content with the same ::specifier1,specifier2... suffix used for flashing contents XML files:

bash
qdl create-zip installer-ufs.zip contents.xml::ufs

The resulting archive can be flashed later with qdl flash installer.zip. Creating and flashing zip archives requires QDL to be built with libzip support, which is enabled by default.

Flash simulation (dry run)

Use the --dry-run option to run QDL without connecting to or flashing any device. This is useful for validating your XML descriptors and programmer arguments, or for generating VIP digest tables (see below):

bash
qdl --dry-run prog_firehose_ddr.elf rawprogram*.xml patch*.xml

Reading and writing raw binaries

In addition to flashing builds using their XML-based descriptions, QDL supports reading and writing binaries directly.

bash
qdl prog_firehose_ddr.elf [read | write] [address specifier] ...

Multiple read and write commands can be specified at once. The address specifier can take the forms:

  • N - single number, specifies the physical partition number N, starting at sector 0. To read data, the number of sectors must be specified explicitly using the N/S+L form.

  • N/S - two numbers, specifies the physical partition number N and the start sector S. To read data, the number of sectors must be specified explicitly using the N/S+L form.

  • N/S+L - three numbers, specifies the physical partition number N, the start sector S and the number of sectors L, that binary should be written to, or which should be read into binary.

  • partition name - a string, will match against partition names across the GPT partition tables on all physical partitions.

  • N/partition_name - a number followed by a string, will match against partition names of the GPT partition table in the specified physical partition N.

Validated Image Programming (VIP)

QDL supports Validated Image Programming (VIP) mode, which is activated when Secure Boot is enabled on the target. VIP controls which packets are allowed to be issued to the target by hashing all received data and comparing each resulting digest against the next entry in a pre-loaded digest table. If the digest matches, the packet is accepted; otherwise, the packet is rejected, and the target halts.

To use VIP programming, a digest table must be generated prior to flashing the device. To generate a table of digests, run QDL with the --create-digests option, providing a path to store the VIP tables. Note that --create-digests implicitly enables dry-run mode, so no device connection is required:

bash
mkdir vip
qdl --create-digests=./vip prog_firehose_ddr.elf rawprogram*.xml patch*.xml

As a result, three types of files are generated:

  • DIGEST_TABLE.bin - contains the SHA256 table of digests for all Firehose packets to be sent to the target. It is an intermediary table and is used only for the subsequent generation of DigestsToSign.bin and ChainedTableOfDigests.bin files, and is not used directly by QDL for VIP programming.

  • DigestsToSign.bin - first 53 digests + SHA256 hash of ChainedTableOfDigests0.bin. This file must be converted to MBN format and then signed with sectools:

    bash
    sectools mbn-tool generate --data DigestsToSign.bin --mbn-version 6 --outfile DigestsToSign.bin.mbn
    sectools secure-image --sign DigestsToSign.bin.mbn --image-id=VIP

    Please check the security profile for your SoC to determine which version of the MBN format should be used.

  • ChainedTableOfDigests.bin - contains the remaining digests, split across multiple files of up to 255 digests each. Non-final files have the SHA256 hash of the next chained table appended. The final file has a trailing zero byte appended to ensure its size is not a multiple of the sector size.

To flash a board using VIP mode, provide the path where the previously generated and signed tables are stored using the --vip-table-path option:

bash
qdl --vip-table-path=./vip prog_firehose_ddr.elf rawprogram*.xml patch*.xml

Note that --vip-table-path and --create-digests are mutually exclusive.

Validating VIP tables without hardware

Before flashing a real device it is possible to verify that the signed digest tables match the data that will be sent, using --dry-run together with --vip-table-path:

bash
qdl --dry-run --vip-table-path=./vip prog_firehose_ddr.elf rawprogram*.xml patch*.xml

QDL will simulate the full Firehose session, compute SHA256 over every packet it would send, and compare each hash against the corresponding entry in the loaded digest tables. Any mismatch is reported to stderr. All mismatches are printed before the run exits so that every problem is visible at once.

This catches table/data mismatches early -- before committing to a real flash -- and is useful both as a local sanity check and as a step in CI pipelines.

Multi-programmer targets

On some targets multiple files need to be loaded in order to reach the Firehose programmer; these targets will request multiple images over Sahara. Three mechanisms for providing these images are provided:

Command line argument

The programmer argument allows specifying a comma-separated list of colon-separated "id" and "filename" pairs. Each filename should refer to the Sahara image of the specified Sahara image id.

bash
qdl 13:prog_firehose_ddr.elf,42:the-answer rawprogram.xml

Sahara configuration XML file

Flattened METAs include the various images that need to be loaded to enter Firehose mode, as well as a sahara_config

Issues· 20 开放

查看全部 Issues在 GitHub 打开

暂无开放 Issues,或尚未同步最近议题。

> 标签

Cbootloadercommand-linedevice-recoveryedl

暂无评论,来聊聊你的看法吧

> 工具信息

发布日期2026年8月1日
最后更新2026年9月17日
分类编程语言
定价开源

> 相关工具

T
TypeScript
JavaScript 的超集,为前端与全栈提供静态类型
P
Python
通用编程语言,广泛用于 Web、数据与 AI
G
Go
Google 推出的简洁高效系统语言