Skip to main content

​
Introduction

Provides a high-level overview of how to build firmware components from source and integrate them into the Qualcomm BSP image. It is intended for registered users with the appropriate licenses, as access to firmware sources is restricted. At a high level, you will learn the following:

​
Supported SoCs

The following SoCs are supported by this document. If your chipset is not listed, the firmware build process described here does not apply to your device.
SoCDescriptionSupported
QCS6490Qualcomm Dragonwing™ RB3 Gen 2 Vision Kit✓
Qualcomm Dragonwing™ RB3 Gen 2 Core Kit✓
Qualcomm Dragonwing™ RB3 Gen 2 Industrial Kit✓
QCS5430Qualcomm Dragonwing™ RB3 Gen 2 Lite Vision Kit✓
Qualcomm Dragonwing™ RB3 Gen 2 Lite Core Kit✓
IQ9Qualcomm Dragonwing™ IQ-9075 Evaluation Kit✓
IQ8Qualcomm Dragonwing™ IQ-8275 Evaluation Kit✓
IQ6Qualcomm Dragonwing™ IQ-615 Evaluation Kit✓
IQ-X7181Qualcomm Dragonwing™ IQ-X7181 Evaluation Kit✓
IQ-X5121Qualcomm Dragonwing™ IQ-X5121 Evaluation Kit✓

​
Host system requirements

  • Operating System
    • Ubuntu 22.04
  • Configuration
    • x86 machine
    • Quad-core CPU, for example, Intel i7-2600 at 3.4 GHz (equivalent or better)
    • 300 GB free disk space (swap partition > 32 GB)
    • 16 GB RAM
  • Tools
    • Git 1.8.3.1 or later versions
    • Tar 1.28 or later versions
    • Python 3.10.2 or later versions
    • GCC 10.1 or later versions
    • GNU Make 4.0 or later versions
    • Kas 4.8 or later versions
  • Permissions
    • sudo permission is required to run a few commands

​
Install QSC-CLI

qsc-cli is a command-line tool provided by Qualcomm that offers an end-to-end workflow for accessing, managing, and building Qualcomm software. Follow these steps to install qsc-cli on your system:
  • Register your Qualcomm email ID by visiting the Qualcomm Support Page.
  • Download the Debian package for qsc-cli: 
    wget https://softwarecenter.qualcomm.com/api/download/software/tools/Qualcomm_Software_Center/Linux/Debian/latest.deb -O qsc_installer.deb
  • Install the qsc-cli Debian package: 
    sudo apt update
sudo apt install ./qsc_installer.deb
  • Sign in to qsc-cli using your registered email ID: 
    qsc-cli login -u <username>

​
Host setup

The following instructions are intended for use on a Ubuntu host system. The Yocto build is also supported on other distributions compatible with Yocto, but no validation is performed against them.
  • Install the following packages to prepare your host environment for the Yocto build 
    sudo apt update
sudo apt install build-essential chrpath cpio debianutils diffstat \
     file gawk gcc git iputils-ping libacl1 locales python3 python3-git \
     python3-jinja2 python3-pexpect python3-pip python3-subunit socat \
     texinfo unzip wget xz-utils zstd
  • Qualcomm uses the kas tool to sync and build the Yocto project. Use the following commands to install kas on your system
    On older Ubuntu versions, the kas version provided by the system package manager may be outdated. Using pipx is the recommended way to install kas.
     sudo apt install pipx

 # Restart your shell session after running this command to ensure
 # path changes take effect
 pipx ensurepath

 # The kas version is expected to be 4.8 or higher
 pipx install "kas>=4.8"
  • The following packages are additionally required to compile firmware: 
    sudo apt-get install lib32stdc++6 libncurses5 checkinstall libreadline-dev \
     libncursesw5-dev libssl-dev libsqlite3-dev tk-dev libgdbm-dev libc6-dev \
     libbz2-dev libffi-dev curl
  • Use qsc-cli to obtain the PAT token for Chipcode access. This token expires in two weeks. 
    qsc-cli show-access-token
    Sample output
    user@hostname:/local/mnt/workspace$ qsc-cli show-access-token
[Info]: Starting qsc-cli version 0.0.0.9
5LThNlklb55mMVLB5C2KqUGU2jCF
  • Add the following entries to your ~/.netrc file to authenticate access to Chipcode repositories: 
    machine chipmaster2.qti.qualcomm.com
