> ## Documentation Index
> Fetch the complete documentation index at: https://dragonwingdocs.qualcomm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# meta-qcom

The `meta-qcom` metadata layer is hosted at [git.yoctoproject.org](http://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](https://github.com/qualcomm-linux/meta-qcom/tree/master/classes-recipe) and [classes](https://github.com/qualcomm-linux/meta-qcom/tree/master/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](https://github.com/qualcomm-linux/meta-qcom/tree/master/conf/machine). 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<sup>™</sup> 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<sup>®</sup> IQ-9 Beta Evaluation Kit (EVK) with the IQ-9100 SoC.                                    |
|   `conf/machine/iq-9075-evk.conf`   | This file is for the Qualcomm Dragonwing<sup>™</sup> 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<sup>®</sup> IQ-8 Beta EVK with the IQ-8300 SoC.                                             |
|   `conf/machine/iq-8275-evk.conf`   | This file is for the Qualcomm Dragonwing<sup>™</sup> 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<sup>™</sup> 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<sup>™</sup> IQ-X5121 EVK (Purwa IoT platform). |
| `conf/machine/iq-x7181-evk.conf` | This file is for the Qualcomm Dragonwing<sup>™</sup> 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.

```text theme={null}
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.

```text theme={null}
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:

```text theme={null}
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 recipes**e

Qualcomm Linux firmware recipe files are available on [GitHub](https://github.com/qualcomm-linux/meta-qcom/tree/master/recipes-bsp). 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/firmware`directory.

|                             **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:

> 1. Fetches the subsystem firmware binaries.
> 2. Unpacks the tar file.
> 3. 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 `rootfs`image. 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:

> 1. Fetches the DSP libraries from the GitHub repository.
> 2. Unpacks the zip file.
> 3. 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:

```text theme={null}
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.bb**linux-qcom-rt\_6.18.bb

```text theme={null}
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`.

```text theme={null}
licenses/
├── LICENSE.qcom
└── LICENSE.qcom-2
```

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

> 1. Inherit the `create-spdx` class in `local.conf` as follows:
>    ```text theme={null}
>    INHERIT += "create-spdx"
>    ```
> 2. After you inherit the class, rebuild the image with the BitBake command:
>    ```text theme={null}
>    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](./add-custom-machine-configurations).
* For kernel development and device tree customization, see the [Qualcomm Linux Kernel Guide](https://dragonwingdocs.qualcomm.com/System/Kernel/kernel-overview).
* To handle out-of-tree kernel modules and device tree using recipes, see [Handle out-of-tree kernel modules and device tree using recipes](./handling-out-of-tree-kernel-modules-and-device-tree-using-recipes).