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

# Modify the kernel

The Qualcomm<sup>®</sup> Linux kernel is developed using the Yocto `devtool` workflow.
This page covers the edit–build–maintain cycle for making kernel source and
configuration changes within a Yocto workspace.

<Note>
  This page covers the Yocto `devtool` workflow only. For faster iteration on
  kernel-only changes without building a full image, see
  [Build the kernel without Yocto](./build-kernel-standalone).
</Note>

<Note>
  Before starting, ensure your host is set up with the required tools (`kas`,
  `git`, and the Yocto build dependencies). See
  [Prerequisites & host setup](./prerequisites-and-host-setup).
</Note>

* To set up your host and clone the source, see [Access kernel sources](./access-kernel-sources).
* To configure the kernel and build an image, see [Build the kernel using Yocto](./build-kernel-yocto).
* To build the kernel without Yocto, see [Build the kernel without Yocto](./build-kernel-standalone).
* To flash and verify after a build, see [Install & boot the kernel](./install-and-boot-the-kernel).

For more information about Yocto kernel development provisions, see
[Yocto Project Linux Kernel Development](https://docs.yoctoproject.org/kernel-dev/).

## Unpack the kernel source

Use `devtool` to unpack the kernel source into a local workspace for editing.
`devtool modify` checks out the kernel source into the devtool workspace and
rewires the recipe to build from that local copy, so your edits are picked up
automatically on the next build without re-fetching from upstream.

1. Clone `meta-qcom` at a release tag. 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).

```bash theme={null}
git clone https://github.com/qualcomm-linux/meta-qcom.git -b <release-tag>
```

2. Sync all meta-layers at their pinned revisions. If you have already completed
   the sync steps in
   [Build the kernel using Yocto](./build-kernel-yocto#sync-meta-layers-with-kas),
   this step is already done.

3. Open a kas shell. Replace `rb3gen2-core-kit.yml` with the machine YML that
   matches your board. All supported machine YML files are in `meta-qcom/ci/`.

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

4. Unpack the kernel source into the devtool workspace:

```bash theme={null}
devtool modify linux-qcom
```

The kernel source is checked out to `build/workspace/sources/linux-qcom`.

<Note>
  For the mainline BSP, use `linux-qcom-next` and set
  `PREFERRED_PROVIDER_virtual/kernel = "linux-qcom-next"` in
  `build/conf/local.conf` before unpacking.
</Note>

## Make kernel config changes

Edit kernel source or configuration in `build/workspace/sources/linux-qcom`.

To modify the kernel configuration interactively:

1. Open a kas shell (replace `rb3gen2-core-kit.yml` with your machine YML):

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

2. Launch `menuconfig` via devtool:

```bash theme={null}
devtool menuconfig linux-qcom
```

3. The configuration fragment is saved to:

```text theme={null}
build/workspace/sources/linux-qcom/oe-local-files/devtool-fragment.cfg
```

<Note>
  For the mainline kernel, replace `linux-qcom` with `linux-qcom-next`.
</Note>

## Build and test your changes

After editing the kernel source or configuration, build and deploy the kernel
to verify your changes on hardware before committing them.

1. Open a kas shell (replace `rb3gen2-core-kit.yml` with your machine YML):

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

2. Build the kernel only (faster than a full image build):

```bash theme={null}
devtool build linux-qcom
```

3. Build the full flashable image when ready to deploy:

```bash theme={null}
devtool build-image qcom-multimedia-image
```

4. Flash the updated kernel images and reboot. See
   [Install & boot the kernel](./install-and-boot-the-kernel) for the full
   flashing procedure and post-boot verification steps.

## Commit the kernel changes

After editing and testing, commit your changes inside the devtool workspace so
they can be exported as patches. The `-s` flag adds a `Signed-off-by:` trailer,
which is required for patches submitted upstream.

```bash theme={null}
cd build/workspace/sources/linux-qcom
git add .
git commit -s -m "my changes"
```

## Maintain kernel changes

Use `devtool finish` to export your changes as patches and wire them into a
custom meta-layer:

1. Open a kas shell (replace `rb3gen2-core-kit.yml` with your machine YML):

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

2. Create and register a custom layer (first time only):

```bash theme={null}
bitbake-layers create-layer ~/meta-<mylayer>
mkdir -p ~/meta-<mylayer>/recipes-kernel/linux/linux-qcom
bitbake-layers add-layer ~/meta-<mylayer>
```

3. Export patches and configuration fragments into the layer:

```bash theme={null}
devtool finish linux-qcom ~/meta-<mylayer>
```

After `devtool finish`, the layer is updated with:

* Kernel patches in `meta-<mylayer>/recipes-kernel/linux/linux-qcom/*.patch`
* A `bbappend` that adds those patches to `SRC_URI`
* The `build/workspace` entry is removed

The resulting `bbappend` looks like:

```text theme={null}
FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:"

SRC_URI += "file://devtool-fragment.cfg \
            file://0001-my-patch.patch"
```

4. Rebuild the image from the layer to verify the patches apply cleanly:

```bash theme={null}
devtool build-image qcom-multimedia-image
```

## Clean up the workspace

To discard the devtool workspace and return to a clean state:

1. Open a kas shell (replace `rb3gen2-core-kit.yml` with your machine YML):

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

2. Remove the custom layer:

```bash theme={null}
bitbake-layers remove-layer ~/meta-<mylayer>
```

3. Reset the devtool workspace:

```bash theme={null}
devtool reset linux-qcom
```

4. Delete the workspace directory:

```bash theme={null}
rm -rf build/workspace/sources/linux-qcom
```

## Next steps

* To debug kernel issues, see [Configure debug methods](./configure-debug-methods).