自定义音频图 - Qualcomm Dragonwing Documentation

每个音频用例都是一个具有特定类型子图的图。每个子图有一个或多个功能软件块（称为模块），用于执行特定功能。

在 PAL 级别自定义

平台抽象层 (PAL) 提供更高级别的音频特定 API 用于访问音频硬件和驱动。在 PAL 级别自定义可让您控制流行为、设备路由、缓冲区配置以及平台特定的音频设置。

PipeWire PAL 插件

PipeWire PAL 插件 (pw-pal-plugin) 将 PipeWire 流直接桥接到 PAL API。它作为 PipeWire 模块运行，并处理 PipeWire 和 AudioReach 硬件栈之间的所有音频路由。该插件执行以下操作：

打开和管理用于播放和捕获的 PAL 流
配置混音器控件以设置硬件编解码器设备和流配置
调用 PAL API 以打开和启动音频会话
在 PipeWire 缓冲区和 PAL DMA 缓冲区之间路由音频数据

以下是 PipeWire PAL 插件的组件：

源 (Source)	产生数据流（音频/视频帧）并暴露输出端口的节点。PipeWire 源节点：不需要接收数据通过输出端口推出数据基于时钟/驱动/捕获触发器运行通常与硬件或软件生成器绑定
接收端 (Sink)	消费传入数据并暴露输入端口的节点。PipeWire 接收端节点：通过输入端口接收数据不生成自身的主要数据通常与硬件播放/输出交互控制缓冲和渲染

PAL 资源管理器跟踪所有活动会话和设备以启用并发。它从以下平台 XML 文件解析并加载配置：

Resource_manager.xml — 设备到后端映射以及策略制定属性
Card-defs.xml — 虚拟 PCM 和压缩节点及其选项
mixer_paths.xml — 定义所有低级音频路由路径和控件，用于决定如何在设备上录制、处理和播放声音
plugin_manager.xml — 将音频流、会话和设备链接到其相应的插件库和运行时音频处理函数
usecaseKvManager.xml — 将音频流和设备映射到 DSP 处理图，决定芯片上如何在内部处理音频

在此处查找 PipeWire PAL 插件源代码：

build-qcom-wayland/workspace/sources/pipewire

在此处查找 PAL 源代码：

build-qcom-wayland/workspace/sources/qcom-pal/opensource/arpal-lx

以下文件列出了 PAL 模块公开的所有 API：

build-qcom-wayland/workspace/sources/qcom-pal/opensource/arpal-lx/inc/PalApi.h

PAL API

以下是常用的 PAL API。有关所有 API 的完整说明，请参阅 PalApi.h。

pal_init

初始化 PAL，解析相关配置文件，并将其存储在本地结构中以供使用。

int32_t pal_init()

参数无 返回值

成功时返回 0
失败时返回错误代码

pal_deinit

反初始化 PAL 并释放初始化期间分配的资源。

void pal_deinit()

参数无 返回值 无

pal_stream_open

以指定配置（例如源/接收端设备和媒体配置）打开流。成功后返回流句柄。

int32_t pal_stream_open(
    struct pal_stream_attributes *attributes,
    uint32_t no_of_devices,
    struct pal_device *devices,
    uint32_t no_of_modifiers,
    struct modifier_kv *modifiers,
    pal_stream_callback cb,
    uint64_t cookie,
    pal_stream_handle_t **stream_handle)

参数

参数	描述
attributes	指向指定流类型、方向和媒体配置的 `pal_stream_attributes` 结构的指针。
no_of_devices	首先启动流的音频设备数量。
devices	`pal_device` 数组。数组的大小基于 `no_of_devices` 中指定的设备数量。
no_of_modifiers	修饰符的数量。
modifiers	修饰符数组。修饰符添加更多键值对。
cb	与流关联的回调函数。此回调函数会通知任何事件。
cookie	与流关联的客户端数据。回调函数返回此 cookie。
stream_handle	如果操作成功，则用有效的流句柄进行更新。

返回值

成功时返回 0
失败时返回错误代码

pal_stream_start

启动流。

int32_t pal_stream_start(
    pal_stream_handle_t *stream_handle)

参数

参数	描述
stream_handle	来自 `pal_stream_open` 的有效流句柄。

返回值

成功时返回 0
失败时返回错误代码