login <login-id>
password <access-token>

machine qpm-git.qualcomm.com
login <login-id>
password <access-token>
  • Update git configurations: 
    # Add the following git configurations to fetch large size repositories and to avoid unreliable connections
git config --global http.postBuffer 1048576000
git config --global http.maxRequestBuffer 1048576000
git config --global http.lowSpeedLimit 0
git config --global http.lowSpeedTime 999999
# Add the following git configurations to follow remote redirects from http-alternates files or alternates
git config --global http.https://chipmaster2.qti.qualcomm.com.followRedirects true
git config --global http.https://qpm-git.qualcomm.com.followRedirects true

​
Configuration parameters

The following table describes the build tags for the current release. These values will be need to be substituted in the build commands.
Release TagIdentifier
meta-qcom-release-tagqli-2.0
meta-qcom-extras-release-tagqli-2.0
firmware-release-tagr2.0_00007.2
firmware-release-tag (IQ-X7181/IQ-X5121)r2.0_00008.0

​
Map firmware source

The following tables describe the firmware distributions that you can download. For more information about the Yocto layers, see Qualcomm Linux metadata layers. Mapping access levels to firmware distributions
DistributionDescriptionYocto layers
Qualcomm_Linux.SPF.2.0|AP|Standard|OEM|NoModemHigh-level OS and firmware source (GPS only)meta-qcom
meta-qcom-distro
meta-qcom-extras
Qualcomm_Linux.SPF.2.0|AP|Standard|OEMHigh-level OS and firmware (GPS only) sourcemeta-qcom
meta-qcom-distro
meta-qcom-extras
Qualcomm_Linux.SPF.2.0|AMSS|Standard|OEMHigh-level OS and firmware (GPS and modem) sourcemeta-qcom
meta-qcom-distro
meta-qcom-extras
Mapping firmware distributions to git repositories
DistributionRepository URLClone Directory
Qualcomm_Linux.SPF.2.0|AP|Standard|OEM|NoModem|https://qpm-git.qualcomm.com/home2/git/qualcomm/qualcomm-linux-spf-2-0_ap_standard_oem_nomodem.gitqualcomm-linux-spf-2-0_ap_standard_oem_nomodem
Qualcomm_Linux.SPF.2.0|AP|Standard|OEM|https://qpm-git.qualcomm.com/home2/git/qualcomm/qualcomm-linux-spf-2-0_ap_standard_oem.gitqualcomm-linux-spf-2-0_ap_standard_oem
Qualcomm_Linux.SPF.2.0|AMSS|Standard|OEM|https://qpm-git.qualcomm.com/home2/git/qualcomm/qualcomm-linux-spf-2-0_amss_standard_oem.gitqualcomm-linux-spf-2-0_amss_standard_oem
Qualcomm_Linux.SPF.2.0|AP|Standard|OEM| and Qualcomm_Linux.SPF.2.0|AMSS|Standard|OEM| distributions are only supported on QCS6490 chipset.

​
Build firmware

  • Create a workspace directory for the firmware sources and navigate to it. All subsequent instructions assume this as the working directory. 
    mkdir -p <firmware-root>
cd <firmware-root>
  • Clone the firmware sources from Chipcode using the release tag and clone URL from the Firmware Source Mapping table. 
    git clone -b <firmware-release-tag> --depth 1 <clone-url>
  • Substitute the <firwmare-root> and <distro-clone-directory> in the following commands with the correct values based on the chosen access profile.
Prerequisites
  • Ensure that the working shell is bash: 
    echo $0
    The expected output of the command should be bash. If not, enter the bash shell. 
    bash
  • Install the libffi6 package using the following commands. This is required for the QAIC compiler, which generates the header and the source files from the IDL files. 
    curl -LO http://archive.ubuntu.com/ubuntu/pool/main/libf/libffi/libffi6_3.2.1-8_amd64.deb
sudo dpkg -i libffi6_3.2.1-8_amd64.deb
  • Install LLVM for AOP, Qualcomm® Trusted Execution Environment (TEE), and boot compilation: 
    cd <firmware-root>
