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

# 在 QIR SDK 上启用和评估 Qualcomm Linux overlays

Qualcomm Linux overlays 是模块化的、增值型组件 —— 用于诸如音频、摄像头、图形、视频、传感器和视觉等技术的源代码或预构建二进制文件 —— 与上游组件集成。

Overlays 让你可以在平台级别在上游和 Qualcomm 技术栈之间进行选择。有关 overlays 的介绍，请参见 [启用和评估 Qualcomm Linux overlays](../../Key-Documents/Migration-Guide/enable-and-evaluate-qualcomm-linux-overlays)。

多个 QIR SDK 包和示例应用都构建在 Qualcomm 技术栈之上。这些包无法在纯上游镜像上运行，因为它们所链接的 Qualcomm 用户空间库和树外内核驱动模块都是以 overlays 形式交付的。

使用以下信息可以：

* 将每个 QIR SDK 镜像与 overlay 配置匹配。
* 识别每个 QIR SDK 包和示例应用所依赖的 overlays。
* 在启用相应的 overlays 后，在设备上安装 QIR SDK 包和示例应用。

<Note>
  **注意**

  本页面仅涵盖工作流中特定于 QIR SDK 的部分。启用 overlays 本身是一项平台级任务，包括：

  * 刷写基础镜像
  * 配置包源
  * 安装 overlay RPMs
  * 将上游驱动模块加入黑名单
  * 为摄像头设置可扩展固件接口 (EFI) 变量

  有关这些说明，请参见 [使用支持的工作流评估 overlays](/zh/Key-Documents/Migration-Guide/evaluate-overlays-using-supported-workflows)。
</Note>

## QIR SDK 的 Overlay 配置

Qualcomm Linux 将 Qualcomm 技术栈分组为四个经过验证的 overlay 配置：`Config #1` 到 `Config #4`。每个配置定义了给定技术领域使用的是上游栈还是 Qualcomm 栈。有关每个配置的定义以及对应的平台镜像 recipe，请参见 [使用 overlay 配置派生镜像 recipe](/zh/Key-Documents/Migration-Guide/use-overlay-configurations-to-derive-image-recipes)。

QIR SDK 镜像 recipe 分层构建在这些平台配置之上。下表将每个 QIR SDK 镜像 recipe 映射到其 overlay 配置和平台镜像 recipe。

<p style={{ textAlign: 'center', fontWeight: 'bold' }}>
  表：QIR SDK 镜像 recipe 及对应的 overlay 配置
</p>

<table>
  <thead>
    <tr>
      <th style={{ width: '10%' }}>Overlay 配置</th>
      <th style={{ width: '20%' }}>平台镜像 recipe</th>
      <th style={{ width: '20%' }}>QIR SDK 镜像 recipe</th>
      <th style={{ width: '50%' }}>说明</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>`Config #1`</td>
      <td>`qcom-multimedia-image`</td>
      <td>`qcom-robotics-image`</td>
      <td><p>完全上游栈。包括：</p>
      <ul><li>ROS 2 Jazzy</li>
      <li>开源 qrb-ros 包</li>
      <li>仿真示例</li>
      <li>第三方驱动</li>
      <li>QIR SDK 制品</li></ul>
      没有专有依赖。</td>
    </tr>

    <tr>
      <td>`Config #2`</td>
      <td>`qcom-multimedia-proprietary-image`</td>
      <td>`qcom-robotics-proprietary-image`</td>
      <td><p>完整的 Qualcomm 栈。包括 `qcom-robotics-image` 中的所有内容，以及依赖 Qualcomm 专有库的 `qrb-ros` 包和 AI 示例应用。</p></td>
    </tr>
  </tbody>
</table>

## 安装顺序

overlay 工作流有四个阶段，每个阶段都依赖于前一个阶段。请按顺序完成：