pal_stream_read

读取从音频源设备捕获的音频缓冲区。

ssize_t pal_stream_read(
    pal_stream_handle_t *stream_handle,
    struct pal_buffer *buf)

参数

参数	描述
stream_handle	来自 `pal_stream_open` 的有效流句柄。
buf	指向 `pal_buffer` 的指针，该缓冲区包含音频样本和元数据。

返回值

成功时返回读取的字节数
失败时返回错误代码

pal_stream_write

写入音频缓冲区以通过接收端设备渲染流。

ssize_t pal_stream_write(
    pal_stream_handle_t *stream_handle,
    struct pal_buffer *buf)

参数

参数	描述
stream_handle	来自 `pal_stream_open` 的有效流句柄。
buf	指向 `pal_buffer` 的指针，该缓冲区包含音频样本和元数据。

返回值

成功时返回写入的字节数
失败时返回错误代码

pal_stream_stop

停止流。

int32_t pal_stream_stop(
    pal_stream_handle_t *stream_handle)

参数

参数	描述
stream_handle	来自 `pal_stream_open` 的有效流句柄。

返回值

成功时返回 0
失败时返回错误代码

pal_stream_close

关闭流。

int32_t pal_stream_close(
    pal_stream_handle_t *stream_handle)

参数

参数	描述
stream_handle	来自 `pal_stream_open` 的有效流句柄。

返回值

成功时返回 0
失败时返回错误代码

配置文件

通过使用 mixer_paths、resourcemanager 和 usecasekvmanager XML 文件，在 PAL 级别配置音频用例。下表显示了每个支持平台的配置文件： QCS6490 配置文件

变体	声卡名称	mixer_paths.xml	ResourceManager.xml
Core Kit (Qualcomm RB3 Platform)	`qcm6490-rb3-snd-card`	`mixer_paths_qcm6490_rb3.xml`	`resourcemanager_qcm6490_rb3.xml`
Vision Kit	`qcm6490-vision-snd-card`	`mixer_paths_qcm6490_vision.xml`	`resourcemanager_qcm6490_vision.xml`
Video Collab Kit	`qcm6490-vc-snd-card`	`mixer_paths_qcm6490_vc.xml`	`resourcemanager_qcm6490_vc.xml`

Qualcomm Dragonwing IQ-9075 配置文件

变体	声卡名称	mixer_paths.xml	ResourceManager.xml
Core Kit (RB8)	`qcs9075-rb8-snd-card`	`mixer_paths_qcs9075_rb8.xml`	`resourcemanager_qcs9075_rb8.xml`

Qualcomm Dragonwing IQ-8275 配置文件

变体	声卡名称	mixer_paths.xml	ResourceManager.xml
Dragonwing IQ-8275 Beta Evaluation Kit	`qcs8300-ridesx-snd-card`	`mixer_paths_qcs8300_ridesx.xml`	`resourcemanager_qcs8300_ridesx.xml`

Talos QCS615 配置文件

变体	声卡名称	mixer_paths.xml	ResourceManager.xml
Talos QCS615 Evaluation Kit	`qcs615-TALOS-EVK`	`mixer_paths_TALOS_EVK.xml`	`resourcemanager_TALOS_EVK.xml`

自定义混音器路径 XML 文件

混音器控件是从 ALSA 混音器暴露给用户空间的控件变量。它允许用户空间访问设置和获取函数并向 ALSA 混音器传递参数。平台使用 mixer_paths_<sound-card-name>.xml 文件作为混音器路径。此文件位于目标上的 /etc/ 文件夹中。以下是在 mixer_paths.xml 文件中启用单声道扬声器设备的示例条目。当触发播放且所选设备为扬声器时，在音频路由辅助类的帮助下运行以下混音器控件：

<path name="speaker">
    <!--Mixer controls related to speaker need to be defined here-->
</path>

自定义资源管理器 XML 文件

Resourcemanager.xml 文件包括所有可能的设备、用例和组合。它还包括其他配置、模块参数和全局参数。以下是资源管理器 XML 文件中的示例扬声器设备条目。它包含扬声器设备的所有配置，例如后端名称、通道、采样率和位宽：