mkdir llvm
# Sign in to qsc-cli and activate the license
qsc-cli login
qsc-cli tool activate-license --name sdllvm_arm
# LLVM requirement for boot compilation is 14.0.4
qsc-cli tool install --name sdllvm_arm --required-version 14.0.4 --path <firmware-root>/llvm/14.0.4
chmod -R 777 <firmware-root>/llvm/14.0.4
# LLVM requirement for the Qualcomm TEE compilation is 16.0.7
qsc-cli tool install --name sdllvm_arm --required-version 16.0.7 --path <firmware-root>/llvm/16.0.7
chmod -R 777 <firmware-root>/llvm/16.0.7
  • Export the SECTOOLS variable and compile the firmware builds (<firmware-root>/<distro-clone-directory> is the top-level directory): 
    export SECTOOLS=<firmware-root>/<distro-clone-directory>/QCM6490.LE.2.0/common/sectoolsv2/ext/Linux/sectools
export SECTOOLS_DIR=<firmware-root>/<distro-clone-directory>/QCM6490.LE.2.0/common/sectoolsv2/ext/Linux
  • Install and set up Qualcomm® Hexagon™ Processor. Set the environment variable HEXAGON_ROOT to the path where the Hexagon SDK is installed. To change the install path when using qsc-cli, see Change the Hexagon tool install path. 
    qsc-cli tool extract --name hexagon8.4 --required-version 8.4.07
qsc-cli tool extract --name hexagon8.4 --required-version 8.4.10
export HEXAGON_ROOT=$HOME/Qualcomm/HEXAGON_Tools
echo $HEXAGON_ROOT
Build aDSPTools required
  • Compiler version: Hexagon 8.4.07
  • Python version: Python 3.10.2
  • libffi6 package
Build steps
  • Nanopb integration (one-time setup): 
    cd <firmware-root>/<distro-clone-directory>/ADSP.HT.5.5.c8/adsp_proc/qsh_api
curl https://jpa.kapsi.fi/nanopb/download/nanopb-0.3.9.5-linux-x86.tar.gz -o nanopb-0.3.9.5-linux-x86.tar.gz
cd <firmware-root>/<distro-clone-directory>/ADSP.HT.5.5.c8/adsp_proc/
python qsh_api/build/config_nanopb_dependency.py -f nanopb-0.3.9.5-linux-x86
  • Go to the following directory: 
    cd <firmware-root>/<distro-clone-directory>/ADSP.HT.5.5.c8/adsp_proc/build/ms
  • Clean the build: 
    python ./build_variant.py kodiak.adsp.prod --clean
  • Build the image: 
    python ./build_variant.py kodiak.adsp.prod
Build BootTools required
  • Compiler version: LLVM version must be updated to 14.0.4 
    export LLVM=<firmware-root>/llvm/14.0.4/
  • Python version: Python 3.10
  • libffi6 package
Build steps
  • Install the device tree compiler: 
    sudo apt-get install device-tree-compiler
export DTC=/usr/bin
  • Go to the following directory: 
    cd <firmware-root>/<distro-clone-directory>/BOOT.MXF.1.0.c1/
  • Install the dependencies: 
    python -m pip install -r boot_images/boot_tools/dtschema_tools/oss/requirements.txt
pip install json-schema-for-humans
  • Clean the build: 
    python -u boot_images/boot_tools/buildex.py -t kodiak,QcomToolsPkg -v LAA -r RELEASE --build_flags=cleanall
  • Build the image: 
    python -u boot_images/boot_tools/buildex.py -t kodiak,QcomToolsPkg -v LAA -r RELEASE
    For debug variant builds, replace RELEASE with DEBUG.
Build Qualcomm TEE firmwareTools required
  • Compiler version: LLVM 16.0.7
  • Python version: Python 3.10
Build steps
  • Install LLVM: 
    cd <firmware-root>/<distro-clone-directory>/TZ.XF.5.29.1/trustzone_images/build/ms/
vi build_config_deploy_kodiak.xml
# Edit all the occurrences of /pkg/qct/software/llvm/release/arm/16.0.7/ to <firmware-root>/llvm/16.0.7/
  • Clean the build: 
    python build_all.py -b TZ.XF.5.0 CHIPSET=kodiak --cfg=build_config_deploy_kodiak.xml --clean
  • Build the image: 
    cd <firmware-root>/<distro-clone-directory>/TZ.XF.5.29.1/trustzone_images/build/ms/
python build_all.py -b TZ.XF.5.0 CHIPSET=kodiak --cfg=build_config_deploy_kodiak.xml
Build AOP firmwareTools required
  • Compiler version: LLVM 14.0.4
  • Python version: Python 3.10
