# Getting started with Qualcomm Linux kernel This information explains how to download, configure, and develop the Qualcomm^®^ Linux kernel for the Qualcomm Linux development kit and its associated components to build and flash system images. Before you begin downloading and configuring the Qualcomm Linux kernel, set up your host computer as described in the [Qualcomm Linux Build Guide](bundle/publicresource/topics/80-70018-254), which also provides information about the common Qualcomm Linux kernel workflows. ## Access Qualcomm Linux kernel source code To access the source code for the Qualcomm Linux kernel, see the [Qualcomm Linux Build Guide](bundle/publicresource/topics/80-70018-254) and get all the necessary Qualcomm Linux meta layers. Qualcomm Linux uses the LTS Linux kernel (6.6.x) and supports two software variants: > > > - Base board support package (BSP) > - Custom BSP Note - **Base BSP** variant uses the upstream LTS Linux kernel (6.6.x) with a limited set of downstream patches. Kernel sources are hosted at [kernel/git/stable/linux.git](https://web.git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/tree/?h=linux-6.6.y&id=943e0aeece93a9c2329215d02621e634adf6d790). - **Custom BSP** variant uses a customized LTS Linux kernel (6.6.x) and is hosted at the Qualcomm repository on CodeLinaro. Kernel sources are hosted at [kernel.qclinux.1.0.r1-rel](https://git.codelinaro.org/clo/la/kernel/qcom/-/commits/LKP.QCLINUX.1.0.r1-04800-kernel.0?ref_type=tags). Table: Kernel recipe path of the variants | Variant | Kernel recipe path | | --- | --- | | Base BSP | `recipes-kernel/linux/linux-qcom-base_6.6.bb` | | Custom BSP | `recipes-kernel/linux/linux-qcom-custom_6.6.bb` | Note The kernel recipes for base BSP and custom BSP are present in the `meta-qcom-hwe` layer. See the `recipes-kernel/linux/linux-qcom-base_6.6.bb` or `recipes-kernel/linux/linux-qcom-custom_6.6.bb` file to know the Git uniform resource identifier (URI) to download the kernel source code. For more information about Qualcomm Linux layers, see [Qualcomm Linux metadata layers overview](https://docs.qualcomm.com/bundle/publicresource/topics/80-70018-27/qualcomm_linux_metadata_layers_overview.html). > > > Note > > > Yocto recipe refers to Qualcomm Linux kernel sources that are publicly hosted at [CodeLinaro](https://git.codelinaro.org/clo/la/kernel/qcom). The following examples show the Qualcomm Linux kernel recipe source URI information for the base BSP and custom BSP: **Base BSP** The following is the source URI information for the base BSP variant: SECTION = "kernel" SUMMARY = "Linux kernel for QCOM devices" DESCRIPTION = "Recipe to build Linux kernel from 6.6 LTS branch" LICENSE = "GPL-2.0-only" LIC_FILES_CHKSUM = "file://COPYING;md5=6bc538ed5bd9a7fc9398086aedcd7e46" inherit kernel COMPATIBLE_MACHINE = "(qcom)" SRC_URI = " git://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git;protocol=https;branch=linux-6.6.y \ file://qcom.cfg \ " Copy to clipboard **Custom BSP** The following is the source URI information for the custom BSP variant: > > > SECTION = "kernel" > > SUMMARY = "Linux kernel for QCOM devices" > DESCRIPTION = "Recipe to build Linux kernel" > > LICENSE = "GPLv2.0-with-linux-syscall-note" > LIC_FILES_CHKSUM = "file://COPYING;md5=6bc538ed5bd9a7fc9398086aedcd7e46" > > inherit kernel > > COMPATIBLE_MACHINE = "(qcom)" > > SRC_URI = "git://git.codelinaro.org/clo/la/kernel/qcom.git;protocol=https;rev=350dfd604d2ffbe0cac99bf3459b49114aad11f4;branch=kernel.qclinux.1.0.r1-rel \ > file://QCLINUX-arm64-dts-qcom-sa8775p-ride-add-board-id-and.patch \ > ${@bb.utils.contains('DISTRO_FEATURES', 'selinux', ' file://selinux.cfg', '', d)} \ > ${@bb.utils.contains('DISTRO_FEATURES', 'selinux', ' file://selinux_debug.cfg', '', d)} \ > " > Copy to clipboard ## Identify supported Qualcomm machines The Qualcomm machine configuration files are present in the `meta-qcom-hwe/conf/machine/` directory. Machine configuration files follow a `--​.conf` naming convention, where: - `SoC` is the system-on-chip (SoC) name - `board` is the type of board for which the software is built - `variant` is the type of product For example: In the `qcs6490-rb3gen2-core-kit.conf` filename, - `qcs6490` is the SoC - `rb3gen2` is the board - `core-kit` is the type of product The same naming convention is followed in platform-specific device tree files. The following example shows the list of supported machines that are configured for Yocto: ls -l ./LE.QCLINUX.1.0/layers/meta-qcom-hwe/conf/machine/*.conf meta-qcom-hwe/conf/machine/qcs6490-rb3gen2-core-kit.conf meta-qcom-hwe/conf/machine/qcs6490-rb3gen2-vision-kit.conf meta-qcom-hwe/conf/machine/qcs9075-ride-sx.conf Copy to clipboard The following example shows the machine configuration selection for the development board with Qualcomm chipset: less meta-qcom-hwe/conf/machine/--.conf #@TYPE: Machine #@NAME: --`` > #@DESCRIPTION: Machine configuration for the development board, with Qualcomm qcs6490 require conf/machine/include/qcom-.inc Copy to clipboard The following example shows the kernel configuration selection for base and custom BSP variants: less meta-qcom-hwe/conf/machine/include/qcom-base.inc # Provider for linux kernel # qcom-base-bsp uses 'linux-qcom-base' as kernel PREFERRED_PROVIDER_virtual/kernel ?= "linux-qcom-custom" PREFERRED_PROVIDER_virtual/kernel:qcom-base-bsp ?= "linux-qcom-base" Copy to clipboard Note - `linux-qcom-base` is selected when the base BSP variant is compiled. - `linux-qcom-custom` is selected when a custom BSP is compiled. ## Build Yocto image recipes and kernel configuration You can access the Qualcomm Linux image recipes to modify the kernel configurations. The following table lists the supported `meta-qcom-hwe` images: Table: Qualcomm Linux supported image recipes | Image name | Description | | --- | --- | | qcom-console-image
Copy to clipboard | This is a boot-to-shell image with the package group to bring in all basic packages. | | qcom-multimedia-image
Copy to clipboard | This image recipe includes recipes for multimedia software components, such as audio, Bluetooth^®^, camera, computer vision, display, and video. | | qcom-multimedia-test-image
Copy to clipboard | This image recipe includes tests. | After downloading the Qualcomm Linux code, run the `bitbake` command to build the image. Note The base BSP variant uses a `arch/arm64/configs/defconfig` kernel configuration file. Local changes are overlaid on top of `defconfig` from the `meta-qcom-hwe/recipes-kernel/linux/linux-qcom-base-6.6/qcom.cfg` file. To compile the Qualcomm Linux kernel for the base BSP variant, run the following commands: # Use the filename of Machine conf file for MACHINE parameter $ MACHINE=-- DISTRO=qcom-wayland QCOM_SELECTED_BSP=base source setup-environment # build qcom linux console image $ bitbake qcom-console-image # Build Images are produced under "build-qcom-wayland/tmp-glibc/deploy/images/--/qcom-console-image/" Copy to clipboard To build the images listed in [Table: Qualcomm Linux supported image recipes](https://docs.qualcomm.com/doc/80-70018-3/topic/getting_started_chapter2.html#qualcomm-linux-supported-image-recipes), the Qualcomm Linux kernel custom BSP recipe uses one of the following kernel configuration fragments: Note Downstream kernel configuration files contain `addons`. Table: Custom BSP kernel configuration fragments | Kernel configuration fragments | Description | | --- | --- | | /arch/arm64/configs/qcom_defconfig
Copy to clipboard | Requires the base configuration of the product to be aligned with the upstream kernel | | /arch/arm64/configs/qcom_debug.config
Copy to clipboard | Debugs a configuration fragment from the upstream kernel | | /arch/arm64/configs/qcom_addons.config
Copy to clipboard | Adds Qualcomm downstream additions on top of the upstream aligned base | | /arch/arm64/configs/qcom_addons_debug.config
Copy to clipboard | Enables Qualcomm downstream debug | To build Qualcomm Linux including the kernel for the custom BSP variant, run the following commands: > > > # Use the filename of Machine conf file for MACHINE parameter > MACHINE=-- DISTRO=qcom-wayland QCOM_SELECTED_BSP=custom source setup-environment > > # build qcom linux console image > bitbake qcom-console-image > > # Build Images are produced under "build-qcom-wayland/tmp-glibc/deploy/images/--/qcom-console-image/" > Copy to clipboard The kernel default builds are defined in the `linux-qcom-base_6.6.bb` or `linux-qcom-custom_6.6.bb` file. Qualcomm Linux kernel recipes support number 3 (performance) and number 4 (debug) builds mentioned in the following table. The default build configuration is number 3 (performance). The following kernel configuration fragments are only applicable to the custom BSP variant. > > > Table: Custom BSP kernel build configuration type and configurations > > > | Serial number | Kernel build configuration type | Defconfig/config fragments | > | --- | --- | --- | > | 1 | Base | arch/arm64/configs/qcom_defconfig
Copy to clipboard | > | 2 | Debug-enabled base | 

  • arch/arm64/configs/qcom_defconfig
    Copy to clipboard



  • arch/arm64/configs/qcom_debug.config
    Copy to clipboard



