meta-qcom - Qualcomm Dragonwing Documentation

meta-qcom 元数据层托管在 git.yoctoproject.org，提供用于构建 Qualcomm BSP 的配方。使用 meta-qcom 层中的配方来构建软件镜像。该层还提供对启用 Qualcomm 设备的支持。注意本指南将 QCM6490 和 QCS6490 硬件 SoC 互换使用。在 meta-qcom/conf/machine/ 目录中定义的 rb3gen2-core-kit.conf 和机器配置文件支持 QCM6490、QCS6490 和 QCS5430 硬件 SoC。

配方	描述
`recipes-devtools/qdl/qdl_git.bb`	Qualcomm Download（QDL）烧录工具与显示 ID 05c6:9008 的 USB 设备通信以上传烧录加载程序，并使用此配方烧录镜像。
`recipes-support/pd-mapper/pd-mapper_<version>.bb`	Qualcomm `pd-mapper` 是保护域映射服务的一种实现。该服务配置和管理保护域，确保应用程序与各种远程处理器之间的安全通信。
`recipes-support/qrtr/qrtr_<version>.bb`	Qualcomm Router（QRTR）是 Qualcomm 片上系统（SoC）中使用的进程间通信机制。QRTR 允许系统中不同处理器（例如应用处理器和调制解调器）之间使用用户空间中套接字风格的编程接口进行通信。
`recipes-support/initrdscripts/initramfs-module-copy-modules_1.0.bb`	用于将内核模块从 `initramfs` 复制到 `rootfs` 的 `initramfs-framework` 模块。
`recipes-multimedia/`	为 Qualcomm 技术提供多媒体配方，包括相机组件、用于图像处理和计算机视觉的优化 Qualcomm FastCV 库、支持 Qualcomm 特定格式和修复的 GStreamer 插件补丁，以及 Qualcomm IM SDK GStreamer 插件。
`recipes-graphics/`	包含 Qualcomm Adreno 图形用户模式库、KGSL 驱动程序以及适用于 MSM 平台的 Mesa GBM 后端的配方。
`lib/qcom/dtb_only_fitimage.py`	用于生成支持 Qualcomm 特定要求的仅 DTB 的 FIT 镜像的工具。
`recipes-ml/`	提供 Qualcomm AI 运行时 SDK 组件的配方，包括工具、运行时和模型执行引擎。
`recipes-bsp/firmware-boot/`	包含为 Qualcomm 平台提供启动固件二进制文件的配方。
`recipes-bsp/firmware/camxfirmware-<soc>_<version>.bb`	提供启用相机功能所需的 Qualcomm 相机固件。
`recipes-bsp/hexagon-dsp-binaries/hexagon-dsp-binaries_<version>.bb`	提供随 Linux 固件发布分发的 Hexagon DSP 二进制文件。这些二进制文件包括通过 FastRPC 接口与相应 DSP 固件一起使用的库和可执行文件，以启用额外的 DSP 功能。
`recipes-bsp/partition/qcom-partition-conf_git.bb`	为 Qualcomm 参考设备提供 GPT 分区二进制文件和 QDL 脚本。
`recipes-bsp/partition/mount-tee-partition_1.0.bb`	将 persist 分区挂载到 `/var/lib/tee`，以存储加密数据并支持与安全相关的功能。

BitBake 类

下表描述了 meta-qcom 提供的自定义 BitBake 类。要浏览类定义，请参阅 classes-recipe 和 classes。