Build steps
  • Go to the following directory: 
    cd <firmware-root>/<distro-clone-directory>/AOP.HO.3.6/aop_proc/build/
  • Clean the build: 
    ./build_kodiak.sh -c -l <firmware-root>/llvm/14.0.4/
  • Build the image: 
    ./build_kodiak.sh -l <firmware-root>/llvm/14.0.4/
Build MPSS
This step is only applicable for Qualcomm_Linux.SPF.2.0|AMSS|Standard|OEM|.
Tools required
  • Compiler version: Hexagon 8.4.10
  • Python version: Python 3.8.2
Build steps
  • Nanopb integration (one-time setup): 
    cd <firmware-root>/<distro-clone-directory>/MPSS.HI.4.3.3.c6.2/modem_proc/ssc_api
curl https://jpa.kapsi.fi/nanopb/download/nanopb-0.3.9.5-linux-x86.tar.gz -o nanopb-0.3.9.5-linux-x86.tar.gz
cd <firmware-root>/<distro-clone-directory>/MPSS.HI.4.3.3.c6.2/modem_proc
python ssc_api/build/config_nanopb_dependency.py -f  nanopb-0.3.9.5-linux-x86
  • Go to the following directory: 
    cd <firmware-root>/<distro-clone-directory>/MPSS.HI.4.3.3.c6.2/modem_proc/build/ms
  • Clean the build: 
    python build_variant.py kodiak.gen.prod --clean
  • Build the image: 
    python build_variant.py kodiak.gen.prod bparams=-k
CPUCP firmwareQualcomm releases the CPUCP firmware as a binary and you don’t need to compile the build.CPUSYS.VM firmwareQualcomm releases the CPUSYS.VM firmware as a binary and you don’t need to compile the build.BTFM firmwareQualcomm releases the BTFM firmware as a binary and you don’t need to compile the build.WLAN firmwareQualcomm releases the WLAN firmware as a binary and you don’t need to compile the build.Generate firmware prebuilts (boot-critical and split-firmware binaries)
  • Create an integrated firmware binary from the individual components that you compiled: 
    cd <firmware-root>/<distro-clone-directory>/QCM6490.LE.2.0/common/build
python build.py --imf
  • Firmware prebuilt is successful if the following zip files are generated in the <firmware-root>/<distro-clone-directory>/QCM6490.LE.2.0/common/build/ufs/bin directory:
    • QCM6490_bootbinaries.zip
    • QCM6490_dspso.zip
    • QCM6490_fw.zip

​
Build BSP image

This section describes how to integrate firmware binaries and other source components into a full BSP image build. The BSP image build combines the compiled firmware outputs from the previous step with the Yocto layer stack, producing a flashable image that includes all required binaries.
IQ-X7181 and IQ-X5121 aren’t supported by the meta-qcom-extras layer yet; to load custom firmware binaries on these boards, use devtool to modify the upstream recipes instead.
  • Download Qualcomm’s Yocto layer meta-qcom-extras. For the latest <meta-qcom-extras-release-tag>, see Configuration Parameters. 
    git clone https://qpm-git.qualcomm.com/home2/git/component-revision-history/qualcomm-linux/meta-qcom-extras.git -b <meta-qcom-extras-release-tag> --depth 1
Layer Setup
  • Set your Qualcomm Customer ID. To find it, sign in at qualcomm.com, click the Profile icon, select Account Settings, and scroll to the Company Information section. 
    export CUST_ID="<CUST_ID>"
  • Set the outbound license for the layer and its checksum. CUST_LICENSE and CUST_LIC_CHKSUM are required for every recipe in the layer. 
    export CUST_LICENSE="<CUST_LICENSE>"
export CUST_LIC_CHKSUM="<CUST_LIC_CHKSUM>"
  • Export NETRC_FILE parameter to ensure ~/.netrc credentials are visible in the kas environment: 
    export NETRC_FILE=~/.netrc
  • Update the license file in the source repositories. By default, all sources used by meta-qcom-extras contain a placeholder LICENSE file. Replace it with your outbound license in each source before building. The recipes verify CUST_LICENSE against this file at build time.
