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. Firmware sources are available to users that have signed the required agreements. If you don’t yet have access, create a Qualcomm ID and see the Working with Qualcomm page to learn more about account verification and access levels. 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.

​
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:
  • Install the qsc-cli Debian package:
  • Sign in to qsc-cli using your Qualcomm ID. For most users, your Qualcomm ID is your email address. This opens a browser window to complete authentication. If the browser doesn’t open automatically, copy the link printed in the terminal and paste it into your browser to complete authentication.

​
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
  • Qualcomm uses the kas tool to sync and build the Yocto project. Use the following steps 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.
    1. Install pipx
    2. Add the pipx install location to your PATH
      This command updates your shell’s startup file, so the change only takes effect in new shell sessions. Restart your shell session before continuing to the next step.
    3. Install kas (version 4.8 or higher is required)
  • Verify if the kas installation is successful.
  • The following packages are additionally required to compile firmware:
  • Use qsc-cli to obtain the PAT token for Chipcode access. This token expires in two weeks.
    Sample output
  • Add the following entries to your ~/.netrc file to authenticate access to Chipcode repositories:
  • Update git configurations:

​
Configuration parameters

The following table describes the build tags for the current release. These values need to be substituted in the build commands.

​
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 Mapping firmware distributions to git repositories
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.
  • Clone the firmware sources from Chipcode using the release tag and clone URL from the Firmware Source Mapping table.
  • 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:
    The expected output of the command should be bash. If not, enter the bash shell.
  • 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.
  • Install LLVM for AOP, Qualcomm® Trusted Execution Environment (TEE), and boot compilation:
  • Export the SECTOOLS variable and compile the firmware builds (<firmware-root>/<distro-clone-directory> is the top-level directory):
  • 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.
Build cDSPTools required
  • Compiler version: Hexagon 8.4.07
  • Python version: Python 3.10.2
  • libffi6 package
Build steps
  • Go to the following directory:
  • Clean the build:
  • Build the image:
Build aDSPTools required
  • Compiler version: Hexagon 8.4.07
  • Python version: Python 3.10.2
  • libffi6 package
Build steps
  • Nanopb integration (one-time setup):
  • Go to the following directory:
  • Clean the build:
  • Build the image:
Build BootTools required
  • Compiler version: LLVM version must be updated to 14.0.4
  • Python version: Python 3.10
  • libffi6 package
Build steps
  • Install the device tree compiler:
  • Go to the following directory:
  • Install the dependencies:
  • Clean the build:
  • Build the image:
    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:
  • Clean the build:
  • Build the image:
Build AOP firmwareTools required
  • Compiler version: LLVM 14.0.4
  • Python version: Python 3.10
Build steps
  • Go to the following directory:
  • Clean the build:
  • Build the image:
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):
  • Go to the following directory:
  • Clean the build:
  • Build the image:
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)
This step is only applicable for Qualcomm_Linux.SPF.2.0|AP|Standard|OEM|.
  • Create an integrated firmware binary from the individual components that you compiled:
  • 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 using the meta-qcom-extras layer. The BSP image build combines the compiled firmware from the previous step with the Yocto layer stack, producing a flashable image that includes all required binaries.
  • Download Qualcomm’s Yocto layer meta-qcom-extras. For the latest <meta-qcom-extras-release-tag>, see Configuration Parameters.
Layer Setup
  • Export NETRC_FILE parameter to ensure ~/.netrc credentials are visible in the kas environment:
  • Set CUST_ID value to “213195” for meta-qcom-extras compilation.
  • Set the outbound license for the layer and its checksum. CUST_LICENSE and CUST_LIC_CHKSUM are required for every recipe in the layer.
    • Customers must specify an appropriate outbound license in the recipes to build the proprietary sources.
    • Customers should consult their own legal team for guidance on outbound licensing decisions.
    • The chosen outbound license must be compatible with the PKLA.
  • The following values match the placeholder LICENSE files already present in the source repositories. Use them for internal builds and evaluation without needing to replace any license files. Do not use these values for production builds. Define your own license values for any deployment.
  • Update the license file in the source repositories before building. All sources used by meta-qcom-extras contain a placeholder LICENSE file by default. Recipes verify CUST_LICENSE against this file at build time, so it must be replaced with your chosen outbound license. The upstream repositories cannot be modified directly. Mirror each repository to a local or remote server you own, replace the placeholder LICENSE file, then update the SRC_URI variable in the affected recipes to point to the new URI.
The sync and layer setup steps above apply to all boards. However, meta-qcom-extras doesn’t yet provide ready-made recipes for loading custom firmware binaries on IQ-X7181 and IQ-X5121; use devtool to modify the upstream recipes instead, as shown in the “IQ-X7181” and “IQ-X5121” tabs below.
Firmware Setup
  • Set FWZIP_PATH to the directory containing the firmware ZIP files to include locally compiled firmware zip paths in the build.
  • 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:
    • Then modify the linux-firmware recipe using devtool:
    • Unzip the firmware archive:
    • Copy the contents of the firmware zip file into the devtool workspace
      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:
    • Unzip the firmware archive:
    • Copy the ADSP binaries into the devtool workspace:
    • Copy the CDSP binaries into the devtool workspace:
  • 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:
    • Unzip the boot binaries archive:
    • Copy boot binaries into the devtool workspace:
      Then append the required configuration to the .bbappend file:
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.
  • Build the software image using kas. You define build targets based on machine and distro combinations.