<out-device>
    <id>PAL_DEVICE_OUT_SPEAKER</id>
    <back_end_name>CODEC_DMA-LPAIF_WSA-RX-0</back_end_name>
    <max_channels>2</max_channels>
    <channels>2</channels>
    <samplerate>48000</samplerate>
    <bit_width>16</bit_width>
    <snd_device_name>speaker</snd_device_name>
</out-device>

自定义 usecasekvmanager XML 文件

Usecasekvmanager.xml 文件包含每个用例的 GKV 详情。PAL 使用此 XML 文件获取每个用例的 KV 配置，然后使用该配置从 acdb 文件中获取图信息。此文件位于设备上的 /etc 文件夹中。以下是一个流和设备图关键向量配置的示例： Stream KV

<stream type="PAL_STREAM_LOW_LATENCY">
    <keys_and_values Direction="RX" Instance="1">
        <!-- STREAMRX - PCM_LL_PLAYBACK -->
        <graph_kv key="0xA1000000" value="0xA100000E"/>
        <!-- INSTANCE - INSTANCE_1 -->
        <graph_kv key="0xAB000000" value="0x1"/>
    </keys_and_values>

Device KV

<!-- Speaker Device -->
<device id="PAL_DEVICE_OUT_SPEAKER">
    <keys_and_values>
        <!-- DEVICERX - SPEAKER -->
        <graph_kv key="0xA2000000" value="0xA2000001"/>
    </keys_and_values>
</device>

DevicePP KV

<!-- OUT Speaker DevicePPs -->
<devicepp id="PAL_DEVICE_OUT_SPEAKER">
    <keys_and_values StreamType="PAL_STREAM_COMPRESSED,PAL_STREAM_LOW_LATENCY">
        <!-- DEVICERX - SPEAKER -->
        <graph_kv key="0xA2000000" value="0xA2000001"/>
        <!-- DEVICEPP_RX - DEVICEPP_RX_AUDIO_MBDRC -->
        <graph_kv key="0xAC000000" value="0xAC000002"/>
    </keys_and_values>
</devicepp>

同步和编译音频组件

音频软件使用位于 Linux 启用的音频软件目录中的用户空间和内核空间模块。音频用户空间和内核模块源代码树提取到以下路径：

<workspace>/build-qcom-wayland/workspace/sources

使用 devtool Linux 实用程序获取、提取和构建音频模块源代码。

转到工作区 (<workspace>/build-qcom-wayland$) 以使用 devtool 访问源代码树。

同步 PipeWire

提取源代码树：

devtool modify pipewire

PipeWire 源代码树提取到：

build-qcom-wayland/workspace/sources/pipewire

构建源代码树：
devtool build pipewire

同步 PAL

提取源代码树：

devtool modify qcom-pal

PAL 源代码树提取到：

build-qcom-wayland/workspace/sources/qcom-pal/opensource/arpal-lx

构建源代码树：
devtool build qcom-pal

同步 TinyALSA

提取源代码树：

devtool modify tinyalsa

TinyALSA 源代码树提取到：

build-qcom-wayland/workspace/sources/tinyalsa

构建源代码树：
devtool build tinyalsa

音频模块源代码位置

如果您对随 Qualcomm Linux 附带的专有软件具有完全访问权限，请在以下位置查看音频模块源代码：

模块	源代码路径
PipeWire	`build-qcom-wayland/workspace/sources/pipewire`
PAL	`build-qcom-wayland/workspace/sources/qcom-pal/opensource/arpal-lx`
TinyALSA	`build-qcom-wayland/workspace/sources/tinyalsa`
TinyCompress	`build-qcom-wayland/workspace/sources/tinycompress`
ACDB files	`build-qcom-wayland/workspace/sources/qcom-acdbdata/opensource/audioreachconf/ar-acdb/acdbdata`
ARGS	`build-qcom-wayland/workspace/sources/qcom-args/opensource/args`

音频图术语