Firmware Setup
  • Set FWZIP_PATH to the directory containing the firmware ZIP files to include locally compiled firmware zip paths in the build. 
    export FWZIP_PATH="<FWZIP_PATH>"
  • Override Linux-firmware Binaries If you want to modify the Linux firmware binaries, use this section to substitute them into the build.
    • Create a kas configuration file at meta-qcom-extras/ci/firmware.yml with the following content: 
      cat << EOF > meta-qcom-extras/ci/firmware.yml
header:
 version: 14

local_conf_header:
 firmware-build: |
   SRCREV:pn-linux-firmware = "dc85ccedc9c973682fbcf4d628ca61174bcc3120"
EOF
    • Then modify the linux-firmware recipe using devtool: 
      kas shell -c "devtool modify linux-firmware" meta-qcom-extras/ci/iq-x7181-evk.yml:meta-qcom-extras/ci/qcom-distro.yml:meta-qcom-extras/ci/performance.yml:meta-qcom-extras/ci/firmware.yml
    • Unzip the firmware archive: 
      unzip $FWZIP_PATH/HAMOA_fw.zip -d $FWZIP_PATH
    • Copy the contents of the firmware zip file into the devtool workspace 
      cp $FWZIP_PATH/HAMOA_fw/lib/firmware/qcom/x1e80100/*.{mbn,jsn} build/workspace/sources/linux-firmware/qcom/x1e80100/
      When you override the firmwares in linux-firmware, you must also override the Hexagon DSP binaries.
  • Override DSPSO Binaries If you want to modify the Hexagon DSP shared-object binaries, use this section to substitute the ADSP and CDSP binaries into the build.
    • Initialize a devtool workspace for hexagon-dsp-binaries: 
      kas shell -c "devtool modify hexagon-dsp-binaries" meta-qcom-extras/ci/iq-x7181-evk.yml:meta-qcom-extras/ci/qcom-distro.yml:meta-qcom-extras/ci/performance.yml
    • Unzip the firmware archive: 
      unzip $FWZIP_PATH/HAMOA_fw.zip -d $FWZIP_PATH
    • Copy the ADSP binaries into the devtool workspace: 
      cp -r $FWZIP_PATH/HAMOA_fw/usr/share/qcom/x1e80100/Qualcomm/X1E80100/dsp/adsp/* build/workspace/sources/hexagon-dsp-binaries/x1e80100/Qualcomm/Hamoa-IoT-EVK/ADSP.HT.5.9-00839-HAMOA-1/
    • Copy the CDSP binaries into the devtool workspace: 
      cp -r $FWZIP_PATH/HAMOA_fw/usr/share/qcom/x1e80100/Qualcomm/X1E80100/dsp/cdsp/* build/workspace/sources/hexagon-dsp-binaries/x1e80100/Qualcomm/Hamoa-IoT-EVK/CDSP.HT.2.9.c1-00069-HAMOA-1/
  • Override Boot Firmware Binaries If you want to modify the boot-critical firmware binaries, use this section to substitute them into the build.
    • Initialize a devtool workspace for the boot firmware recipe: 
      kas shell -c "devtool modify firmware-qcom-boot-iq-x7181" meta-qcom-extras/ci/iq-x7181-evk.yml:meta-qcom-extras/ci/qcom-distro.yml:meta-qcom-extras/ci/performance.yml
    • Unzip the boot binaries archive: 
      unzip $FWZIP_PATH/HAMOA_bootbinaries.zip -d $FWZIP_PATH
    • Copy boot binaries into the devtool workspace: 
      cp -r $FWZIP_PATH/HAMOA_bootbinaries/* build/workspace/sources/firmware-qcom-boot-iq-x7181
      Then append the required configuration to the .bbappend file: 
      echo 'ALLOW_EMPTY:${PN} = "1"' >> build/workspace/appends/firmware-qcom-boot-iq-x7181_00012.bbappend
Once all override steps are complete, the subsequent Yocto image build will automatically use the locally provided firmware binaries rather than upstream sources.Build Image
  • Run the setup script to apply these parameters to the build environment. 
    meta-qcom-extras/setup_extras_config.sh
  • Build the software image using kas. You define build targets based on machine and distro combinations. 
    kas shell -c "devtool build-image qcom-multimedia-proprietary-image" meta-qcom-extras/ci/iq-x7181-evk.yml:meta-qcom-extras/ci/qcom-distro.yml:meta-qcom-extras/ci/performance.yml