Skip to main content
The Yocto workflow is recommended for full BSP integration and production image builds. It uses kas and BitBake with the meta-qcom layer to build the kernel alongside the root file system and all packages.
For standalone builds (kernel only, without Yocto), see Build the kernel without Yocto.

​
Access kernel sources

​
Required meta-layers

The Qualcomm® Linux BSP is built using the meta-qcom Yocto layer. Release tags follow the qli-<version> convention (for example, qli-2.0). For available tags, see the Qualcomm Linux release notes - Introduction.

​
Sync meta-layers with kas

Run the following commands from your workspace root directory. After syncing, the workspace will contain a meta-qcom/ directory. 
# Clone meta-qcom at the target release tag (e.g. -b qli-2.0)
git clone https://github.com/qualcomm-linux/meta-qcom \
    -b <release-tag>

​
Supported machine configurations

Machine configuration files are located in meta-qcom/conf/machine/ and follow the <SoC>-<board>-<variant>.conf naming convention, where:
  • SoC is the system-on-chip name
  • board is the board type
  • variant is the product type
The following example lists the supported machine configurations: 
ls meta-qcom/conf/machine/*.conf

meta-qcom/conf/machine/iq-8275-evk.conf
meta-qcom/conf/machine/iq-9075-evk.conf
meta-qcom/conf/machine/qcs615-ride.conf
meta-qcom/conf/machine/qcs6490-rb3gen2-core-kit.conf
meta-qcom/conf/machine/qcs8300-ride-sx.conf
meta-qcom/conf/machine/qcs9100-ride-sx.conf
The kernel recipe and version are selected in the common include file meta-qcom/conf/machine/include/qcom-base.inc, which every machine configuration inherits: 
# Provider for linux kernel
PREFERRED_PROVIDER_virtual/kernel = "linux-qcom"
PREFERRED_VERSION_virtual/kernel = "6.18%"
linux-qcom is selected for LTS BSP. linux-qcom-next is selected for mainline BSP, with PREFERRED_VERSION_virtual/kernel left empty.

​
Image recipes and kernel configuration

Image recipes are located in meta-qcom-distro/recipes-products/images/. The following table lists the main supported images: Table: Qualcomm® Linux supported image recipes
Image nameDescription
qcom-console-imageBoot-to-shell image with basic packages.
qcom-multimedia-imageIncludes multimedia software components: audio, Bluetooth®, camera, computer vision, display, and video.
See meta-qcom-distro/recipes-products/images/ for complete list of images that are supported on Qualcomm Linux.
The Qualcomm Linux kernel BSP recipe uses the following configuration fragments: Table: Kernel configuration fragments
FragmentDescription
arch/arm64/configs/defconfigUpstream arm64 defconfig used as the base configuration.
arch/arm64/configs/prune.configPrunes configurations from upstream defconfig to optimize build time.
arch/arm64/configs/qcom.configEnables Qualcomm-specific configurations not in upstream defconfig.
kernel/configs/debug.configEnables standard kernel debug configuration.
kernel/configs/hardening.configEnables security configurations for production kernel hardening.
arch/arm64/configs/rt.configEnables PREEMPT_RT for real-time kernel builds.
To modify the active fragments, update KBUILD_DEFCONFIG and KBUILD_CONFIG_EXTRA in your kernel recipe in the meta-qcom layer. The following example shows the default configuration in recipes-kernel/linux/linux-qcom_6.18.bb: 
KBUILD_DEFCONFIG ?= "defconfig"
KBUILD_DEFCONFIG:qcom-armv7a = "qcom_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"
KBUILD_CONFIG_EXTRA:append = " ${@oe.utils.vartrue('DEBUG_BUILD', '${S}/kernel/configs/debug.config', '', d)}"
Yocto maintains an additional distro-level fragment applied on top: meta-qcom/recipes-kernel/linux/linux-qcom-6.18/configs/bsp-additions.cfg.

​
Build the kernel and modules

  1. Open a kas shell:
kas shell meta-qcom/ci/rb3gen2-core-kit.yml:meta-qcom/ci/qcom-distro.yml
  1. Build the full image (kernel + root file system):
bitbake qcom-multimedia-image
Built images are placed in: 
build/tmp/deploy/images/<Machine>/
The kernel source tree is unpacked by BitBake during the build and is available at: 
build/tmp/work-shared/<machine>/kernel-source/

​
Enable a debug build

To compile a debug-enabled build, set DEBUG_BUILD=1 as an environment variable or in build/conf/local.conf: 
kas shell meta-qcom/ci/rb3gen2-core-kit.yml:meta-qcom/ci/qcom-distro.yml

DEBUG_BUILD=1 bitbake qcom-multimedia-image

​
Common build errors

Configuration changes not reflected in the built image If a kernel config option does not appear in the running kernel after a rebuild:
  1. Add the missing option explicitly to kernel/configs/debug.config.
  2. Set DEBUG_BUILD=1 before running BitBake to ensure the debug fragment is applied:
DEBUG_BUILD=1 bitbake qcom-multimedia-image
do_fetch failure Verify network connectivity and confirm that SRCREV in the kernel recipe matches a commit that exists on the specified branch. Check the recipe file meta-qcom/recipes-kernel/linux/linux-qcom_6.18.bb for the release-pinned revision. Disk space exhausted during build A full Yocto build requires at least 300 GB of free space and a swap partition larger than 32 GB. Clean previous build artifacts to reclaim space: 
bitbake -c cleanall linux-qcom
ERROR_QA or warnings treated as errors These are typically recipe metadata issues. Inspect the full BitBake log at build/tmp/work/<SoC>-<board>-<variant>/linux-qcom/*/temp/log.do_compile for the root cause before changing recipe settings.