用例	从源端点到接收端端点的模块图，满足产品定义的用例。
图	一组连接在一起的一个或多个子图的逻辑解释，用于创建特定用例。
子图	一组模块的逻辑抽象，这些模块被连接并作为单个实体进行操纵。
容器	允许系统设计人员在单个软件线程中一起分组和运行音频处理模块的对象。
模块	信号处理框架中最小的独立处理单元。
键值 (KV) 对	键向量中的单个键及其关联的值。例如，键可以是声音设备，值可以是耳机、扬声器或其他声音设备。
键向量	通过一组 KV 对唯一标识图或子图。
图键向量 (GKV)	GKV 是一个唯一标识符，用于获取由 KV 对表示的图。在从 QACT UI 画布创建子图时，图或系统设计人员会关联一组唯一的 <键> 和 <值>。
校准键向量 (CKV)	CKV 是一个唯一标识符，用于获取由 KV 对表示的校准数据。在存储校准数据时，图或系统设计人员会关联一组唯一的 <键> 和 <值>。
标签和标签键向量 (TKV)	标签是一个标识符，用于为一个或多个模块设置运行时参数。它允许在运行时更新图中的模块配置（例如启用/禁用回声消除或均衡等功能）。

图段

音频用例具有以下段。前端表示 stream 和 streamPP 子图，而后端表示每流每设备 (PSPD)、devicePP 和 device 子图。图段

Stream	提供数据写/读接口，并对压缩数据进行解码和编码。
StreamPP	具有基于流的处理模块（例如均衡器）。
PSPD	具有将流媒体格式转换为设备媒体格式的模块。
DevicePP	具有用于声音设备调优的处理模块。
Device	硬件端点，例如 CodecDMA (SoundWire)、I2S 或 TDM 端口。

一旦前端使用路由混音器控件连接到后端，完整的 GKV 将通过连接子图 GKV 以及使用混音器控件分配的 CKV 而形成。打开前端 PCM 或压缩设备后，AGM 将使用连接的 GKV 和 CKV 调用 GSL API 以在 SPF 中设置图并应用校准。同时，AGM 打开与连接的后端对应的内核 PCM 设备以开始音频外设设置。

示例音频图

下图显示了播放场景的示例音频图。

播放的示例音频图

CONT#1PCM ConverterPCM DecoderWrite SHMEM EPCONT#6Media Format ConverterCONT#2SplitterPP2PP1CONT#8HW EPCONT#7PP6PP5MixerClient PCM DataSGKV: [StreamRx: PCM Low Latency PlaybackInstance: instance 1]SGKV: [StreamRx: PCM Low Latency Playback Device: SpeakerInstance: instance 1]SGKV: [DeviceRx:SpeakerDevicePP rx: Speaker PP]SGKV: [DeviceRx:Speaker] 播放的示例音频图在此图中：

流子图具有写共享内存端点、PCM 解码器和 PCM 转换器。客户端将 PCM 样本传递到写共享内存端点。
如有必要，PCM 转换器将 PCM 样本转换为流特定后处理模块支持的格式。
流子图的输出被馈入流-设备子图，该子图具有媒体格式转换器 (MFC)。MFC 将流子图 PCM 转换为设备子图 PCM 格式。
转换后，流-设备子图的输出被馈入设备 PP 子图以进行设备特定的后处理。子图开头放置了一个混音器以混合输入流。
devicePP 子图的输出随后被馈入设备子图，该子图具有硬件端点模块（如 I2S 驱动）。

以下是此示例图的 GKV：

GKV1: <StreamRX1 KVs, StreamRX2 PP KVs, StreamRX1DeviceRX KVs, DeviceRX PP KVs, DeviceRX KVs>

GKV2: <StreamRX2 KVs, StreamRX2 PP KVs, StreamRX2DeviceRX KVs, DeviceRX PP KVs, DeviceRX KVs>

音频图管理器

音频图管理器 (AGM) 提供接口以允许基于 TinyALSA 的混音器控件以及 PCM/压缩插件进行交互并启用音频用例。AGM 作为在用户空间中运行的 PipeWire 服务的一部分运行。 AGM 为混音器插件和 PCM/压缩 API 提供 API 以设置音频用例。它维护许多 ALSA 客户端以设置用例。AGM 还管理前端到后端的连接。下图从高层次显示了 AGM 块。

高层次 AGM 软件块

Kernel spaceUserspaceAGM serviceAGM APIPALSession objectsGSLALSA devicesGraph objectsDevice objects 高层次 AGM 软件块 AGM 对象

对象	描述
Session	会话对象是音频播放或捕获会话。调用会话特定的混音器控件或 API 会创建会话。为 TinyALSA 插件提供配置流的 API，并管理图和设备对象的状态转换。
Graph	图对象是一个音频用例。与 GSL 交互以打开、管理和关闭图。为图创建提供 API，管理图，并配置流和设备端点。
Device	设备对象是来自 ALSA 声卡的 ALSA 设备。枚举可用的音频接口，并为转换设备状态提供设备 API。