1. [安装多媒体 overlay 包](#install-the-multimedia-overlay-packages) — 启用平台音频、摄像头、视频和图形栈。
2. [在设备上设置 robotics DNF 存储库](#set-up-the-robotics-dnf-repository-on-the-device) — 将设备指向 robotics 包源。
3. [安装 robotics overlay 包](#install-the-robotics-overlay-packages) — 安装依赖 overlays 的 `qrb-ros` 包。
4. [安装依赖 overlays 的 robotics 示例应用](#install-the-robotics-sample-applications-that-depend-on-overlays) — 安装基于这些包构建的示例。

## 前提条件

在你安装本页描述的 QIR SDK 包之前，请完成以下步骤：

1. 下载预构建的 `qcom-robotics-image`（Overlay `Config #1`）。有关说明，请参见 [下载预构建包](./download-the-prebuilt-packages)
2. 在你的设备上刷写 `qcom-robotics-image`。有关说明，请参见 [刷写 robotics 镜像](./flash-the-robotics-image)。
3. 使用以下方法之一获取目标的 QIR SDK RPMs：
   * 从 Qualcomm Linux 包源下载它们。有关说明，请参见 [从 Qualcomm Linux 参考包服务器安装包](../../Key-Documents/Migration-Guide/evaluate-overlays-using-supported-workflows#install-packages-from-the-qualcomm-linux-reference-package-server)。
   * 从源码构建它们。有关说明，请参见 [设置本地工作区](#set-up-a-local-workspace)。

## 安装多媒体 overlay 包

本页描述的 QIR SDK 包都构建在 Qualcomm 多媒体栈 —— 音频、摄像头、视频和图形 —— 之上。Qualcomm Linux 将这些栈作为平台级的多媒体 overlay 包交付，因此在安装任何 QIR SDK 包之前，请先为你的目标 overlay 配置安装多媒体 overlay 包。

多媒体 overlay 设置是一项平台级任务。它包括配置平台 DNF 存储库、安装 overlay RPMs、将相应的上游内核模块加入黑名单，以及 —— 对于摄像头 overlay —— 通过 EFI 变量选择 CamX 设备树 blob (DTB) overlay。

有关每个多媒体 overlay 的 `dnf install` 命令、模块黑名单条目和 EFI 变量设置，请参见 Qualcomm Linux 迁移指南中的以下部分：

* [从 Qualcomm Linux 参考包服务器安装包](/zh/Key-Documents/Migration-Guide/evaluate-overlays-using-supported-workflows#install-packages-from-the-qualcomm-linux-reference-package-server)
* [运行 DNF 安装命令派生 Config #2、Config #3 和 Config #4](/zh/Key-Documents/Migration-Guide/evaluate-overlays-using-supported-workflows#run-dnf-installation-commands-to-derive-config-2-config-3-and-config-4)
* [验证 RPM 和驱动包的安装](/zh/Key-Documents/Migration-Guide/evaluate-overlays-using-supported-workflows#verify-the-installation-of-rpm-and-driver-packages)

<Note>
  **注意**

  安装 overlay RPMs 并更新黑名单或 EFI 变量后，请重启设备。如果 overlay 内核模块未加载，QIR SDK 包无法加载它们的运行时依赖。
</Note>

## 在设备上设置 robotics DNF 存储库

使用 DNF 在设备上安装 QIR SDK RPMs。DNF 从配置在 `/etc/yum.repos.d/` 中的存储库解析包的依赖项。因此，在运行任何 `dnf install` 命令之前，请先配置 robotics 存储库。以下步骤将设备指向 CodeLinaro 上的远程 Qualcomm Linux robotics 包源。

1. 确保设备可以网络访问 `https://artifacts.codelinaro.org`。

2. 创建 `/etc/yum.repos.d/overlay.repo` 文件，并附加你目标的配置。

   * 第一个块是特定于架构的源，对所有支持的目标都相同。
   * 第二个块是特定于目标的源。

   <CodeGroup>
     ```text IQ-9075-EVK theme={null}
     [overlay-armv8_2a]
     name = Qualcomm Overlay Repository (armv8_2a)
     baseurl = https://artifacts.codelinaro.org/qli-robotics-yocto-rpm-signed/qli-2.1/rpm/armv8_2a/
     enabled = 1
     gpgcheck = 0
     repo_gpgcheck=0

     [overlay-iq-9075-evk]
     name = Qualcomm Overlay Repository IQ-9075 EVK
     baseurl = https://artifacts.codelinaro.org/qli-robotics-yocto-rpm-signed/qli-2.1/rpm/iq-9075-evk/
     enabled = 1
     gpgcheck = 0
     repo_gpgcheck=0
     ```

     ```text IQ-8275-EVK theme={null}
     [overlay-armv8_2a]
     name = Qualcomm Overlay Repository (armv8_2a)
     baseurl = https://artifacts.codelinaro.org/qli-robotics-yocto-rpm-signed/qli-2.1/rpm/armv8_2a/
     enabled = 1
     gpgcheck = 0
     repo_gpgcheck=0

     [overlay-iq-8275-evk]
     name = Qualcomm Overlay Repository IQ-8275 EVK
     baseurl = https://artifacts.codelinaro.org/qli-robotics-yocto-rpm-signed/qli-2.1/rpm/iq-8275-evk/
     enabled = 1
     gpgcheck = 0
     repo_gpgcheck=0
     ```
   </CodeGroup>

   <Note>
     **注意**

     * `/etc/yum.repos.d/` 是存储库配置文件的目录。请确保此目录存在；如果不存在，请创建它。
   </Note>

3. 要刷新包索引，请运行以下命令：

   ```bash theme={null}
   dnf update
   ```

4. 要安装一个包，请使用包名运行 `dnf install` 命令：

   ```bash theme={null}
   # Install by package name. DNF selects the package from the configured repositories.
   dnf install <package_name> -y
   ```

   <Note>
     **注意**

     * 使用 `dnf install` 而不是 `rpm -i`，以便自动解析并安装该包的依赖项。
     * 要列出已配置存储库中可用的包，请运行 `dnf list available`。
   </Note>

   robotics overlay 包的 `dnf install` 命令列在 [安装 robotics overlay 包](#install-the-robotics-overlay-packages) 中。

## 安装 robotics overlay 包

Robotics overlay 包是链接到 Qualcomm 多媒体栈的 QIR SDK `qrb-ros` 包。请在对应的多媒体 overlay 包就位后再安装它们。

下表列出了每个 robotics overlay 包及其依赖的多媒体 overlay。

**表：Robotics overlay 包及其 overlay 依赖**

| **技术领域** | **QIR SDK 包**                                                                                       | **Overlay 依赖**                              |
| :------- | :-------------------------------------------------------------------------------------------------- | :------------------------------------------ |
| 音频       | [`qrb-ros-audio`](./enable-core-audio-with-qrb-ros-audio-service)                                   | 音频 overlay (AudioReach)                     |
| 摄像头      | [`qrb-ros-camera`](./run-a-zero-copy-camera-with-qrb-ros-camera)                                    | 摄像头 overlay (CamX)                          |
| 视频       | [`qrb-ros-video`](./encode-and-decode-video-with-qrb-ros-video)                                     | 视频 overlay (`iris-video-dlkm`)              |
| 图形       | [`qrb-ros-colorspace-convert`](./convert-between-nv-12-and-rgb-888-with-qrb-ros-colorspace-convert) | 图形 overlay（`kgsl-dlkm` 和 `qcom-adreno`）     |
| AI 推理    | [`qrb-ros-nn-inference`](./execute-ai-model-inference-with-qrb-ros-nn-inference)                    | Qualcomm AI Engine Direct SDK (`qairt-sdk`) |

在设备上运行与你的技术领域对应的命令。

<CodeGroup>
  ```bash title="Audio" theme={null}
  dnf install libqrb-audio-common-lib1 -y
  dnf install libqrb-audio-manager1 -y
  dnf install qrb-ros-audio-service-msgs -y
  dnf install qrb-ros-audio-service -y
  ```

  ```bash title="Camera" theme={null}
  # Install the packages
  dnf install qrb-camera qrb-ros-camera -y

  # Select the CamX device tree blob (DTB) overlay through the EFI variable
  echo -n "camx" > /tmp/overlay
  efivar -n 882f8c2b-9646-435f-8de5-f208ff80c1bd-VendorDtbOverlays -w -f /tmp/overlay
  efivar -n 882f8c2b-9646-435f-8de5-f208ff80c1bd-VendorDtbOverlays -p
  sync
  reboot
  ```

  ```bash title="Video" theme={null}
  dnf install qrb-ros-video -y
  dnf install libv4l2codecs1 -y
  dnf install iris-video-dlkm -y
  ```

  ```bash title="Graphics" theme={null}
  dnf install qrb-colorspace-convert-lib -y
  dnf install qrb-ros-colorspace-convert -y
  ```

  ```bash title="AI inference" theme={null}
  dnf install qairt-sdk -y
  ```
</CodeGroup>

<Note>
  **注意**

  * 上述命令按名称安装包，因此 DNF 从配置的存储库中解析版本和特定于目标的构建。如果你改为安装本地 RPM 文件，文件名还包括包版本和特定于目标的后缀，例如 `iq_9075_evk`。请将版本和后缀替换为匹配你的发布快照和目标的值。
  * `armv8_2a` 包是特定于架构的，对所有支持的目标都相同。
</Note>

## 安装依赖 overlays 的 robotics 示例应用

下表列出了依赖 overlays 的 QIR SDK 示例应用、它们的依赖以及在设备上安装它们的命令。

<Note>
  **注意**

  在安装依赖某些 overlays 的示例应用之前，请先安装 [安装 robotics overlay 包](#install-the-robotics-overlay-packages) 中列出的包。例如，`sample-apriltag` 需要 `qrb-ros-camera` 和 `qrb-ros-nn-inference`，而它们又需要摄像头和 AI 推理 overlays。
</Note>

**表：示例应用、依赖和安装命令**

| **示例应用**                                                                                   | **Overlay 依赖**                                 | **安装命令**                                      |
| :----------------------------------------------------------------------------------------- | :--------------------------------------------- | :-------------------------------------------- |
| [`sample-hand-detection`](./detect-hands-with-sample-hand-detection)                       | `qrb-ros-camera`, `qrb-ros-nn-inference`       | `dnf install sample-hand-detection -y`        |
| [`sample-resnet101`](./classify-images-with-sample-resnet101)                              | `qrb-ros-camera`, `qrb-ros-nn-inference`       | `dnf install sample-resnet101 -y`             |
| [`sample-object-detection`](./detect-objects-with-sample-object-detection)                 | `qrb-ros-camera`, `qrb-ros-nn-inference`       | `dnf install sample-object-detection -y`      |
| [`sample-object-segmentation`](./segment-objects-with-sample-object-segmentation)          | `qrb-ros-camera`, `qrb-ros-nn-inference`       | `dnf install sample-object-segmentation -y`   |
| [`sample-hrnet-pose-estimation`](./estimate-human-poses-with-sample-hrnet-pose-estimation) | `qrb-ros-camera`, `qrb-ros-nn-inference`       | `dnf install sample-hrnet-pose-estimation -y` |
| [`sample-face-detection`](./detect-faces-with-sample-face-detection)                       | `qrb-ros-camera`, `qrb-ros-nn-inference`       | `dnf install sample-face-detection -y`        |
| [`sample-depth-estimation`](./estimate-image-depth-values-with-sample-depth-estimation)    | `qrb-ros-camera`, `qrb-ros-nn-inference`       | `dnf install sample-depth-estimation -y`      |
| [`sample-apriltag`](./enable-april-tag-pipeline-with-sample-apriltag)                      | `qrb-ros-camera`, `qrb-ros-colorspace-convert` | `dnf install sample-apriltag -y`              |

## 验证安装

1. 要验证 overlay 驱动模块已加载，请使用 [验证 RPM 和驱动包的安装](../../Key-Documents/Migration-Guide/evaluate-overlays-using-supported-workflows#verify-the-installation-of-rpm-and-driver-packages) 中列出的 `lsmod` 命令。

2. 要验证 QIR SDK 包已安装，请运行以下命令：

   ```bash theme={null}
   dnf list installed | grep <package_name>
   ```

3. 要验证包提供的 ROS 2 节点可用，请运行以下命令：

   ```bash theme={null}
   source /usr/share/qirp-setup.sh
   ros2 pkg list | grep <package_name>
   ```

4. 运行相应的示例应用以确认端到端流水线。有关说明，请参见 [示例应用](./qir-sdk-sample-applications)。

## 卸载 overlays

要移除某个 overlay 配置的下游 RPM 包并切换回上游驱动，请参见 [卸载 overlay 配置并切换到上游驱动](../../Key-Documents/Migration-Guide/uninstall-overlays)。

## 从源码构建 QIR SDK 镜像和 RPM 包

除了从包源安装预构建 RPMs 之外，你还可以从源码构建 QIR SDK 镜像和包。当你想集成自己的更改，然后刷写 Config #1 镜像并安装从 Config #2 构建生成的 overlay 和 QIR SDK 包时，请使用此工作流。这是 [本地构建、刷写镜像并使用本地构建的包](../../Key-Documents/Migration-Guide/evaluate-overlays-using-supported-workflows#build-locally-flash-images-and-use-packages-from-the-local-build) 中描述的平台工作流的 QIR SDK 版本。

### 设置本地工作区

1. 准备你的主机计算机，并安装 KAS 工具。有关说明，请参见 [为构建设置主机计算机](./build-with-git-hub-workflow#set-up-the-host-computer-for-build)。

2. 要克隆 `meta-qcom-robotics-sdk`，请运行以下命令：

   ```shell theme={null}
   git clone https://github.com/qualcomm-linux/meta-qcom-robotics-sdk \
   -b qli-2.1
   ```

3. 要构建 Config #1 的镜像 `qcom-robotics-image`，请运行以下命令：

   <CodeGroup>
     ```bash IQ-9075-EVK theme={null}
     kas build meta-qcom-robotics-sdk/ci/iq-9075-evk.yml:meta-qcom-robotics-sdk/ci/qcom-robotics-distro.yml:meta-qcom-robotics-sdk/ci/qcom-robotics-image.yml:meta-qcom-robotics-sdk/ci/linux-qcom-6.18.yml:meta-qcom-robotics-sdk/ci/performance.yml
     ```

     ```bash IQ-8275-EVK theme={null}
     kas build meta-qcom-robotics-sdk/ci/iq-8275-evk.yml:meta-qcom-robotics-sdk/ci/qcom-robotics-distro.yml:meta-qcom-robotics-sdk/ci/qcom-robotics-image.yml:meta-qcom-robotics-sdk/ci/linux-qcom-6.18.yml:meta-qcom-robotics-sdk/ci/performance.yml
     ```
   </CodeGroup>

4. 要构建 Config #2 的镜像 `qcom-robotics-proprietary-image` 及所有包，请运行以下命令：

   <CodeGroup>
     ```bash IQ-9075-EVK theme={null}
     kas build meta-qcom-robotics-sdk/ci/iq-9075-evk.yml:meta-qcom-robotics-sdk/ci/qcom-robotics-distro.yml:meta-qcom-robotics-sdk/ci/qcom-robotics-proprietary-image.yml:meta-qcom-robotics-sdk/ci/linux-qcom-6.18.yml:meta-qcom-robotics-sdk/ci/performance.yml
     ```

     ```bash IQ-8275-EVK theme={null}
     kas build meta-qcom-robotics-sdk/ci/iq-8275-evk.yml:meta-qcom-robotics-sdk/ci/qcom-robotics-distro.yml:meta-qcom-robotics-sdk/ci/qcom-robotics-proprietary-image.yml:meta-qcom-robotics-sdk/ci/linux-qcom-6.18.yml:meta-qcom-robotics-sdk/ci/performance.yml
     ```
   </CodeGroup>

   <Note>
     **注意**

     `qcom-robotics-distro.yml` 将 DISTRO 设置为 `qcom-robotics-distro`，这启用了使用 DNF 的包管理，并允许安装 RPMs。有关支持的 MACHINE、DISTRO、TARGET 和 KERNEL 组合的完整列表，请参见 [构建 robotics 镜像](./build-with-git-hub-workflow#build-the-robotics-image)。
   </Note>

5. 刷写在步骤 3 中构建的 `qcom-robotics-image` 镜像。有关说明，请参见 [刷写 robotics 镜像](./flash-the-robotics-image)。

6. 从构建工作区的 `rpm` 目录中收集由 `qcom-robotics-proprietary-image` 构建生成的 RPMs：

   ```shell theme={null}
   build/tmp/deploy/rpm
   ```

   `rpm` 目录包含以下子目录：

   | **子目录**                         | **内容**               |
   | :------------------------------ | :------------------- |
   | `armv8_2a/`                     | 对所有支持的目标都相同的特定于架构的包。 |
   | `iq_9075_evk/` 或 `iq_8275_evk/` | 特定于目标的包。             |
   | `noarch/`                       | 与架构无关的包。             |

7. 将 RPMs 复制到设备，并按照 [在设备上设置 robotics DNF 存储库](#set-up-the-robotics-dnf-repository-on-the-device) 和 [安装 robotics overlay 包](#install-the-robotics-overlay-packages) 中的步骤进行安装。