自定义音频图

每个音频用例都是一个包含特定类型子图的图。每个子图包含一个或多个执行特定功能的功能性软件块(称为模块)。

在 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 source 节点: 无需接收数据通过输出端口向外推送数据基于时钟/驱动/捕获触发器运行通常与硬件或软件生成器绑定
Sink	消费传入数据并公开输入端口的节点。PipeWire sink 节点: 通过输入端口接收数据不生成自身的主要数据通常与硬件播放/输出交互控制缓冲和渲染

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

Resource_manager.xml — 设备到后端的映射以及策略制定属性
Card-defs.xml — 虚拟 PCM 和 compress 节点及其选项
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 平台)	`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 评估套件	`qcs8300-ridesx-snd-card`	`mixer_paths_qcs8300_ridesx.xml`	`resourcemanager_qcs8300_ridesx.xml`

Talos QCS615 配置文件

型号	声卡名称	mixer_paths.xml	ResourceManager.xml
Talos QCS615 评估套件	`qcs615-TALOS-EVK`	`mixer_paths_TALOS_EVK.xml`	`resourcemanager_TALOS_EVK.xml`

自定义 mixer paths XML 文件

混音器控制是从 ALSA 混音器公开给用户空间的控制变量。它允许用户空间访问 set 和 get 函数,并将参数传递给 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>

自定义 resource manager XML 文件

Resourcemanager.xml 文件包含所有可能的设备、用例和组合。它还包含其他配置、模块参数和全局参数。以下是 resource manager 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 文件	`build-qcom-wayland/workspace/sources/qcom-acdbdata/opensource/audioreachconf/ar-acdb/acdbdata`
ARGS	`build-qcom-wayland/workspace/sources/qcom-args/opensource/args`

音频图术语

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

图段

一个音频用例包含以下段。前端表示 stream 和 streamPP 子图,而后端表示每流每设备(PSPD)、devicePP 和 device 子图。图段

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

前端通过路由混音器控制连接到后端后,完整的 GKV 通过串联子图 GKV 以及使用混音器控制分配的 CKV 形成。打开前端 PCM 或 compress 设备时,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] 用于播放的示例音频图在此图中:

stream 子图包含写入共享内存端点、PCM 解码器和 PCM 转换器。客户端将 PCM 样本传递给写入共享内存端点。
如有必要,PCM 转换器会将 PCM 样本转换为流专用后处理模块支持的格式。
stream 子图的输出被送入 stream-device 子图,该子图包含媒体格式转换器(MFC)。MFC 将 stream 子图的 PCM 转换为 device 子图的 PCM 格式。
转换后,stream-device 子图的输出被送入 device PP 子图,以进行设备专用后处理。子图起始处放置了一个混音器,用于混合输入流。
devicePP 子图的输出随后被送入 device 子图,该子图包含诸如 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/compress 插件进行交互并启用音频用例。AGM 作为在用户空间运行的 PipeWire 服务的一部分运行。 AGM 为混音器插件以及 PCM/compress API 提供 API,用于设置音频用例。它维护多个 ALSA 客户端来设置用例。AGM 还管理前端到后端的连接。下图展示了 AGM 模块的高层视图。

高层 AGM 软件模块

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

对象	说明
Session	session 对象是一个音频播放或捕获会话。调用会话专用的混音器控制或 API 会创建会话。为 TinyALSA 插件提供用于配置流的 API,并管理图对象和设备对象的状态转换。
Graph	graph 对象是一个音频用例。与 GSL 交互,以打开、管理和关闭图。提供用于创建图的 API,管理图,并配置流和设备端点。
Device	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,用于设置和配置音频用例。
Modules	模块是 SPF 中的功能块。它在 LPAI 子系统中执行实时音频处理。
Containers	容器是一种框架实现,可在同一软件线程中一起运行一组数据处理模块。每个容器在自己的软件线程中运行。

后续步骤

高级音频功能 — 启用回声消除、噪声抑制和多设备播放
音频补充文档 — 使用 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

配置文件

自定义 mixer paths XML 文件

自定义 resource manager 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

​配置文件

​自定义 mixer paths XML 文件

​自定义 resource manager 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

配置文件

自定义 mixer paths XML 文件

自定义 resource manager XML 文件

自定义 usecasekvmanager XML 文件

同步和编译音频组件

同步 PipeWire

同步 PAL

同步 TinyALSA

音频模块源代码位置

音频图术语

图段

示例音频图

音频图管理器

AudioReach 图服务

音频校准数据库

AudioReach 引擎(ARE)

后续步骤