| > | 3 | Base with downstream additions | 

  • arch/arm64/configs/qcom_defconfig
    Copy to clipboard



  • arch/arm64/configs/qcom_addons.config
    Copy to clipboard



| > | 4 | Debug-enabled base with downstream | 

  • arch/arm64/configs/qcom_defconfig
    Copy to clipboard



  • arch/arm64/configs/qcom_debug.config
    Copy to clipboard



  • arch/arm64/configs/qcom_addons.config
    Copy to clipboard



  • arch/arm64/configs/qcom_addons_debug.config
    Copy to clipboard



| For more information about configuring the kernel, see [Kernel configurations](https://docs.qualcomm.com/doc/80-70018-3/topic/features.html#kernel-configuration-1). ### Compile a Qualcomm debug build Run the following command to compile a debug build: DEBUG_BUILD=1 bitbake qcom-console-image Copy to clipboard To modify the build configurations, update the `KERNEL_CONFIG` and `KERNEL_CONFIG_FRAGMENTS` variables in the `linux-qcom-base_6.6.bb` or `linux-qcom-custom_6.6.bb` kernel recipe in the `meta-qcom-hwe` layer. ### Example kernel configuration The following examples show kernel configuration for base and custom BSPs: **Base BSP** The following example shows the kernel configuration using the `linux-qcom-base_6.6.bb` kernel recipe: > > > KERNEL_CONFIG_FRAGMENTS:append = " ${WORKDIR}/qcom.cfg" > > S = "${WORKDIR}/git" > > # 6.6.38 > SRCREV = "2928631d5304b8fec48bad4c7254ebf230b6cc51" > PV = "6.6+git${SRCPV}" > > KERNEL_CONFIG ??= "defconfig" > Copy to clipboard **Custom BSP** The following example shows the kernel configuration using the `linux-qcom-custom_6.6.bb` kernel recipe: > > > KERNEL_CONFIG ??= "qcom_defconfig" > > KERNEL_CONFIG_FRAGMENTS:append = " ${S}/arch/arm64/configs/qcom_addons.config" > KERNEL_CONFIG_FRAGMENTS:append = " ${@oe.utils.vartrue('DEBUG_BUILD', '${S}/arch/arm64/configs/qcom_debug.config', '', d)}" > KERNEL_CONFIG_FRAGMENTS:append = " ${@oe.utils.vartrue('DEBUG_BUILD', '${S}/arch/arm64/configs/qcom_addons_debug.config', '', d)}" > > # Enable selinux support > SELINUX_CFG = "${@oe.utils.vartrue('DEBUG_BUILD', 'selinux_debug.cfg', 'selinux.cfg', d)}" > KERNEL_CONFIG_FRAGMENTS:append = " ${@bb.utils.contains('DISTRO_FEATURES', 'selinux', '${WORKDIR}/${SELINUX_CFG}', '', d)}" > Copy to clipboard For more information about the build instructions, see [Build with QSC CLI](https://docs.qualcomm.com/bundle/publicresource/topics/80-70018-254/build_frm_source_qsc_cli.html#build-from-source-qsc-cli) in the [Qualcomm Linux Build Guide](bundle/publicresource/topics/80-70018-254). ## Access the platform device tree The Qualcomm device tree source inclusion (DTSI) and device tree source (DTS) files for supported development kits are located under the kernel source in the `arch/arm64/boot/dts/qcom/` directory. These Qualcomm files segregate the upstream-aligned and downstream additions. The device tree files with `addons` are downstream files. The base BSP variant software doesn’t use any downstream device tree files. `--​.conf` is the Qualcomm Linux machine configuration file that contains the required device tree blob (DTB) selection configuration data. - `SoC` is any supported Qualcomm Linux SoC. For example, QCS6490 and QCS9075. - `board` is an RB3 Gen 2 supported product. - `variant` is the specific type of product, for example core-kit. The following example shows the DTB inclusion into the device configuration file: KERNEL_DEVICETREE = " \ qcom/-addons-.dtb \ " Copy to clipboard Tab QCS6490 Tab QCS9075 Tab QCS8275 The following table lists the Qualcomm^®^ device tree files for the Qualcomm RB3 Gen 2 Development Kit. > > > Table: Qualcomm device tree source > > > | Device tree source | Details | > | --- | --- | > | arch/arm64/boot/dts/qcom/sc7280.dtsi
Copy to clipboard | The QCS6490 SoC is derived from SC7280 SoC. | > | arch/arm64/boot/dts/qcom/qcm6490.dtsi
Copy to clipboard | The QCM6490/QCS6490 DTSI that hosts any changes is different from the SC7280 SoC. | > | arch/arm64/boot/dts/qcom/qcm6490-addons.dtsi
Copy to clipboard | Downstream additions specific to the QCM6490/QCS6490 SoC. | > | arch/arm64/boot/dts/qcom/qcs6490-rb3gen2.dts
Copy to clipboard | Device tree source for the QCS6490 Qualcomm RB3 Gen 2 Development Kit. | > | arch/arm64/boot/dts/qcom/qcs6490-addons-rb3gen2.dts
Copy to clipboard | Downstream additions specific to the QCS6490 for the Qualcomm RB3 Gen 2 Development Kit. | > | arch/arm64/boot/dts/qcom/qcs5430-addons-rb3gen2.dts
Copy to clipboard | Downstream additions specific to the QCS5430 feature pack-1 for the Qualcomm RB3 Gen 2 Development Kit. | > | arch/arm64/boot/dts/qcom/qcs5430-fp2-addons-rb3gen2.dts
Copy to clipboard | Downstream additions for the QCS5430 feature pack-2 in the Qualcomm RB3 Gen 2 Development Kit. | > | arch/arm64/boot/dts/qcom/qcs5430-fp2p5-addons-rb3gen2-vision-mezz.dts
Copy to clipboard | Downstream additions for the QCS5430 feature pack-2.5 in the RB3 Gen 2 vision Mezzanine Development Kit. | > | arch/arm64/boot/dts/qcom/qcs5430-fp3-addons-rb3gen2-vision-mezz.dts
Copy to clipboard | Downstream additions for the QCS5430 feature pack-3 in the RB3 Gen 2 vision Mezzanine Development Kit. | The following table lists the Qualcomm device tree files for the QCS9075 Development Kit. By default, the addons DTB is used. > > > Table : Qualcomm device tree source > > > | Device tree source | Details | > | --- | --- | > | arch/arm64/boot/dts/qcom/sa8775p.dtsi
Copy to clipboard | The QCS9075 SoC is derived from SA8775P. | > | arch/arm64/boot/dts/qcom/sa8775p-ride.dtsi
Copy to clipboard | Qualcomm Linux development kit for QCS9075. | > | arch/arm64/boot/dts/qcom/qcs9075-ride.dts
Copy to clipboard | Qualcomm Linux development kit for QCS9075 ride. | > | arch/arm64/boot/dts/qcom/qcs9075-addons-ride.dts
Copy to clipboard | Qualcomm Linux development kit for the QCS9075 ride with downstream additions. | > | arch/arm64/boot/dts/qcom/qcs9075-ride-r3.dts
Copy to clipboard | Qualcomm Linux development kit for the QCS9075 ride R3. | > | arch/arm64/boot/dts/qcom/qcs9075-addons-ride-r3.dts
Copy to clipboard | Qualcomm Linux development kit for the QCS9075 ride R3 with downstream additions. | > | arch/arm64/boot/dts/qcom/qcs9075-iq-9075-evk.dts
Copy to clipboard | Qualcomm Linux development kit for the Qualcomm Dragonwing^TM^ IQ-9075 EVK. | > | arch/arm64/boot/dts/qcom/qcs9075-addons-iq-9075-evk.dts
Copy to clipboard | Qualcomm Linux development kit for the Qualcomm Dragonwing^TM^ IQ-9075 EVK with downstream additions. | The following table lists the Qualcomm device tree files for the QCS8275 development kit. By default, the addons DTB is used. > > > Table : Qualcomm device tree source > > > | Device tree source | Details | > | --- | --- | > | arch/arm64/boot/dts/qcom/qcs8300.dtsi
Copy to clipboard | The QCS8275 SoC is derived from QCS8300. | > | arch/arm64/boot/dts/qcom/qcs8300-addons.dtsi
Copy to clipboard | Qualcomm Linux development kit for QCS8275 with downstream additions. | > | arch/arm64/boot/dts/qcom/qcs8300-ride.dts
Copy to clipboard | Qualcomm Linux development kit for QCS8275 ride. | > | arch/arm64/boot/dts/qcom/qcs8300-addons-ride.dts
Copy to clipboard | Qualcomm Linux development kit for the QCS8275 ride with downstream additions. | ## Manage out-of-tree DT overlay fragments SoC machine configuration files include additional out-of-tree DTB overlays (DTBO). Graphics, camera, wireless local area network (WLAN) drivers, and their device tree configurations are maintained out of the kernel source tree. The respective device tree source overlay (DTSO) fragments are overlaid at the build time onto the base DTBs. The DTBO configuration is done in the `conf/machine/--.conf` file. The following example shows the DTBO configuration: # OUT_OF_KERNEL_DTSO - qcs6490-rb3gen2-core-kit.conf # Additional list of DTBOs to be overlaid on top of base kernel devicetree files # Format - KERNEL_TECH_DTBOS[] = " ..." # For example: KERNEL_TECH_DTBOS[qcs6490-addons-rb3gen2] = " \ qcm6490-graphics.dtbo qcm6490-wlan-rb3.dtbo \ qcm6490-display-rb3.dtbo qcm6490-bt.dtbo \ qcm6490-video.dtbo qcm6490-wlan-upstream.dtbo \ " Copy to clipboard ## Manage out-of-tree kernel modules Most of the kernel drivers are compiled from upstream kernel sources. However, some drivers are maintained outside the kernel source tree and are built as kernel modules using the Yocto build system. In the following example, Bluetooth^®^ is an out-of-tree kernel module. The recipe located at `recipes-connectivity/bt_dlkm_kernel/bt-dlkm-kernel_git.bb` compiles the driver as a kernel module. To autoload the kernel module on boot, you can add the module name to the `KERNEL_MODULE_AUTOLOAD` variable. # Example out-of-tree Kernel module recipe DESCRIPTION = "QCOM BT drivers" LICENSE = "GPL-2.0-only" LIC_FILES_CHKSUM = "file://${COMMON_LICENSE_DIR}/${LICENSE};md5=801f80980d171dd6425610833a22dbe6" inherit module SRC_URI += "git://git.codelinaro.org/clo/le/platform/vendor/qcom-opensource/bt-kernel.git;protocol=https;rev=9e5cf29625d60f78e88440c94d096a9139445c00;branch=bt-performant.qclinux.1.0.r1-rel \ file://bt_dlkm \ file://bt_dlkm.service \ " S = "${WORKDIR}/git" RPROVIDES:${PN} += "kernel-module-bt-kernel" EXTRA_OEMAKE += "MACHINE='${MACHINE}'" MAKE_TARGETS = "modules" MODULES_INSTALL_TARGET = "modules_install" # Kernel module to be autoloaded KERNEL_MODULE_AUTOLOAD += "bt_fm_slim" Copy to clipboard ## Build the device image To build the full image and kernel, run the following Yocto commands: # setup the build environment export SHELL=/bin/bash source setup-environment # (select " meta-qcom" → Enter → select "qcom-wayland meta-qcom-distro" → Enter) # build qcom linux console image bitbake qcom-console-image # Build kernel only bitbake linux-qcom-base # Build Images are produced under # build-qcom-wayland/tmp-glibc/deploy/images/--/qcom-console-image/ Copy to clipboard For more information about how to build different images for SoC-supported Qualcomm distribution, see [Kernel configurations](https://docs.qualcomm.com/doc/80-70018-3/topic/features.html#kernel-configuration-1). Note To build a custom BSP, use `linux-qcom-custom`. ## Bring up the device The `efi.bin` file contains the systemd-boot (boot manager), kernel, and initramfs images. The Yocto build packs these images into `efi.bin` that’s flashed to the EFI system partition (ESP) to boot the device. Device tree blobs are updated or added to the `KERNEL_DEVICETREE` variable in the `conf/machine/--.conf` file. These device tree blobs are used to compile the `dtb.bin` file. Flash the `efi.bin` and `dtb.bin` images using the following fastboot commands: # Bring the device in fastboot mode # cd to the source root location $ cd build-qcom-wayland/tmp-glibc/deploy/images//qcom-console-image $ fastboot flash efi efi.bin $ fastboot flash dtb_a dtb.bin $ fastboot reboot Copy to clipboard After the Qualcomm Linux build is generated, the kernel build is completed and the kernel-related images are created in the `tmp-glibc/deploy/images/--/` directory. The following table lists the kernel build artifacts: Table : Kernel build artifacts | Image | Image name | Build deploy path | Details | | --- | --- | --- | --- | | Kernel executable and linking format (ELF) | vmlinux
Copy to clipboard | tmp-glibc/deploy/images/--/
Copy to clipboard | Output kernel ELF with debug symbols. | | Initramfs | initramfs-qcom-image---.cpio.gz
Copy to clipboard | tmp-glibc/deploy/images/--/
Copy to clipboard | Initramfs in copy in, copy out (CPIO) file format. | | Kernel image | Image
Copy to clipboard | tmp-glibc/deploy/images/--/
Copy to clipboard | Kernel raw image binary, systemd-boot doesn’t support compressed images. | | Kernel modules | Different kernel dynamically loadable kernel modules (DLKMs)


modules---.tgz
Copy to clipboard | tmp-glibc/deploy/images/--/
Copy to clipboard | Kernel drivers modules. | | Device tree blobs | -addons-.dtb
Copy to clipboard | tmp-glibc/deploy/images/--/
Copy to clipboard | Individual device tree blobs. | | ESP partition | efi.bin
Copy to clipboard | tmp-glibc/deploy/images/--/
Copy to clipboard | All required boot images including systemd-boot, kernel, and initramfs are packaged into the extensible firmware interface (`efi.bin`) binary. | | DTB partition | dtb.bin
Copy to clipboard | tmp-glibc/deploy/images/--/
Copy to clipboard | All the DTBO files are merged into the `dtb.bin` binary. | Last Published: Apr 10, 2025 [Previous Topic Kernel overview](https://docs.qualcomm.com/bundle/publicresource/80-70018-3/topics/overview.md) [Next Topic Kernel features](https://docs.qualcomm.com/bundle/publicresource/80-70018-3/topics/features.md)