文件	描述
`classes-recipe/dtb-fit-image.bbclass`	创建 `qclinux-fit-image.its` 文件并生成 FIT 镜像（ITB）。该类初始化 ITS 结构，添加 DTB 部分（包括 `qcom-metadata.dtb`），应用 Qualcomm 特定的 ITS 修改，并使用 `mkimage` 组装最终镜像。
`classes-recipe/image-adbd.bbclass`	当 OpenEmbedded 层可用时，将 `adbd` 守护进程安装到镜像中。`adbd` 守护进程默认禁用，仅当 `IMAGE_FEATURES` 包含 `enable-adbd` 时才启用。
`classes-recipe/image_types_qcom.bbclass`	添加对新 `IMAGE_FSTYPE` 的支持，该类型创建一个包含完整全新烧录所需的所有产物的单一 tarball，包括分区元数据、启动固件、ESP 分区和根文件系统。
`classes/linux-qcom-bootimg.bbclass`	实现生成由内核镜像、ramdisk 镜像和内核命令行组成的 `boot.img` 文件的逻辑。生成的 `boot.img` 可在使用 LK 或 fastboot 的机器上启动。
`classes/linux-qcom-dtbbin.bbclass`	生成由符合 ARM SystemReady IR 标准的 Qualcomm UEFI 固件加载的 DTB 镜像。固件支持通过从 DTB 分区读取 `combined-dtb.dtb` 或 `qclinux_fit.img` 来加载匹配的设备树。
`classes/uki-esp-image.bbclass`	使用 OE-Core `uki.bbclass` 基础设施组装包含 systemd-boot 和 UKI 的 ESP 镜像。

机器配置

Qualcomm Linux 机器配置文件可在 GitHub 上获取。位于 meta-qcom/conf/machine/include 目录中的文件定义并设置所需的 BitBake 变量，这些变量通常由 Qualcomm BSP 定义的机器配置使用。下表概述了这些文件。

文件	描述
`meta-qcom/conf/machine/include/qcom-base.inc`	此文件设置 Qualcomm BSP 中定义的所有机器配置通常共享的 BitBake 变量。例如 `PREFERRED_PROVIDER` 和 `IMAGE_FSTYPES`。
`meta-qcom/conf/machine/include/qcom-common.inc`	定义默认的 `MACHINE_FEATURES` 集合和 `QCOM_XBL_CONFIG` 变量。当 `MACHINE_FEATURES` 中存在 `kvm` 时，`QCOM_XBL_CONFIG` 会自动选择 `xbl_config_kvm.elf` 而不是 `xbl_config.elf`，从而启用支持 KVM 的启动固件。
`meta-qcom/conf/machine/include/qcom-qcs6490.inc`	此文件将 `SOC_FAMILY` 变量设置为 `qcm6490`。此文件还定义了所有基于 QCS6490 的 Qualcomm 开发套件共享的配置变量。
`meta-qcom/conf/machine/include/qcom-qcs9100.inc`	此文件将 `SOC_FAMILY` 变量设置为 `qcs9100`。此文件还定义了所有基于 QCS9100 的 Qualcomm 开发套件共享的配置变量。
`meta-qcom/conf/machine/include/qcom-qcs8300.inc`	此文件将 `SOC_FAMILY` 变量设置为 `qcs8300`。此文件还定义了所有基于 QCS8300 的 Qualcomm 开发套件共享的配置变量。
`meta-qcom/conf/machine/include/qcom-qcs615.inc`	此文件将 `SOC_FAMILY` 变量设置为 `qcs615`。此文件还定义了所有基于 QCS615 的 Qualcomm 开发套件共享的配置变量。
`meta-qcom/conf/machine/include/qcom-hamoa.inc`	此文件将 `SOC_FAMILY` 变量设置为 `hamoa`。它定义了基于 IQ-X7181（Hamoa）平台的开发套件共享的配置变量。
`meta-qcom/conf/machine/include/qcom-shikra.inc`	此文件将 `SOC_FAMILY` 变量设置为 `shikra`。它定义了基于 Shikra 平台的开发套件共享的配置变量。

基于 QCS6490 的开发套件的机器配置文件

配置文件	描述
`conf/machine/qcm6490-idp.conf`	此文件适用于搭载 QCM6490 的集成开发平台（IDP）。
`conf/machine/rb3gen2-core-kit.conf`	此文件适用于搭载 QCS6490 SoC 的 Qualcomm Dragonwing^™ RB3 Gen 2 Core 开发套件。

基于 IQ-9075 和 IQ-9100 的开发套件的机器配置文件

