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

# 使用 Yocto 构建内核

Yocto 工作流推荐用于完整的 BSP 集成和生产镜像构建。它使用 `kas` 和 BitBake 配合 `meta-qcom` 层，在构建内核的同时构建根文件系统和所有软件包。

<Note>
  对于独立构建（仅内核，不使用 Yocto），请参阅[不使用 Yocto 构建内核](./build-kernel-standalone)。
</Note>

## 访问内核源代码

### 必需的 meta 层

Qualcomm<sup>®</sup> Linux BSP 使用 `meta-qcom` Yocto 层构建。

* **meta-qcom**（层）：[https://github.com/qualcomm-linux/meta-qcom](https://github.com/qualcomm-linux/meta-qcom)

发布标签遵循 `qli-<version>` 约定（例如 `qli-2.0`）。有关可用标签，请参阅 [Qualcomm Linux 发行说明 - 简介](https://dragonwingdocs.qualcomm.com/Key-Documents/Software-Release-Notes/introduction)。

### 使用 kas 同步 meta 层

在您的工作区根目录下运行以下命令。同步后，工作区中将包含一个 `meta-qcom/` 目录。

```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>
```

### 支持的机器配置

机器配置文件位于 `meta-qcom/conf/machine/` 中，遵循 `<SoC>-<board>-<variant>.conf` 命名约定，其中：

* `SoC` 是片上系统名称
* `board` 是开发板类型
* `variant` 是产品类型

以下示例列出了支持的机器配置：

```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
```

内核配方和版本在公共 include 文件 `meta-qcom/conf/machine/include/qcom-base.inc` 中选择，每个机器配置都会继承该文件：

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

<Note>
  对于 LTS BSP 选择 `linux-qcom`。对于主线（mainline）BSP 选择 `linux-qcom-next`，并将 `PREFERRED_VERSION_virtual/kernel` 留空。
</Note>

## 镜像配方和内核配置

镜像配方位于 `meta-qcom-distro/recipes-products/images/` 中。下表列出了主要支持的镜像：

**表：Qualcomm<sup>®</sup> Linux 支持的镜像配方**

| 镜像名称                    | 描述                                                  |
| ----------------------- | --------------------------------------------------- |
| `qcom-console-image`    | 包含基本软件包的启动到 shell 的镜像。                              |
| `qcom-multimedia-image` | 包含多媒体软件组件：音频、Bluetooth<sup>®</sup>、摄像头、计算机视觉、显示和视频。 |

<Note>
  有关 Qualcomm Linux 支持的完整镜像列表，请参阅 `meta-qcom-distro/recipes-products/images/`。
</Note>

Qualcomm Linux 内核 BSP 配方使用以下配置片段：

**表：内核配置片段**

| 片段                                | 描述                                 |
| --------------------------------- | ---------------------------------- |
| `arch/arm64/configs/defconfig`    | 用作基础配置的上游 arm64 defconfig。         |
| `arch/arm64/configs/prune.config` | 从上游 defconfig 中裁剪配置以优化构建时间。        |
| `arch/arm64/configs/qcom.config`  | 启用上游 defconfig 中没有的 Qualcomm 特定配置。 |
| `kernel/configs/debug.config`     | 启用标准内核调试配置。                        |
| `kernel/configs/hardening.config` | 启用用于生产内核加固的安全配置。                   |
| `arch/arm64/configs/rt.config`    | 为实时内核构建启用 `PREEMPT_RT`。            |

要修改生效的片段，请更新 `meta-qcom` 层中内核配方内的 `KBUILD_DEFCONFIG` 和 `KBUILD_CONFIG_EXTRA`。以下示例展示了 `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 还维护了一个在其之上应用的发行版级片段：
  `meta-qcom/recipes-kernel/linux/linux-qcom-6.18/configs/bsp-additions.cfg`。
</Note>

## 构建内核和模块

1. 打开 kas shell：

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

2. 构建完整镜像（内核 + 根文件系统）：

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

构建好的镜像位于：

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

内核源代码树在构建期间由 BitBake 解包，可在以下位置获得：

```text theme={null}
build/tmp/work-shared/<machine>/kernel-source/
```

### 启用调试构建

要编译启用调试的构建，请将 `DEBUG_BUILD=1` 设置为环境变量或在 `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
```

## 常见构建错误

**配置更改未反映在构建的镜像中**

如果重新构建后某个内核配置选项未出现在运行的内核中：

1. 将缺失的选项显式添加到 `kernel/configs/debug.config`。
2. 在运行 BitBake 之前设置 `DEBUG_BUILD=1`，以确保应用调试片段：

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

**`do_fetch` 失败**

验证网络连接，并确认内核配方中的 `SRCREV` 与指定分支上存在的提交匹配。检查配方文件 `meta-qcom/recipes-kernel/linux/linux-qcom_6.18.bb` 中固定的发布修订版本。

**构建期间磁盘空间耗尽**

完整的 Yocto 构建至少需要 300 GB 的可用空间和大于 32 GB 的交换分区。清理之前的构建产物以回收空间：

```bash theme={null}
bitbake -c cleanall linux-qcom
```

**`ERROR_QA` 或警告被视为错误**

这些通常是配方元数据问题。在更改配方设置之前，请检查位于 `build/tmp/work/<SoC>-<board>-<variant>/linux-qcom/*/temp/log.do_compile` 的完整 BitBake 日志以找出根本原因。