# 迁移到 Qualcomm Linux 1.4 或更高版本

考虑以下关键更新和改进，了解如何从 Qualcomm^®^ Linux^®^ 1.3 版本迁移到 Qualcomm Linux 1.4 或更高版本。

Qualcomm Linux 1.4 及更高版本具有 Yocto 5.0 的最新长期支持 (LTS) 版本，称为 Yocto `scarthgap`。通用缓存管理 (GBM) 内存管理器和 Weston 驱动程序现在是上游版本，取代了 1.3 及更早版本中使用的下游版本。

如果您是 Qualcomm Linux 的新用户且使用的是最新的 1.6 版本，则无需迁移您的软件。有关最新版本的新功能、增强特性和局限性的列表，请参阅 [Qualcomm Linux 1.6 Release Notes](https://docs.qualcomm.com/bundle/publicresource/topics/RNO-251013063244/)。

## Yocto 方面的变更

1.4 及更高版本中 Yocto 的变更如下：

- 将 Yocto 版本从 `kirkstone` (v4.0.22) 升级到 `scarthgap` (v5.0.11)。有关 `scarthgap` 的功能和增强特性，请参阅 [Release notes for 5.0 (scarthgap)](https://docs.yoctoproject.org/5.0.11/singleindex.html#release-notes-for-5-0-scarthgap)。
- 将 GNU 编译器集合 (GCC) 编译器升级到 v13.2。为避免兼容性问题，请使用最新的 Qualcomm Linux 版本重新编译任何预编译的应用程序。

## 内存管理器方面的变更

在 1.4 及更高版本中，用于内存管理的上游 [`libgbm` package](https://git.openembedded.org/openembedded-core/tree/meta/recipes-graphics/mesa?h=scarthgap&id=00a662c5e28235fb64348aab4ce9aeb5e7f95d06) 版本取代了下游版本。此变更会影响显示、图形、视频和摄像头模块中的内存格式和 GBM 功能。

有关上游 GBM 支持的格式列表，请参阅 [`mesa` repository](https://gitlab.freedesktop.org/mesa/mesa/-/blob/main/src/gbm/main/gbm.h)。

## 分区方面的变更

在 1.2 及更高版本中，Qualcomm Linux 使用 bootloader 规范 `uapi-group` UUID，而不是分区标签名称。这些 UUID 是固定的。要更改分区标签或 UUID，并避免不兼容问题，请联系 Qualcomm。如果您的设备是 1.2 或更早版本，并且分区定义是基于标签的，请在升级到更高版本之前切换到基于 UUID 的映射。

对于每个分区条目的 UUID，请参阅 [Qualcomm Linux 1.6 Release Notes](https://docs.qualcomm.com/bundle/publicresource/topics/RNO-251013063244/)。

在 1.6 版本中，基于 EMMC 存储的 QCS6490 和 QCS5430 产品的分区表发生了变化。如果您要从 1.5 版本升级设备软件，并且设备使用 EMMC 存储，则不支持通过空中下载 (OTA) 迁移到 1.6 版本。

## 实时子系统方面的变更

在 1.6 版本中，实时子系统 (RTSS) 模块已作为操作系统迁移到 FreeRTOS。它使用两个二进制文件作为固件，而不是单个二进制文件。二进制镜像 `sailhyp.elf` 和 `sailsw1.elf` 是专有的，并且是从 FreeRTOS 源代码编译而来的。

从 1.5 版本升级到 1.6 版本时，您必须重新刷写 1.6 版本的 RTSS 二进制文件，因为 1.5 版本中的 RTSS 固件与 1.6 版本中的应用处理器镜像不兼容。

## 显示方面的变更

在 1.4 及更高版本中，QCS6490 和 QCS5430 片上系统 (SoC) 平台的显示协议栈现已成为上游版本，因此无需使用专有的 Snapdragon^®^ 显示管理器 (SDM) 后端。IQ-8275 和 IQ-9075 SoC 平台已使用上游显示协议栈。

由于此次迁移，某些依赖于 SDM 组件的功能默认情况下不可用。如果您需要这些功能，可以将显示协议栈切换到下游实现。

要在 1.4 及更高版本中启用这些功能，请使用下表中的信息：

| 功能 | 在 1.4 及更高版本中启用 |
| --- | --- |
| 嵌入式 DisplayPort (eDP) 支持 | 按照 [Qualcomm Linux Display Guide - Addendum](https://docs.qualcomm.com/bundle/resource/topics/80-70022-18A/configure.html#enable-display-downstream-drivers) 中所述启用下游路径。 |
| 基于 DisplayPort (DP) 的 Type-C | 按照 [Qualcomm Linux Display Guide - Addendum](https://docs.qualcomm.com/bundle/resource/topics/80-70022-18A/configure.html#enable-display-downstream-drivers) 中所述启用下游路径。 |
| 预编译 modetest 二进制文件 | 在 `libdrm_2.4.120.bb` 文件中，启用 `install-test-programs` 选项。有关更多信息，请参阅 [Qualcomm Linux 显示指南](https://docs.qualcomm.com/bundle/publicresource/topics/80-70022-18/samples.html#run-drm-mode-test)。 |

## 摄像头方面的变更

在 1.4 及更高版本中，缓存管理工具使用上游 GBM 组件，而不再使用下游组件。因此，需要更改 Qualcomm Intelligent Multimedia (IM) 命令来调用摄像头缓存管理。

raw 缓存的默认格式现为 `memory:GBM`。请勿在 `gst` 命令中指定内存格式。

**Pipeline 示例**

- 1.3 版本的 pipeline 如下：

gst-launch-1.0 qtiqmmfsrc name=camsrc video_0::type=preview ! video/x-raw\(memory:GBM\),format=NV12,width=1920,height=1080,framerate=30/1,compression=ubwc ! waylandsink fullscreen=true async=true sync=false
        Copy to clipboard
- 1.4 及更高版本的 pipeline 如下：

gst-launch-1.0 -e qtiqmmfsrc name=camsrc video_1::type=preview ! video/x-raw,format=NV12,width=1920,height=1080,framerate=30/1,interlace-mode=progressive,colorimetry=bt601 ! waylandsink fullscreen=true sync=false
        Copy to clipboard

有关插件变更的更多信息，请参阅 [Qualcomm IM SDK 的变更](https://docs.qualcomm.com/doc/80-70022-150Y/topic/introduction.html#qim-sdk)。

## 视频方面的变更

为了管理用于视频编码或解码的缓存，1.4 及更高版本支持直接内存访问 (DMA) Export 模式 (4)、DMA Import 模式 (5) 以及内存映射 (MMAP) 模式 (2)。请根据您的具体用例选择合适的模式。

**示例**

在对摄像头进行编码时，就会生成 DMA 缓存。在本用例中，请执行以下操作：

> 
> 
> - 将编码器输入设置为 DMA Import 模式 (5)。此模式可确保直接使用摄像头缓存文件描述符 (FD)，无需在视频驱动程序端分配新的缓存并复制内容。
> - 将编码器输出设置为 DMA Import 模式 (5)。此模式可确保由视频驱动程序分配输出缓存。

此示例的视频 pipeline 如下：

gst-launch-1.0 -ev qtiqmmfsrc ! video/x-raw,format=NV12,width=1920,height=1080,framerate=30/1 ! v4l2h264enc output-io-mode=5 capture-io-mode=4 ! h264parse ! mp4mux ! filesink location=/opt/cam_enc.mp4
    Copy to clipboard

在此 pipeline 中，`output-io-mode` 为 DMA Import 模式 (5)，表示编码器的输入，`capture-io-mode` 为 DMA Export 模式 (4)，表示编码器的输出。

## 音频方面的变更

在 1.5 及更高版本中，Qualcomm Linux 的音频协议栈已从 PulseAudio 迁移到 PipeWire 框架。本机音频验证命令现在使用 PipeWire 来代替 PulseAudio。关于更多详细信息，请参阅 [Qualcomm Linux 音频指南](https://docs.qualcomm.com/bundle/publicresource/topics/80-70022-16/audio.html)。

使用 Qualcomm IM 音频插件创建的应用程序已经与 PipeWire 兼容。这些应用程序无需进行任何更改。

## Qualcomm IM SDK 的变更

请考虑 Qualcomm IM SDK 各个版本中的以下变更。

### 1.6 及更高版本的变更

在 1.6 版本中，一个新的统一插件执行 Qualcomm IM SDK 后处理操作并促进自定义 AI 模型的集成。

下表列出了用于机器学习 (ML) 的 Qualcomm IM SDK 插件，重点介绍了它们的功能以及 1.6 及更早版本中提供的支持。

**表：1.6 及更早版本中用于机器学习 (ML) 的 Qualcomm IM SDK 插件**

| 插件 | 功能 | 1.5 及更早版本 | 1.6 |
| --- | --- | --- | --- |
| `qtimlvconverter` | 将传入视频缓存中的数据转换为神经网络张量，同时执行所需的格式转换和大小调整。 | 支持 | 支持 |
| `qtimlvclassification` | 对分类用例的输出张量进行后处理。 | 支持 | 支持但将被弃用 |
| `qtimlvdetection` | 对检测用例的输出张量进行后处理。 | 支持 | 支持但将被弃用 |
| `qtimlvsegmentation` | 对像素类用例的输出张量进行后处理，如图像分割和深度图处理。 | 支持 | 支持但将被弃用 |
| `qtimlvpose` | 对姿势估计用例的输出张量进行后处理。 | 支持 | 支持但将被弃用 |
| `qtimlvsuperresolution` | 对视频超分辨率用例的输出张量进行后处理。 | 支持 | 支持但将被弃用 |
| `qtimlpostprocess` | 提供用于后处理推理插件张量输出的库接口。可自定义。 | 不可用 | 支持 |

#### qtimlpostprocess 插件

1.6 版本引入了 `qtimlpostprocess`，这是一个后处理插件，可缩短处理时间，并促进自定义 AI 模型在 Qualcomm IM SDK pipeline 中的集成。该插件提供了一个用于后处理张量输出的库接口。您可以对其进行自定义以满足您的特定模型要求。

`qtimlpostprocess` 插件在 Qualcomm IM SDK pipeline 中实现了以下更改：

- 取代了 Qualcomm IM SDK pipeline 中用于后处理的早期插件。
- 直接从模型获取 `constants`，无需在命令行配置中指定。
- 与升级后的后处理工作流保持一致，现已标准化为使用 JSON 格式的标签文件。

有关 `qtimlpostprocess` 插件的更多信息以及添加自定义 AI 模型进行后处理，请参阅 [AI 开发者工作流](https://docs.qualcomm.com/bundle/publicresource/topics/80-70022-15B/add-postprocessing-support-custom-model.html)。

**使用 LiteRT 模型进行图像分类的 pipeline 示例**

- 1.5 及更早版本的 pipeline 如下：

gst-launch-1.0 -e --gst-debug=2 \
        filesrc location=/etc/media/video.mp4 ! qtdemux ! queue ! h264parse ! v4l2h264dec capture-io-mode=4 output-io-mode=4 ! video/x-raw,format=NV12 ! queue ! tee name=split \
        split. ! queue ! qtivcomposer name=mixer sink_1::position="<30, 30>" sink_1::dimensions="<640, 360>" ! queue ! waylandsink sync=true fullscreen=true \
        split. ! queue ! qtimlvconverter ! queue ! qtimltflite delegate=external external-delegate-path=libQnnTFLiteDelegate.so \
        external-delegate-options="QNNExternalDelegate,backend_type=htp;" model=/etc/models/resnet101_quantized.tflite ! queue ! \
        qtimlvclassification threshold=51.0 results=5 module=mobilenet labels=/etc/labels/classification.labels \
        extra-operation=softmax constants="Resnet,q-offsets=<46.0>,q-scales=<0.2186901867389679 >;" ! video/x-raw,format=BGRA,width=640, height=360 ! queue ! mixer.
        Copy to clipboard
- 1.6 版本的 pipeline 如下：

gst-launch-1.0 -e --gst-debug=2 \
        filesrc location=/etc/media/video.mp4 ! qtdemux ! queue ! h264parse ! v4l2h264dec capture-io-mode=4 output-io-mode=4 ! video/x-raw,format=NV12 ! queue ! tee name=split \
        split. ! queue ! qtivcomposer name=mixer sink_1::position="<30, 30>" sink_1::dimensions="<640, 360>" ! queue ! waylandsink sync=true fullscreen=true \
        split. ! queue ! qtimlvconverter ! queue ! qtimltflite delegate=external external-delegate-path=libQnnTFLiteDelegate.so \
        external-delegate-options="QNNExternalDelegate,backend_type=htp;" model=/etc/models/resnet101_quantized.tflite ! queue ! \
        qtimlpostprocess settings="{\"confidence\": 51.0}" results=5 module=mobilenet-softmax labels=/etc/labels/classification.json ! \
        video/x-raw,format=BGRA,width=640, height=360 ! queue ! mixer.
        Copy to clipboard

### 1.4 及更高版本的变更

在 1.4 及更高版本的 Qualcomm IM SDK 中，由于内存管理器组件向上游迁移，`waylandsink`、`qtiqmmfsrc`、`v4l2h264dec` 和 `v4l2h264enc` 插件的行为发生了变化。更多详细信息，请参见 [内存管理器方面的变更](https://docs.qualcomm.com/doc/80-70022-150Y/topic/introduction.html#memory-manager)。

为体现 1.4 及更高版本中 Qualcomm IM SDK 插件的变化并与上游 GBM 保持一致，请按以下方式更新示例应用程序。

#### waylandsink 插件

早期版本的 Qualcomm IM SDK 使用的是 `waylandsink` 插件的下游版本，该版本会将 `x,y,width,height` 坐标作为额外参数包含在内。在后续版本中，由于切换到了上游 `waylandsink` 插件，此功能不再可用。而是使用 `qtivcomposer` 插件来实现该功能。

插件的变更以及您必须采取的相应操作如下：

| 变更 | 变更 | 操作 |
| --- | --- | --- |
| 1.3 | 1.4 及更高版本 | 操作 |
| 包含 `x,y,width,height` 坐标。 | 通过 `qtivcomposer` 插件提供功能。 | 使用 `qtivcomposer` 插件进行合成。 |
|  |  |  |

**Pipeline 示例**

- 1.3 版本的 pipeline 如下：

gst-launch-1.0 -e qtivcomposer name=mixer sink_0::position="<0, 0>" sink_0::dimensions="<1280, 720>" sink_1::position="<590, 310>" sink_1::dimensions="<640, 360>" mixer. ! queue ! waylandsink enable-last-sample=false sync=true fullscreen=true filesrc location=/opt/mux1.mp4 ! qtdemux ! queue ! h264parse ! v4l2h264dec capture-io-mode=5 output-io-mode=5 ! mixer. filesrc location=/opt/mux1.mp4 ! qtdemux ! queue ! h264parse ! v4l2h264dec capture-io-mode=5 output-io-mode=5 ! mixer.
        Copy to clipboard
- 1.4 及更高版本的 pipeline 如下：

gst-launch-1.0 -e qtivcomposer name=mixer sink_0::position="<0, 0>" sink_0::dimensions="<1280, 720>" sink_1::position="<590, 310>" sink_1::dimensions="<640, 360>" mixer. ! queue ! waylandsink fullscreen=true filesrc location=/opt/mux1.mp4 ! qtdemux ! queue ! h264parse ! v4l2h264dec capture-io-mode=4 output-io-mode=4 ! video/x-raw, format=NV12 ! mixer. filesrc location=/opt/mux1.mp4 ! qtdemux ! queue ! h264parse ! v4l2h264dec capture-io-mode=4 output-io-mode=4 ! video/x-raw, format=NV12 ! mixer.
        Copy to clipboard

#### qtiqmmfsrc 插件

从 1.4 及更高版本开始，`qtiqmmfsrc` 插件不再支持通用带宽压缩 (UBWC) 的 NV12 格式的 compression 字段。而是使用专用于 UBWC 压缩的 NV12 图像的新格式。

插件的变更以及您必须采取的相应操作如下：

| 变更 | 变更 | 操作 |
| --- | --- | --- |
| 1.3 | 1.4 及更高版本 | 操作 |
| `format=NV12`<br><br><br>`compression=ubwc` | 新增 `format=NV12_Q08C` | <ul class="simple"><br><li><p>将格式从 <code class="docutils literal notranslate"><span class="pre">format=NV12</span></code> 更改为 <code class="docutils literal notranslate"><span class="pre">format=NV12_Q08C</span></code>。</p></li><br><li><p>移除 <code class="docutils literal notranslate"><span class="pre">compression=ubwc</span></code> 参数。</p></li><br></ul> |
|  |  |  |

**Pipeline 示例**

- 1.3 版本的 pipeline 如下：

gst-launch-1.0 qtiqmmfsrc name=camsrc video_0::type=preview ! video/x-raw\(memory:GBM\),format=NV12,width=1920,height=1080,framerate=30/1,compression=ubwc ! v4l2h264enc output-io-mode=5 capture-io-mode=5 ! h264parse ! filesink location=/opt/video.h264
        Copy to clipboard
- 1.4 及更高版本的 pipeline 如下：

gst-launch-1.0 -ev qtiqmmfsrc name=camsrc video_0::type=preview ! video/x-raw,format=NV12_Q08C,width=1920,height=1080,framerate=30/1 ! queue ! v4l2h264enc output-io-mode=5 capture-io-mode=4 ! h264parse ! filesink location=/opt/video.h264
        Copy to clipboard

#### v4l2h264enc 和 v4l2h264dec 插件

在早期版本中，GST 框架负责管理应用程序缓存。从 1.4 及更高版本开始，`v4l2` 驱动程序支持内部缓存管理。

要将此改进特性添加到驱动程序中，请执行以下操作：

- 对于使用摄像头源和 `v4l2h264enc` 插件的应用程序，请将 pipeline 配置 `output-io-mode=5`/`capture-io-mode=5` 更改为 `output-io-mode=5`/`capture-io-mode=4`。
- 对于使用文件源和 `v4l2h264dec` 插件的应用程序，请将 pipeline 配置 `output-io-mode=5`/`capture-io-mode=5` 更改为 `output-io-mode=4`/`capture-io-mode=4`。

插件的变更以及您必须采取的相应操作如下：

| 用例 | 变更 | 变更 | 操作 |
| --- | --- | --- | --- |
| 用例 | 1.3 | 1.4 及更高版本 | 操作 |
| 视频编码 | `format=NV12`<br><br><br>`compression=ubwc` | 新增 `format=NV12_Q08C` | <ul class="simple"><br><li><p>将格式从 <code class="docutils literal notranslate"><span class="pre">format=NV12</span></code> 更改为 <code class="docutils literal notranslate"><span class="pre">format=NV12_Q08C</span></code>。</p></li><br><li><p>移除 <code class="docutils literal notranslate"><span class="pre">compression=ubwc</span></code> 参数。</p></li><br></ul> |
| 视频编码 | `output-io-mode=5` 和 `capture-io-mode=5` | 更改为 `output-io-mode=5` 和 `capture-io-mode=4` | 将模式更改为 `output-io-mode=5` 和 `capture-io-mode=4`。 |
| 视频解码 | `output-io-mode=5` 和 `capture-io-mode=5` | <ul class="simple"><br><li><p>新增 caps 和 <code class="docutils literal notranslate"><span class="pre">format=NV12</span></code></p></li><br><li><p>更改为 <code class="docutils literal notranslate"><span class="pre">output-io-mode=4</span></code> 和 <code class="docutils literal notranslate"><span class="pre">capture-io-mode=4</span></code></p></li><br></ul> | <ul class="simple"><br><li><p>添加 <code class="docutils literal notranslate"><span class="pre">video/x-raw,format=NV12</span></code>。</p></li><br><li><p>将模式更改为 <code class="docutils literal notranslate"><span class="pre">output-io-mode=4</span></code> 和 <code class="docutils literal notranslate"><span class="pre">capture-io-mode=4</span></code>。</p></li><br></ul> |
|  |  |  |  |

**Pipeline 示例**

- 1.3 版本的视频解码器 pipeline 如下：

gst-launch-1.0 -e filesrc location=/opt/mux1.mp4 ! qtdemux ! queue ! h264parse ! v4l2h264dec capture-io-mode=5 output-io-mode=5 !  waylandsink fullscreen=true
        Copy to clipboard
- 1.4 及更高版本的视频解码器 pipeline 如下：

gst-launch-1.0 -e filesrc location=/opt/mux1.mp4 ! qtdemux ! queue ! h264parse ! v4l2h264dec capture-io-mode=4 output-io-mode=4 ! video/x-raw,format=NV12 ! waylandsink fullscreen=true
        Copy to clipboard
- 1.3 版本的视频编码器 pipeline 如下：

gst-launch-1.0 -e qtiqmmfsrc name=camsrc video_0::type=preview ! video/x-raw\(memory:GBM\),format=NV12,width=3840,height=2160,framerate=30/1,compression=ubwc,interlace-mode=progressive,colorimetry=bt601 ! queue ! v4l2h264enc capture-io-mode=5 output-io-mode=5 ! queue ! h264parse ! mp4mux ! queue ! filesink location="/opt/mux1.mp4"
        Copy to clipboard
- 1.4 及更高版本的视频编码器 pipeline 如下：

gst-launch-1.0 -e qtiqmmfsrc name=camsrc video_0::type=preview ! video/x-raw,format=NV12_Q08C,width=3840,height=2160,framerate=30/1,interlace-mode=progressive,colorimetry=bt601 ! queue ! v4l2h264enc capture-io-mode=4 output-io-mode=5 ! queue ! h264parse ! mp4mux ! queue ! filesink location="/opt/mux1.mp4"
        Copy to clipboard

## 后续步骤

- 要为 Qualcomm Linux 进行空中下载 (OTA) 更新，请参阅 [Qualcomm Linux Yocto 指南](https://docs.qualcomm.com/bundle/publicresource/topics/80-70022-27/update_fw_and_os_qualcomm_linux_using_capsule_and_ostree_mechanisms.html)。
- 要了解有关 Qualcomm Intelligent Multimedia (IM) SDK 的新功能、增强特性和局限性的更多信息，请参阅 [Qualcomm Intelligent Multimedia (IM) SDK Release Notes](https://docs.qualcomm.com/bundle/publicresource/topics/80-70022-52/qim-sdk-release-1-6.html)。
- 要了解有关最新发布版本的新功能、增强特性和局限性的更多信息，请参阅 [Qualcomm Linux 1.6 Release Notes](https://docs.qualcomm.com/bundle/publicresource/topics/RNO-251013063244/)。

Last Published: Nov 03, 2025

[Next Topic
参考资料](https://docs.qualcomm.com/bundle/publicresource/80-70022-150Y/topics/references.md)

Source: [https://docs.qualcomm.com/doc/80-70022-150Y/topic/introduction.html](https://docs.qualcomm.com/doc/80-70022-150Y/topic/introduction.html)