配置文件	描述
`conf/machine/qcs9100-ride-sx.conf`	此文件适用于搭载 IQ-9100 SoC 的 Qualcomm^® IQ-9 Beta 评估套件（EVK）。
`conf/machine/iq-9075-evk.conf`	此文件适用于搭载 IQ-9075 SoC 的 Qualcomm Dragonwing^™ IQ-9075 EVK。KVM 硬件加速默认启用（`MACHINE_FEATURES` 中包含 `kvm`）。

基于 IQ-8275 的开发套件的机器配置文件

配置文件	描述
`conf/machine/qcs8300-ride-sx.conf`	此文件适用于搭载 IQ-8300 SoC 的 Qualcomm^® IQ-8 Beta EVK。
`conf/machine/iq-8275-evk.conf`	此文件适用于搭载 IQ-8275 SoC 的 Qualcomm Dragonwing^™ IQ-8275 EVK。KVM 硬件加速默认启用（`MACHINE_FEATURES` 中包含 `kvm`）。

基于 IQ-615 的开发套件的机器配置文件

配置文件	描述
`conf/machine/iq-615-evk.conf`	此文件适用于搭载 IQ-615 SoC 的 Qualcomm Dragonwing^™ IQ-615 EVK。

IQ-X5121 和 IQ-X7181 的机器配置文件

配置文件	描述
`conf/machine/iq-x5121-evk.conf`	此文件适用于 Qualcomm Dragonwing^™ IQ-X5121 EVK（Purwa IoT 平台）。
`conf/machine/iq-x7181-evk.conf`	此文件适用于 Qualcomm Dragonwing^™ IQ-X7181 EVK（Hamoa IoT 平台）。

Shikra 的机器配置文件

配置文件	描述
`conf/machine/shikra-evk.conf`	此文件适用于 Qualcomm Dragonwing^™ Shikra Alpha 评估套件 (EVK)。

内核命令行

recipes-kernel/images/esp-qcom-image.bb 设置 UKI_CMDLINE 变量。在生成 UKI 镜像时，此变量作为 –cmdline= 传递给 ukify 工具。meta-qcom/conf/machine/include/qcom-base.inc 设置变量 QCOM_BOOTIMG_ROOTFS 和 SERIAL_CONSOLES，这些变量用于组成 UKI_CMDLINE 变量。

包含 DTB 和 DTB 覆盖

KERNEL_DEVICETREE 变量用于将所需的 DTB 和 DTB 覆盖打包到 FIT 镜像中。此变量在位于 meta-qcom/conf/machine 的各个机器配置文件中配置。例如，conf/machine/rb3gen2-core-kit.conf 文件设置 KERNEL_DEVICETREE 变量，从而选择合适的 DTB： rb3gen2-core-kit.conf 以下代码块展示了如何设置 KERNEL_DEVICETREE。

KERNEL_DEVICETREE ?= " \
                      qcom/qcs6490-rb3gen2.dtb \
                      qcom/qcs6490-rb3gen2-industrial-mezzanine.dtbo \
                      qcom/qcs6490-rb3gen2-vision-mezzanine.dtbo \
                     "

# These DTs are not upstreamed and currently exist only in linux-qcom kernels
LINUX_QCOM_KERNEL_DEVICETREE ?= " \
                     qcom/qcs6490-rb3gen2-vision-mezzanine-camx.dtbo \
                     "

列出的 DTB 和 DTB 覆盖通过 conf/machine/include/fit-dtb-compatible.inc 文件中的 FIT_DTB_COMPATIBLE 条目打包到 FIT 镜像中。

FIT_DTB_COMPATIBLE[qcom_qcs5430-iot] = "qcs6490-rb3gen2"
FIT_DTB_COMPATIBLE[qcom_qcs6490-iot] = "qcs6490-rb3gen2"

FIT_DTB_COMPATIBLE[qcom_qcs5430-iot-subtype9] = \
    "qcs6490-rb3gen2 qcs6490-rb3gen2-industrial-mezzanine"
FIT_DTB_COMPATIBLE[qcom_qcs6490-iot-subtype9] = \
    "qcs6490-rb3gen2 qcs6490-rb3gen2-industrial-mezzanine"

