Flash software images - Qualcomm Dragonwing Documentation

This document covers the instructions for flashing on UNIX based systems only. Refer to the instructions in the device specific guides for instructions to flash on Windows host systems.

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:

Download the QDL binary from the Qualcomm Software Center using the following command:

wget https://softwarecenter.qualcomm.com/api/download/software/tools/Qualcomm_Device_Loader/Linux/Debian/latest.zip -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.

IQ-X7181/IQ-X5121
Other Kits

Download the CDT binary from CodeLinaro:

curl 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 xbl_s_devprg_ns.melf rawprogram0.xml patch0.xml

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.
Sample command
```
cp cdt_vision_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)
6 RB3Gen2 Core Kit (Moselle attach)
7 Vision Kit (HSP attach)
13 Industrial Mezz Kit

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

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 using a Type-C cable 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
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

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