meta-qcom - Qualcomm Dragonwing Documentation

The meta-qcom metadata layer is hosted at git.yoctoproject.org and provides recipes to build the Qualcomm BSP. Use the recipes from the meta-qcom layer to build the software image. This layer also provides support for enabling Qualcomm devices. Note This guide uses the QCM6490 and QCS6490 hardware SoCs interchangeably. The rb3gen2-core-kit.conf and machine configuration files defined in the meta-qcom/conf/machine/ directory support the QCM6490, QCS6490, and QCS5430 hardware SoCs.

Recipe	Description
`recipes-devtools/qdl/qdl_git.bb`	The Qualcomm Download (QDL) flashing tool communicates with the USB devices displaying ID 05c6:9008 to upload a flash loader and uses this recipe to flash the images.
`recipes-support/pd-mapper/pd-mapper_<version>.bb`	The Qualcomm `pd-mapper` is an implementation for the protection domain mapper service. This service configures and manages protection domains, ensuring secure communication between applications and various remote processors.
`recipes-support/qrtr/qrtr_<version>.bb`	The Qualcomm Router (QRTR) is an inter-process communication mechanism used in Qualcomm system on chips (SoCs). QRTR allows communication between different processors in the system, such as the application processor and the modem, using a socket-style programming interface in the user space.
`recipes-support/initrdscripts/initramfs-module-copy-modules_1.0.bb`	`initramfs-framework` module for copying kernel modules from `initramfs`to `rootfs`.
`recipes-multimedia/`	Provides multimedia recipes for Qualcomm technologies, including camera components, the optimized Qualcomm FastCV library for image processing and computer vision, patches for GStreamer plug-ins to support Qualcomm-specific formats and fixes, and Qualcomm IM SDK GStreamer plug-ins.
`recipes-graphics/`	Contains recipes for Qualcomm Adreno graphics user-mode libraries, the KGSL driver, and the Mesa GBM backend for MSM platforms.
`lib/qcom/dtb_only_fitimage.py`	Tool for generating DTB-only FIT images that support Qualcomm-specific requirements.
`recipes-ml/`	Provides recipes for Qualcomm AI runtime SDK components, including tools, runtimes, and model execution engines.
`recipes-bsp/firmware-boot/`	Contains recipes that provide boot firmware binaries for Qualcomm platforms.
`recipes-bsp/firmware/camxfirmware-<soc>_<version>.bb`	Provides Qualcomm camera firmware required to enable camera functionality.
`recipes-bsp/hexagon-dsp-binaries/hexagon-dsp-binaries_<version>.bb`	Provides Hexagon DSP binaries distributed with the Linux firmware release. These binaries include libraries and executables used with the corresponding DSP firmware through the FastRPC interface to enable additional DSP functionality.
`recipes-bsp/partition/qcom-partition-conf_git.bb`	Provides GPT partition binaries and QDL scripts for Qualcomm reference devices.
`recipes-bsp/partition/mount-tee-partition_1.0.bb`	Mounts the persist partition at `/var/lib/tee` to store encrypted data and support security-related functionality.

BitBake classes

For an introduction to the BitBake classes, see classes-recipe and classes.

