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

# 修改内核

Qualcomm<sup>®</sup> Linux 内核使用 Yocto `devtool` 工作流进行开发。本页介绍在 Yocto 工作区内进行内核源码和配置修改的“编辑—构建—维护”循环。

<Note>
  本页仅介绍 Yocto `devtool` 工作流。若要在不构建完整镜像的情况下更快地迭代纯内核修改，请参阅 [不使用 Yocto 构建内核](./build-kernel-standalone)。
</Note>

<Note>
  开始之前，请确保您的主机已安装所需工具（`kas`、`git` 以及 Yocto 构建依赖项）。请参阅 [先决条件与主机设置](./prerequisites-and-host-setup)。
</Note>

* 要设置主机并克隆源码，请参阅 [获取内核源码](./access-kernel-sources)。
* 要配置内核并构建镜像，请参阅 [使用 Yocto 构建内核](./build-kernel-yocto)。
* 要在不使用 Yocto 的情况下构建内核，请参阅 [不使用 Yocto 构建内核](./build-kernel-standalone)。
* 要在构建后刷写并验证，请参阅 [安装并启动内核](./install-and-boot-the-kernel)。

有关 Yocto 内核开发机制的更多信息，请参阅
[Yocto Project Linux Kernel Development](https://docs.yoctoproject.org/kernel-dev/)。

## 解包内核源码

使用 `devtool` 将内核源码解包到本地工作区中进行编辑。`devtool modify` 会将内核源码检出到 devtool 工作区，并将配方（recipe）重新指向该本地副本进行构建，因此下次构建时会自动采用您的修改，而无需重新从上游拉取。

1. 在某个发布标签处克隆 `meta-qcom`。发布标签遵循 `qli-<version>` 约定（例如 `qli-2.0`）。有关可用标签，请参阅
   [Qualcomm Linux 发行说明 - 简介](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. 按固定（pinned）版本同步所有元层（meta-layer）。如果您已完成
   [使用 Yocto 构建内核](./build-kernel-yocto#sync-meta-layers-with-kas)
   中的同步步骤，则此步骤已完成。

3. 打开一个 kas shell。将 `rb3gen2-core-kit.yml` 替换为与您开发板匹配的机器 YML。所有受支持的机器 YML 文件位于 `meta-qcom/ci/`。

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

4. 将内核源码解包到 devtool 工作区：

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

内核源码会被检出到 `build/workspace/sources/linux-qcom`。

<Note>
  对于主线（mainline）BSP，请使用 `linux-qcom-next`，并在解包前在
  `build/conf/local.conf` 中设置
  `PREFERRED_PROVIDER_virtual/kernel = "linux-qcom-next"`。
</Note>

## 修改内核配置

在 `build/workspace/sources/linux-qcom` 中编辑内核源码或配置。

要以交互方式修改内核配置：

1. 打开一个 kas shell（将 `rb3gen2-core-kit.yml` 替换为您的机器 YML）：

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

2. 通过 devtool 启动 `menuconfig`：

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

3. 配置片段（fragment）会保存到：

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

<Note>
  对于主线内核，请将 `linux-qcom` 替换为 `linux-qcom-next`。
</Note>

## 构建并测试您的修改

编辑内核源码或配置后，先构建并部署内核，在提交之前在硬件上验证您的修改。

1. 打开一个 kas shell（将 `rb3gen2-core-kit.yml` 替换为您的机器 YML）：

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

2. 仅构建内核（比构建完整镜像更快）：

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

3. 准备部署时，构建完整的可刷写镜像：

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

4. 刷写更新后的内核镜像并重启。完整的刷写流程和启动后验证步骤，请参阅
   [安装并启动内核](./install-and-boot-the-kernel)。

## 提交内核修改

编辑和测试完成后，在 devtool 工作区内提交您的修改，以便将其导出为补丁。`-s` 标志会添加 `Signed-off-by:` 尾注，这是向上游提交补丁所必需的。

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

## 维护内核修改

使用 `devtool finish` 将您的修改导出为补丁并接入自定义元层：

1. 打开一个 kas shell（将 `rb3gen2-core-kit.yml` 替换为您的机器 YML）：

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

2. 创建并注册一个自定义层（仅首次需要）：

```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. 将补丁和配置片段导出到该层：

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

执行 `devtool finish` 后，该层会更新为包含：

* 位于 `meta-<mylayer>/recipes-kernel/linux/linux-qcom/*.patch` 的内核补丁
* 一个将这些补丁添加到 `SRC_URI` 的 `bbappend`
* `build/workspace` 中的条目会被移除

生成的 `bbappend` 如下所示：

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

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

4. 从该层重新构建镜像，以验证补丁可以干净地应用：

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

## 清理工作区

要丢弃 devtool 工作区并恢复到干净状态：

1. 打开一个 kas shell（将 `rb3gen2-core-kit.yml` 替换为您的机器 YML）：

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

2. 移除自定义层：

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

3. 重置 devtool 工作区：

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

4. 删除工作区目录：

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

## 后续步骤

* 要调试内核问题，请参阅 [配置调试方法](./configure-debug-methods)。