AudioReach 图服务

AudioReach™ 信号处理框架图服务 (ARGS) 由图服务层 (GSL)、通用数据包路由器 (GPR) 和 acdb 管理层 (AML) 组成。它处理图的初始化和创建，以及为向 SPF 发送一系列命令而创建数据包。 ARGS 组件

组件	描述
GSL	图服务层 (GSL) 是 SPF 的软件驱动，用于管理图、子图、缓冲区和配置。使用图键向量 (GKV) 加载和初始化图。处理数据命令和 SPF 模块校准。
GPR	通用数据包路由器 (GPR) 在 SPF 和图服务库之间路由音频消息包。处理构建音频图和处理音频的命令。
AML	acdb 管理层 (AML) 提供 get/set API 以获取和调整 acdb 文件中的数据。提供数据抽象和组织，说明音频驱动及其组件如何使用校准数据。

音频校准数据库

acdb 是应用处理器上的一个静态数据库。它包含 LPAI 的所有调优/校准参数。*.acdb 文件格式为不同的音频模块组织不同用例的校准数据。使用 QACT（PC 工具）编辑此文件格式，并将其放置到设备文件系统的 /etc/acdbdata/ 文件夹中。在用例初始化或设备切换期间，AML 使用指定的 GKV 查询 acdb 数据库，并将设备校准数据推送到 SPF。

AudioReach 引擎 (ARE)

AudioReach 引擎 (ARE) 运行在 LPAI 子系统中，执行音频数据处理。下图给出了 SPF 中使用的功能块的高层次概述。

高层次 SPF 软件块

Processing Domain BProcessing Domain ASignal Processing Framework (SPF)Generic Packet Router (GPR)Audio Processing Manager (APM)OffloadSpecializedGenericContainerM1M2M3AMDPRMIRMModule-2Module-3…ApplicationPlatform and OS abstraction layerBoard Support Package(timer, memory manager, power manager, debug, etc.)Hardware driversReal-Time Operating System (RTOS)CAPIModule-1CAPICAPI 高层次 SPF 软件块 SPF 组件

组件	描述
APM	音频处理管理器 (APM) 在 SPF 中设置和管理用例图。它为图管理库和 APM 客户端提供标准 API 以设置和配置音频用例。
模块	模块是 SPF 中的功能块。它在 LPAI 子系统中执行实时音频处理。
容器	容器是一个框架实现，用于在同一个软件线程中一起运行一组数据处理模块。每个容器都运行在自己的软件线程中。

后续步骤

高级音频功能 — 启用回声消除、噪声抑制和多设备播放
Audio Addendum — 使用 QACT 和 QXDM 进行校准和诊断
故障排除音频 — 捕获并分析音频日志以解决问题

​在 PAL 级别自定义

​PipeWire PAL 插件

​PAL API

​pal_init

​pal_deinit

​pal_stream_open

​pal_stream_start

​pal_stream_read

​pal_stream_write

​pal_stream_stop

​pal_stream_close

​配置文件

​自定义混音器路径 XML 文件

​自定义资源管理器 XML 文件

​自定义 usecasekvmanager XML 文件

​同步和编译音频组件

​同步 PipeWire

​同步 PAL

​同步 TinyALSA

​音频模块源代码位置

​音频图术语

​图段

​示例音频图

​音频图管理器

​AudioReach 图服务

​音频校准数据库

​AudioReach 引擎 (ARE)

​后续步骤

在 PAL 级别自定义

PipeWire PAL 插件

PAL API

pal_init

pal_deinit

pal_stream_open

pal_stream_start

pal_stream_read

pal_stream_write

pal_stream_stop

pal_stream_close

配置文件

自定义混音器路径 XML 文件

自定义资源管理器 XML 文件

自定义 usecasekvmanager XML 文件

同步和编译音频组件

同步 PipeWire

同步 PAL

同步 TinyALSA

音频模块源代码位置

音频图术语

图段

示例音频图

音频图管理器

AudioReach 图服务

音频校准数据库

AudioReach 引擎 (ARE)

后续步骤