File	Description
`classes-recipe/dtb-fit-image.bbclass`	Creates the `qclinux-fit-image.its` file and generates a FIT image (ITB). This class initializes the ITS structure, adds DTB sections, including `qcom-metadata.dtb`, applies Qualcomm-specific ITS modifications, and assembles the final image using `mkimage`.
`classes-recipe/image-adbd.bbclass`	Installs the `adbd` daemon into the image when the OpenEmbedded layer is available. The `adbd` daemon is disabled by default and is enabled only when `IMAGE_FEATURES` includes `enable-adbd`.
`classes-recipe/image_types_qcom.bbclass`	Adds support for a new `IMAGE_FSTYPE` that creates a single tarball containing all required artifacts for a full clean flash, including partition metadata, boot firmware, the ESP partition, and the root filesystem.
`classes/linux-qcom-bootimg.bbclass`	Implements the logic to generate a `boot.img` file composed of a kernel image, a ramdisk image, and a kernel command line. The generated `boot.img` can be booted on machines using LK or fastboot.
`classes/linux-qcom-dtbbin.bbclass`	Generates a DTB image that is loaded by ARM SystemReady IR–compliant Qualcomm UEFI firmware. The firmware supports loading a matching device tree by reading `combined-dtb.dtb` or `qclinux_fit.img` from the DTB partition.
`classes/uki-esp-image.bbclass`	Uses the OE-Core `uki.bbclass` infrastructure to assemble an ESP image containing systemd-boot and a UKI.

Machine configurations

The Qualcomm Linux machine configuration files are available on GitHub. The files located in the meta-qcom/conf/machine/include directory define and set the required BitBake variables, which are commonly used by machine configurations defined by the Qualcomm BSP. The following table provides an overview of these files.

File	Description
`meta-qcom/conf/machine/include/qcom-base.inc`	This file sets the BitBake variables that are commonly shared by all machine configurations defined in the Qualcomm BSP. For example, `PREFERRED_PROVIDER` and `IMAGE_FSTYPES`.
`meta-qcom/conf/machine/include/qcom-common.inc`	Defines the default `MACHINE_FEATURES` set and the `QCOM_XBL_CONFIG` variable. When `kvm` is present in `MACHINE_FEATURES`, `QCOM_XBL_CONFIG` automatically selects `xbl_config_kvm.elf` instead of `xbl_config.elf`, enabling KVM-capable boot firmware.
`meta-qcom/conf/machine/include/qcom-qcs6490.inc`	This file sets the `SOC_FAMILY` variable to `qcm6490`. This file also defines configuration variables that are shared by all Qualcomm development kits based on QCS6490.
`meta-qcom/conf/machine/include/qcom-qcs9100.inc`	This file sets the `SOC_FAMILY` variable to `qcs9100`. This file also defines configuration variables that are shared by all Qualcomm development kits based on QCS9100.
`meta-qcom/conf/machine/include/qcom-qcs8300.inc`	This file sets the `SOC_FAMILY` variable to `qcs8300`. This file also defines configuration variables that are shared by all Qualcomm development kits based on QCS8300.
`meta-qcom/conf/machine/include/qcom-qcs615.inc`	This file sets the `SOC_FAMILY` variable to `qcs615`. This file also defines configuration variables that are shared by all Qualcomm development kits based on QCS615.
`meta-qcom/conf/machine/include/qcom-hamoa.inc`	This file sets the `SOC_FAMILY` variable to `hamoa`. It defines configuration variables shared by development kits based on the IQ-X7181 (Hamoa) platform.

Machine configuration files for development kits based on QCS6490

Configuration file	Description
`conf/machine/qcm6490-idp.conf`	This file is for the integrated development platform (IDP) with QCM6490.
`conf/machine/rb3gen2-core-kit.conf`	This file is for the Qualcomm Dragonwing^™ RB3 Gen 2 Core development kit with the QCS6490 SoC.

Machine configuration files for development kits based on IQ-9075 and IQ-9100

Configuration file	Description
`conf/machine/qcs9100-ride-sx.conf`	This file is for the Qualcomm^® IQ-9 Beta Evaluation Kit (EVK) with the IQ-9100 SoC.
`conf/machine/iq-9075-evk.conf`	This file is for the Qualcomm Dragonwing^™ IQ-9075 EVK with the IQ-9075 SoC. KVM hardware acceleration is enabled by default (`kvm` in `MACHINE_FEATURES`).

Machine configuration files for development kits based on IQ-8275