FIT_DTB_COMPATIBLE[qcom_qcs5430-iot-subtype2] = \
    "qcs6490-rb3gen2 qcs6490-rb3gen2-vision-mezzanine"
FIT_DTB_COMPATIBLE[qcom_qcs6490-iot-subtype2] = \
    "qcs6490-rb3gen2 qcs6490-rb3gen2-vision-mezzanine"

这将生成如下配置的 FIT 镜像：

conf-w {
   fdt="fdt-qcs6490-rb3gen2.dtb";
   compatible="qcom,qcs5430-iot";
};

conf-x {
   fdt="fdt-qcs6490-rb3gen2.dtb";
   compatible="qcom,qcs6490-iot";
};

conf-y {
   fdt = "fdt-qcs6490-rb3gen2.dtb", "fdt-qcs6490-rb3gen2-industrial-mezzanine.dtbo";
   compatible = "qcom,qcs5430-iot-subtype9";
};

conf-z {
   fdt = "fdt-qcs6490-rb3gen2.dtb", "fdt-qcs6490-rb3gen2-industrial-mezzanine.dtbo";
   compatible = "qcom,qcs6490-iot-subtype9";
};

固件配方

Qualcomm Linux 固件配方文件可在 GitHub 上获取。同步 Qualcomm Linux 源代码后，固件配方位于 <workspace>/meta-qcom/recipes-bsp/firmware-boot、<workspace>/meta-qcom/recipes-bsp/hexagon-dsp-binaries 目录中。

启动固件二进制文件

启动设备需要关键的启动固件镜像。以下固件配方提供特定于硬件 SoC 的启动固件。

固件配方	描述
`meta-qcom/recipes-bsp/firmware-boot`	处理兼容机器的关键启动固件二进制文件的获取、解包和部署。`QCM6490_bootbinaries.zip`、`QCS9100_bootbinaries.zip`、`QCS8300_bootbinaries.zip` 和 `SHIKRA_bootbinaries.zip` 文件提供基于 QCS6490、QCS9075、QCS8300 和 Shikra 的机器所需的启动固件。

生成构建后，这些 zip 文件中的固件二进制文件可在以下目录中用于烧录：<workspace>/build/tmp/deploy/images/<machine-name>/<image-name>.qcomflash/

子系统固件二进制文件

Qualcomm Linux 包含在相应子系统上加载和运行的固件二进制文件。当 Qualcomm 硬件 SoC 启动时，各个子系统在退出复位状态后运行固件。linux-firmware 配方提供上游固件软件包并将它们安装到 /usr/lib/firmware 目录中。

固件配方	描述
`openembedded-core/meta/recipes-kernel/linux-firmware/linux-firmware_%.bb`	处理子系统固件二进制文件（例如 aDSP、cDSP、调制解调器、VPU、GPU 和 WLAN）的获取、解包和安装。

linux-firmware_%.bb 配方执行以下操作：

获取子系统固件二进制文件。

解包 tar 文件。

将固件安装到 /usr/lib/firmware/。

DSP 库

用户空间实用程序引用数字信号处理器（DSP）库，这些库必须在 rootfs 镜像中可用。以下固件配方提供特定于硬件 SoC 的 DSP 库：

固件配方	描述
`meta-qcom/recipes-bsp/hexagon-dsp-binaries/hexagon-dsp-binaries_%.bb`	处理托管在 github.com/linux-msm/dsp-binaries 上的 DSP 库的获取、解包和安装

hexagon-dsp-binaries_%.bb 配方执行以下操作：

从 GitHub 仓库获取 DSP 库。

解包 zip 文件。

将 DSP 库安装到 rootfs 中。

boot、subsystem 和 dspso 的安装

构建 Qualcomm Linux 时，构建系统使用固件配方根据机器配置文件中设置的 MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS 配置变量部署固件。例如，在 conf/machine/iq-9075-evk.conf 中，可以看到 MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS 变量中包含了 packagegroup-iq-9075-evk-firmware：

MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += " \
   packagegroup-iq-9075-evk-firmware \
   packagegroup-iq-9075-evk-hexagon-dsp-binaries \
   qairt-sdk-hexagon-v73 \
   qcom-fastcv-binaries-sa8775p-ride-dsp \
   qps615-dlkm \
   "

