Flash software images - Qualcomm Dragonwing Documentation

Introduction

Flash a prebuilt image onto a device. While Qualcomm hardware typically comes with a preloaded image, you can use this procedure to update to a newer software version or deploy images built from source. To flash a prebuilt image, the following steps are required:

Download the packages required for flashing the image – Download Required Packages
Obtain flashable image – Obtain Flashable Image
Identify storage configuration for your device – Identify Storage Configuration
Update the udev rules on the host system – Configure udev rules
Select the appropriate CDT based on the reference kit – Configure CDT
Switch device to EDL mode – Switch device to EDL Mode
Provision UFS – Provision UFS
Flash SAIL – Flash SAIL
Flash software image – Flash software image

Download required packages

QDL is a software utility used to communicate with Qualcomm USB devices in Emergency Download (EDL) mode, enabling you to upload a flash loader and program software images onto the device. Follow these steps to download and setup QDL on your system:

Navigate to QDL’s Releases Page and find the appropriate binary link based on your machine and architecture.
Download the QDL binary using the following command:
wget <qdl-binary-download-url> -O qdl.zip
Unzip the downloaded archive:
unzip qdl.zip

Provide execute permission to the QDL binary:

chmod +x "$PWD/<unzipped-qdl-directory>/qdl"

Add the QDL executable to your system PATH:

export PATH="$PATH:$PWD/<unzipped-qdl-directory>"

Verify that the QDL executable is accessible:
qdl --version

Obtain flashable image

Before flashing, you need a flashable image directory on your host machine. Depending on how you obtained your image, choose one of the following paths.

Prebuilt Image
Compiled Image

Prebuilt images are distributed as compressed archives. Download the archive for your device from the Obtain Prebuilt Images section, extract the archive, and go to the extracted directory.

Extract the archive:
unzip <prebuilt-image>.zip

Go to the extracted directory:

cd <unzipped-image-directory>/images/<machine>/<image>-<machine>

After a successful build, the flashable image directory is already present in your build output. Navigate directly to it.

cd build/tmp/deploy/images/<machine>/<image>-<machine>.rootfs.qcomflash

All subsequent instructions are expected to be run from this directory unless stated otherwise.

Identify storage configuration

Machine configurations come with either UFS or eMMC storage enabled by default, and these settings are reflected in the prebuilt images. If you need to modify the storage type, you must update the configuration and rebuild the image, as this cannot be changed in prebuilt binaries. The default storage configurations for supported platforms are

Machine	Storage Type
IQ-9075-EVK	UFS
IQ-8275-EVK	UFS
QCS6490	UFS
IQ-615-EVK	EMMC
IQ-X7181-EVK	UFS/SPINOR
IQ-X5121-EVK	UFS/SPINOR

Configure udev rules

The host system must have the correct udev rules configured to allow proper USB device access. This step is only required when setting up a new host environment or when encountering permission issues while detecting the device over USB.

Run the following command to configure the udev USB rules for the Qualcomm manufacturing vendor ID 05c6 on the Linux host:

echo 'SUBSYSTEMS=="usb", ATTRS{idVendor}=="05c6", ATTRS{idProduct}=="9008", MODE="0666", GROUP="plugdev"' | sudo tee /etc/udev/rules.d/51-qcom-usb.rules

Restart the udev service for the changes to take effect:
sudo systemctl restart udev
If the USB cable is already connected to the host, unplug and reconnect it for the updated rules to take effect.

Configure CDT

The configuration data table (CDT) contains device-specific information required for proper platform initialization. You need to select the correct CDT file based on your reference kit before flashing.

QCS6490/QCS5430
IQ-X7181/IQ-X5121
Other Kits

Multiple CDT binaries are provided as part of the qcomflash tarball. Choose the correct CDT binary for your kit and replace the default cdt.bin with the appropriate one.
cp cdt_core_kit.bin cdt.bin
cp cdt_vision_kit.bin cdt.bin
cp cdt_industrial_kit.bin cdt.bin
cp cdt_industrial_mezz_kit.bin cdt.bin
After the entire flashing process succeeds, you can verify that the correct CDT is loaded by reviewing the UEFI serial logs. Use the Subtype field to identify the CDT loaded onto your device.
Sample output
Platform Init [ 1966] BDS Platform : IOT Subtype : 2 Boot Device : UFS Chip Name : QCS6490 Chip Ver : 1.0
Subtype Platform Description
2 Vision Kit (Moselle attach)
5 RB3Gen2 Core Kit (HSP attach)
7 Vision Kit (HSP attach)
9 Industrial Kit
13 Industrial Mezz Kit

