> ## 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.

# Build the kernel using Yocto

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.

<Note>
  For standalone builds (kernel only, without Yocto), see
  [Build the kernel without Yocto](./build-kernel-standalone).
</Note>

## Access kernel sources

### Required meta-layers

The Qualcomm<sup>®</sup> Linux BSP is built using the `meta-qcom` Yocto layer.

* **meta-qcom** (layer): [https://github.com/qualcomm-linux/meta-qcom](https://github.com/qualcomm-linux/meta-qcom)

Release tags follow the `qli-<version>` convention (for example, `qli-2.0`). For
available tags, see the [Qualcomm Linux release notes - Introduction](https://dragonwingdocs.qualcomm.com/Key-Documents/Software-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.

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

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

```text theme={null}
# Provider for linux kernel
PREFERRED_PROVIDER_virtual/kernel = "linux-qcom"
PREFERRED_VERSION_virtual/kernel = "6.18%"
```

<Note>
  `linux-qcom` is selected for LTS BSP. `linux-qcom-next` is selected for
  mainline BSP, with `PREFERRED_VERSION_virtual/kernel` left empty.
</Note>

## 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<sup>®</sup> Linux supported image recipes**

| Image name              | Description                                                                                                         |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `qcom-console-image`    | Boot-to-shell image with basic packages.                                                                            |
| `qcom-multimedia-image` | Includes multimedia software components: audio, Bluetooth<sup>®</sup>, camera, computer vision, display, and video. |

<Note>
  See `meta-qcom-distro/recipes-products/images/` for complete list of images that are supported on Qualcomm Linux.
</Note>

The Qualcomm Linux kernel BSP recipe uses the following configuration fragments:

**Table: Kernel configuration fragments**

| Fragment                          | Description                                                           |
| --------------------------------- | --------------------------------------------------------------------- |
| `arch/arm64/configs/defconfig`    | Upstream arm64 defconfig used as the base configuration.              |
| `arch/arm64/configs/prune.config` | Prunes configurations from upstream defconfig to optimize build time. |
| `arch/arm64/configs/qcom.config`  | Enables Qualcomm-specific configurations not in upstream defconfig.   |
| `kernel/configs/debug.config`     | Enables standard kernel debug configuration.                          |
| `kernel/configs/hardening.config` | Enables security configurations for production kernel hardening.      |
| `arch/arm64/configs/rt.config`    | Enables `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`:

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

<Note>
  Yocto maintains an additional distro-level fragment applied on top:
  `meta-qcom/recipes-kernel/linux/linux-qcom-6.18/configs/bsp-additions.cfg`.
</Note>

## Build the kernel and modules

1. Open a kas shell:

```bash theme={null}
kas shell meta-qcom/ci/rb3gen2-core-kit.yml:meta-qcom/ci/qcom-distro.yml
```

2. Build the full image (kernel + root file system):

```bash theme={null}
bitbake qcom-multimedia-image
```

Built images are placed in:

```text theme={null}
build/tmp/deploy/images/<Machine>/
```

The kernel source tree is unpacked by BitBake during the build and is available at:

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

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

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

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