Command-line tool for flashing firmware on Qualcomm-based devices via USB Emergency Download (EDL) mode
Command-line tool for flashing firmware on Qualcomm-based devices via USB Emergency Download (EDL) mode
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.
sudo apt install libxml2-dev libusb-1.0-0-dev libzip-dev meson ninja-build help2man
meson setup build
meson compile -C buildFor Homebrew users:
brew install libxml2 libusb libzip meson ninja help2man
meson setup build
meson compile -C buildFor MacPorts users:
sudo port install libxml2 libusb libzip meson ninja help2man
meson setup build
meson compile -C buildFirst, 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:
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-libzipThen use the meson tool to build QDL:
meson setup build
meson compile -C buildlibzip 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:
meson setup build -Dzip-container=disabledThe 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.
[!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:
usbipd listEach 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:
usbipd bind --busid Attaching the device to WSL does not require Administrator and can be run from inside WSL by calling the Windows binary:
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.
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:
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.
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:
qdl prog_firehose_ddr.elf rawprogram*.xml patch*.xmlIf you have multiple boards connected to the host, provide the serial number of
the board to flash through the --serial option:
qdl --serial=0AA94EFD prog_firehose_ddr.elf rawprogram*.xml patch*.xmlIf you have an installer package instead of individual binaries and XML definitions, you can flash this using the flash subcommand:
qdl flash If the installer package is unpacked it can be installed as:
qdl flash flashmap.jsonThese 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:
qdl flash installer.zip::layout1/ufsQDL also supports flashing builds described by contents.xml files:
qdl flash contents.xmlAs 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:
qdl flash contents.xml::ufs,safe_rtoswill flash the UFS storage with the only applicable flavor, and will flash safe_rtos onto the spinor.
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:
qdl create-zip installer.zip contents.xmlWhen 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:
qdl create-zip installer-ufs.zip contents.xml::ufsThe 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.
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):
qdl --dry-run prog_firehose_ddr.elf rawprogram*.xml patch*.xmlIn addition to flashing builds using their XML-based descriptions, QDL supports reading and writing binaries directly.
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.
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:
mkdir vip
qdl --create-digests=./vip prog_firehose_ddr.elf rawprogram*.xml patch*.xmlAs 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:
sectools mbn-tool generate --data DigestsToSign.bin --mbn-version 6 --outfile DigestsToSign.bin.mbn
sectools secure-image --sign DigestsToSign.bin.mbn --image-id=VIPPlease 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:
qdl --vip-table-path=./vip prog_firehose_ddr.elf rawprogram*.xml patch*.xmlNote that --vip-table-path and --create-digests are mutually exclusive.
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:
qdl --dry-run --vip-table-path=./vip prog_firehose_ddr.elf rawprogram*.xml patch*.xmlQDL 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.
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:
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.
qdl 13:prog_firehose_ddr.elf,42:the-answer rawprogram.xmlFlattened METAs include the various images that need to be loaded to enter Firehose mode, as well as a sahara_config
No open issues yet, or sync has not completed.