注意 packagegroup-iq-9075-evk 配方位于 <workspace>/meta-qcom/recipes-bsp/packagegroups/ 目录中。它将固件配方分组以生成镜像。构建 Qualcomm Linux 时，根据机器配置和软件包组配方文件中的配置，将构建来自 <workspace>meta-qcom/recipes-bsp/firmware 目录的相应固件配方。

内核配方

Qualcomm Linux 使用的 Linux 内核配方位于 <workspace>/meta-qcom/recipes-kernel/linux。Qualcomm Linux 支持长期支持（LTS）版 Qualcomm Linux 内核 v6.18.x。在 meta-qcom 层中，有两个内核配方：

内核配方	用途
`linux-qcom_6.18.bb`	构建标准 Qualcomm Linux 内核镜像。该配方使用 `qcom-6.18.y` 分支上固定的 `SRCREV` 从 `github.com/qualcomm-linux/kernel` 获取内核源代码。
`linux-qcom-rt_6.18.bb`	构建实时 Qualcomm Linux 内核镜像。它依赖 `linux-qcom_6.18.bb` 并应用 `rt.config` 将内核配置为实时运行。

linux-qcom_6.18.bblinux-qcom-rt_6.18.bb

inherit kernel
COMPATIBLE_MACHINE = "(qcom)"
LINUX_VERSION ?= "6.18.30"

# tag:qcom-6.18.y-20260601
SRCREV ?= "b7cce9a3884a873855693af8591d4c9c469cd17e"

SRCBRANCH ?= "nobranch=1"
SRCBRANCH:class-devupstream ?= "branch=qcom-6.18.y"

SRC_URI = "git://github.com/qualcomm-linux/kernel.git;${SRCBRANCH};protocol=https"
# Additional kernel configs.
SRC_URI += " \
    file://configs/bsp-additions.cfg \
"
KBUILD_DEFCONFIG ?= "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"

内核配置 Qualcomm Linux 内核配方使用一组不同的内核配置和片段。

变体	配置和片段文件
`linux-qcom_6.18.bb`	`defconfig`、`hardening.config`、`prune.config`、`qcom.config`、`bsp-additions.cfg`
`linux-qcom-rt_6.18.bb`	使用与 `linux-qcom_6.18.bb` 相同的配置并添加 `rt.config`

许可证

meta-qcom 中配方的许可证列于 <workspace>/meta-qcom/licenses。

licenses/
├── LICENSE.qcom
└── LICENSE.qcom-2

Yocto 可以在创建镜像时自动创建 SPDX SBOM 文档。要启用此功能，请按照以下步骤操作：

在 local.conf 中继承 create-spdx 类，如下所示：
INHERIT += "create-spdx"
继承该类后，使用 BitBake 命令重新构建镜像：
bitbake qcom-multimedia-image

您可以在以下目录中找到 SPDX 输出：

对于每个配方，生成的文件位于 tmp/deploy/spdx/<machine> 目录中。

顶级 SPDX 输出文件位于 tmp/deploy/images/<machine>/ 目录中。

后续步骤

要添加自定义机器配置，请参阅添加自定义机器配置。
有关内核开发和设备树自定义，请参阅 Qualcomm Linux 内核指南。
要使用配方处理树外内核模块和设备树，请参阅使用配方处理树外内核模块和设备树。

​BitBake 类

​机器配置

​基于 QCS6490 的开发套件的机器配置文件

​基于 IQ-9075 和 IQ-9100 的开发套件的机器配置文件

​基于 IQ-8275 的开发套件的机器配置文件

​基于 IQ-615 的开发套件的机器配置文件

​IQ-X5121 和 IQ-X7181 的机器配置文件

​Shikra 的机器配置文件

​内核命令行

​包含 DTB 和 DTB 覆盖

​固件配方

​启动固件二进制文件

​子系统固件二进制文件

​DSP 库

​boot、subsystem 和 dspso 的安装

​内核配方

​许可证

​后续步骤