Subtype	Platform Description
2	Vision Kit (Moselle attach)
5	RB3Gen2 Core Kit (HSP attach)
7	Vision Kit (HSP attach)
9	Industrial Kit
13	Industrial Mezz Kit

Download the CDT binary from CodeLinaro:

curl -OL https://artifacts.codelinaro.org/artifactory/codelinaro-le/Qualcomm_Linux/X1E80100/cdt/IQ-X.1.4-EVK-CDT.tar.gz

Extract the tarball archive:
tar -xzf IQ-X.1.4-EVK-CDT.tar.gz
Go to the extracted directory:
cd IQ-X.1.4-EVK-CDT

Flash the CDT:

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

Navigate back to the previous directory:
cd ..

For IQ-9075, IQ-8275, and IQ-615 kits, the default cdt.bin included in the qcomflash tarball is already the correct CDT for your kit. No action is required to select a CDT before flashing.

Switch device to EDL mode

The device must be in the EDL mode before you flash the software image. The Qualcomm supported device by default enters EDL mode if there is no image on the device after power up or if it’s corrupted. Follow these steps to force the device into EDL mode.

QCS6490/QCS5430
IQ-9075
IQ-8275
IQ-615
IQ-X7181/IQ-X5121

Press and hold the F_DL button.
Connect the device to a +12 V wall power supply.
Connect the device to the host system through the USB Type-C connector.
Release the F_DL button. The device is now in EDL mode.
Unplug the power cable once the entire flashing process is complete to exit EDL mode.

Verify if the device is in EDL mode by running the following command:

lsusb

Expected output

Bus 002 Device 014: ID 05c6:9008 Qualcomm, Inc. Gobi Wireless Modem (QDL mode)

Provision UFS

Universal flash storage (UFS) provisioning helps to divide the storage into many LUNs, which stores different types of data separately. This improves access efficiency and system organization. UFS is provisioned by default. If there are any changes in LUNs, UFS must be re-provisioned. To check if UFS needs to be re-provisioned, see the table UFS Provision in the Release Specific Information document.

Download the provision file from Qualcomm’s artifacts server:

wget https://artifacts.codelinaro.org/artifactory/codelinaro-le/Qualcomm_Linux/QCS9100/provision.zip

wget https://artifacts.codelinaro.org/artifactory/codelinaro-le/Qualcomm_Linux/QCS8300/provision.zip

wget https://artifacts.codelinaro.org/artifactory/codelinaro-le/Qualcomm_Linux/QCS6490/provision.zip

wget https://artifacts.codelinaro.org/artifactory/codelinaro-le/Qualcomm_Linux/X1E80100/provision_default.zip

wget https://artifacts.codelinaro.org/artifactory/codelinaro-le/Qualcomm_Linux/X1E80100/provision_default.zip

Unzip the downloaded archive:
unzip provision.zip -d provision
Go to the extracted directory:
cd provision

Provision UFS:

qdl --storage ufs prog_firehose_ddr.elf provision_1_2.xml

qdl --storage ufs prog_firehose_ddr.elf provision_1_3.xml

qdl --storage ufs prog_firehose_ddr.elf provision_1_3.xml

qdl --storage ufs xbl_s_devprg_ns.melf provision.xml

qdl --storage ufs xbl_s_devprg_ns.melf provision.xml

Navigate back to the previous directory:
cd ..

Flash SAIL

Safety Island (SAIL) image contains the isolated, safety‑critical firmware that runs on the dedicated safety island to ensure secure boot and reliable system operation are independent of the main processor.

Safety Island (SAIL) is applicable only for the Qualcomm Dragonwing™ IQ-9075 and the Qualcomm Dragonwing™ IQ-8275 development kits. If you’re not using one of these development kits, skip this section.

The SAIL artifacts are present under the sail_nor directory within the unpacked qcomflash directory. Go to the following directory:
cd sail_nor

Flash the SAIL:

qdl --storage spinor prog_firehose_ddr.elf rawprogram0.xml patch0.xml

Navigate back to the previous directory:
cd ..