Configuration file	Description
`conf/machine/qcs8300-ride-sx.conf`	This file is for the Qualcomm^® IQ-8 Beta EVK with the IQ-8300 SoC.
`conf/machine/iq-8275-evk.conf`	This file is for the Qualcomm Dragonwing^™ IQ-8275 EVK with the IQ-8275 SoC. KVM hardware acceleration is enabled by default (`kvm` in `MACHINE_FEATURES`).

Machine configuration files for development kits based on IQ-615

Configuration file	Description
`conf/machine/iq-615-evk.conf`	This file is for the Qualcomm Dragonwing^™ IQ-615 EVK with the IQ-615 SoC.

Machine configuration files for IQ-X5121 and IQ-X7181

Configuration file	Description
`conf/machine/iq-x5121-evk.conf`	This file is for the Qualcomm Dragonwing^™ IQ-X5121 EVK (Purwa IoT platform).
`conf/machine/iq-x7181-evk.conf`	This file is for the Qualcomm Dragonwing^™ IQ-X7181 EVK (Hamoa IoT platform).

Kernel command-line

The recipes-kernel/images/esp-qcom-image.bb sets the UKI_CMDLINE variable. This variable is passed as a –cmdline= to ukify tool while generating a UKI image. The meta-qcom/conf/machine/include/qcom-base.inc sets variables QCOM_BOOTIMG_ROOTFS and SERIAL_CONSOLES which are used to compose the UKI_CMDLINE variable.

Include DTB and DTB overlay

The KERNEL_DEVICETREE variable is used to package the required DTBs and DTB overlays into a FIT image. This variable is configured in the individual machine configuration files located in meta-qcom/conf/machine. For example, the conf/machine/rb3gen2-core-kit.conf file sets the KERNEL_DEVICETREE variable, thereby selecting the appropriate DTB: rb3gen2-core-kit.conf The following code block shows how KERNEL_DEVICETREE is set.

KERNEL_DEVICETREE ?= " \
                      qcom/qcs6490-rb3gen2.dtb \
                      qcom/qcs6490-rb3gen2-industrial-mezzanine.dtbo \
                      qcom/qcs6490-rb3gen2-vision-mezzanine.dtbo \
                     "

# These DTs are not upstreamed and currently exist only in linux-qcom kernels
LINUX_QCOM_KERNEL_DEVICETREE ?= " \
                     qcom/qcs6490-rb3gen2-vision-mezzanine-camx.dtbo \
                     "

The DTB and DTB overlay listed are packaged into a FIT image using the FIT_DTB_COMPATIBLE entries in the conf/machine/include/fit-dtb-compatible.inc file.

FIT_DTB_COMPATIBLE[qcom_qcs5430-iot] = "qcs6490-rb3gen2"
FIT_DTB_COMPATIBLE[qcom_qcs6490-iot] = "qcs6490-rb3gen2"

FIT_DTB_COMPATIBLE[qcom_qcs5430-iot-subtype9] = \
    "qcs6490-rb3gen2 qcs6490-rb3gen2-industrial-mezzanine"
FIT_DTB_COMPATIBLE[qcom_qcs6490-iot-subtype9] = \
    "qcs6490-rb3gen2 qcs6490-rb3gen2-industrial-mezzanine"

FIT_DTB_COMPATIBLE[qcom_qcs5430-iot-subtype2] = \
    "qcs6490-rb3gen2 qcs6490-rb3gen2-vision-mezzanine"
FIT_DTB_COMPATIBLE[qcom_qcs6490-iot-subtype2] = \
    "qcs6490-rb3gen2 qcs6490-rb3gen2-vision-mezzanine"

This results in a FIT image generated with configuration as follows:

conf-w {
   fdt="fdt-qcs6490-rb3gen2.dtb";
   compatible="qcom,qcs5430-iot";
};

conf-x {
   fdt="fdt-qcs6490-rb3gen2.dtb";
   compatible="qcom,qcs6490-iot";
};

conf-y {
   fdt = "fdt-qcs6490-rb3gen2.dtb", "fdt-qcs6490-rb3gen2-industrial-mezzanine.dtbo";
   compatible = "qcom,qcs5430-iot-subtype9";
};

conf-z {
   fdt = "fdt-qcs6490-rb3gen2.dtb", "fdt-qcs6490-rb3gen2-industrial-mezzanine.dtbo";
   compatible = "qcom,qcs6490-iot-subtype9";
};

Firmware recipese

Qualcomm Linux firmware recipe files are available on GitHub. When the Qualcomm Linux source code is synced, the firmware recipes are available in the <workspace>/meta-qcom/recipes-bsp/firmware-boot,<workspace>/meta-qcom/recipes-bsp/hexagon-dsp-binaries directories.

Boot firmware binaries

Critical boot firmware images are required to boot the device. The following firmware recipe provides the hardware SoC-specific boot firmware.

Firmware recipe	Description
`meta-qcom/recipes-bsp/firmware-boot`	Handles fetch, unpack, and deploy for critical boot firmware binaries for compatible machines. The `QCM6490_bootbinaries.zip`, `QCS9100_bootbinaries.zip`, and `QCS8300_bootbinaries.zip` files provide the boot firmware required for QCS6490, QCS9075, and QCS8300 based machines.

After generating the build, the firmware binaries in these zip files are available for flashing in the following directory: <workspace>/build/tmp/deploy/images/<machine-name>/<image-name>.qcomflash/

Subsystem firmware binaries

Qualcomm Linux includes firmware binaries that are loaded and run on the corresponding subsystems. As the Qualcomm hardware SoC boots up, individual subsystems run the firmware as they come out of reset. The linux-firmware recipe provides upstream firmware packages and installs them in the /usr/lib/firmwaredirectory.

Firmware recipe	Description
`openembedded-core/meta/recipes-kernel/linux-firmware/linux-firmware_%.bb`	Handles fetch, unpack, and install for subsystem firmware binaries, such as aDSP, cDSP, modem, VPU, GPU, and WLAN.

The linux-firmware_%.bb recipe does the following:

Fetches the subsystem firmware binaries.

Unpacks the tar file.

Installs the firmware in /usr/lib/firmware/.

DSP libraries

User space utilities refer to the digital signal processor (DSP) libraries, which must be available in the rootfsimage. The following firmware recipes provide the hardware SoC-specific DSP libraries:

Firmware recipe	Description
`meta-qcom/recipes-bsp/hexagon-dsp-binaries/hexagon-dsp-binaries_%.bb`	Handles fetch, unpack, and install for DSP libraries, that are hosted on github.com/linux-msm/dsp-binaries

The hexagon-dsp-binaries_%.bb recipe does the following:

Fetches the DSP libraries from the GitHub repository.

Unpacks the zip file.

Installs the DSP libraries in rootfs.

Installation of boot, subsystem, and dspso

When Qualcomm Linux is built, the build system uses the firmware recipes to deploy the firmware based on the MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS configuration variable, which is set in the machine configuration file. For example, in conf/machine/iq-9075-evk.conf, see the inclusion of packagegroup-iq-9075-evk-firmware in the MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS variable:

MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += " \
   packagegroup-iq-9075-evk-firmware \
   packagegroup-iq-9075-evk-hexagon-dsp-binaries \
   qairt-sdk-hexagon-v73 \
   qcom-fastcv-binaries-sa8775p-ride-dsp \
   qps615-dlkm \
   "

Note The packagegroup-iq-9075-evk recipe present in the <workspace>/meta-qcom/recipes-bsp/packagegroups/ directory. It groups the firmware recipes to generate the image. When Qualcomm Linux is built, based on the configuration in the machine configuration and the package group recipe file, the respective firmware recipes from the <workspace>meta-qcom/recipes-bsp/firmware directory are built.

Kernel recipes

The Linux kernel recipes used by Qualcomm Linux are in <workspace>/meta-qcom/recipes-kernel/linux. Qualcomm Linux supports the long-term support (LTS) Qualcomm Linux kernel v6.18.x. In the meta-qcom layer, there are two kernel recipes:

Kernel Recipe	Purpose
`linux-qcom_6.18.bb`	Builds the standard Qualcomm Linux kernel image. The recipe fetches kernel sources from `github.com/qualcomm-linux/kernel` using the `qcom-6.18.y` branch at the pinned `SRCREV`.
`linux-qcom-rt_6.18.bb`	Builds the real-time Qualcomm Linux kernel image. It requires `linux-qcom_6.18.bb` and applies `rt.config` to configure the kernel for real-time operation.

linux-qcom_6.18.bblinux-qcom-rt_6.18.bb

inherit kernel
COMPATIBLE_MACHINE = "(qcom)"
LINUX_VERSION ?= "6.18.30"

# tag:qcom-6.18.y-20260601
SRCREV ?= "b7cce9a3884a873855693af8591d4c9c469cd17e"

SRCBRANCH ?= "nobranch=1"
SRCBRANCH:class-devupstream ?= "branch=qcom-6.18.y"

SRC_URI = "git://github.com/qualcomm-linux/kernel.git;${SRCBRANCH};protocol=https"
# Additional kernel configs.
SRC_URI += " \
    file://configs/bsp-additions.cfg \
"
KBUILD_DEFCONFIG ?= "defconfig"
KBUILD_CONFIG_EXTRA = "${@bb.utils.contains('DISTRO_FEATURES', 'hardened', '${S}/kernel/configs/hardening.config', '', d)}"
KBUILD_CONFIG_EXTRA:append:aarch64 = " ${S}/arch/arm64/configs/prune.config"
KBUILD_CONFIG_EXTRA:append:aarch64 = " ${S}/arch/arm64/configs/qcom.config"

Kernel configuration The Qualcomm Linux kernel recipe uses a different set of kernel configuration and fragments.

Variant	Configuration and fragments files
`linux-qcom_6.18.bb`	`defconfig`, `hardening.config`, `prune.config`, `qcom.config`, `bsp-additions.cfg`
`linux-qcom-rt_6.18.bb`	Uses same configs as `linux-qcom_6.18.bb` and adds `rt.config`

Licenses

The licenses for recipes in meta-qcom are listed at <workspace>/meta-qcom/licenses.

licenses/
├── LICENSE.qcom
└── LICENSE.qcom-2

Yocto can automatically create SPDX SBOM documents based on image creation. To enable this feature, follow the steps:

Inherit the create-spdx class in local.conf as follows:
INHERIT += "create-spdx"
After you inherit the class, rebuild the image with the BitBake command:
bitbake qcom-multimedia-image

You can find the SPDX output in the following directories:

For each recipe, the generated files are available in the tmp/deploy/spdx/<machine> directory.

The top-level SPDX output file is in the tmp/deploy/images/<machine>/ directory.

Next steps

To add a custom machine configuration, see Add custom machine configurations.
For kernel development and device tree customization, see the Qualcomm Linux Kernel Guide.
To handle out-of-tree kernel modules and device tree using recipes, see Handle out-of-tree kernel modules and device tree using recipes.

​BitBake classes

​Machine configurations

​Machine configuration files for development kits based on QCS6490

​Machine configuration files for development kits based on IQ-9075 and IQ-9100

​Machine configuration files for development kits based on IQ-8275

​Machine configuration files for development kits based on IQ-615

​Machine configuration files for IQ-X5121 and IQ-X7181

​Kernel command-line

​Include DTB and DTB overlay

​Firmware recipese

​Boot firmware binaries

​Subsystem firmware binaries

​DSP libraries

​Installation of boot, subsystem, and dspso

​Kernel recipes

​Licenses

​Next steps