# 在 PAL 级别定制

## PulseAudio 音频管理器

PulseAudio 管理所有音频应用程序、本地和网络流、设备、过滤器以及音频输入和输出。

### PulseAudio PAL 插件

PulseAudio PAL 插件加载 PAL。它允许客户端配置音频设备并调用各种音频用例。

以下是 PulseAudio PAL 插件的组件：

| **Card** | 表示声卡，它是一组受支持的 profile、端口、接收端和发送端。<br><br><br>卡模块用途包括：<br><br><ul class="simple"><br><li><p>加载/卸载 PAL</p></li><br><li><p>创建/释放 PAL 支持的端口</p></li><br><li><p>创建/释放 PAL 卡</p></li><br><li><p>创建/释放接收端或发送端。<br>- 接收端是播放路径<br>- 发送端是采集路径</p></li><br></ul> |
| --- | --- |
| **Sink** | 配置音频播放路径。<br><br><br>接收端模块用途包括：<br><br><ul class="simple"><br><li><p>根据 module-pal-card 指定的配置打开/关闭播放会话</p></li><br><li><p>创建/释放为 PAL 播放会话写入数据的 Sink 线程</p></li><br><li><p>设置音量支持</p></li><br><li><p>获取延迟支持</p></li><br><li><p>路由支持</p></li><br></ul> |
| **Source** | 配置音频采集路径。<br><br><br><br>> <br>> <br>> 发送端模块用途包括：<br>> <br>> <ul class="simple"><br>> <li><p>根据 module-pal-card 指定的配置打开/关闭 PAL 录制会话</p></li><br>> <li><p>创建/释放 PA Source</p></li><br>> <li><p>创建用于从 PAL 记录会话读取数据的 Source 线程</p></li><br>> <li><p>路由支持</p></li><br>> </ul> |

## PAL API

PAL 提供更高级别的音频 API 来访问音频硬件和驱动程序。这使得音频功能包括：

- 以 PCM 和压缩格式进行音频播放和录制，支持各种这包括延迟和功率敏感用例。
- 音频格式的硬件加速编码/解码

客户端可使用各种 API 连接 PAL，以控制和配置会话及设备。PAL 执行以下操作：

- 配置混音器控件以搭建硬件编解码器设备和流配置
- 调用 TinyALSA API 打开/启动音频会话

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

- `Resource_manager.xml`– 设备到后端映射和策略制定属性
- `Card-defs.xml` – 虚拟 PCM 和压缩节点及其选项

PAL 负载构建器为用例图构建元数据负载。如需了解图表的更多信息，请参阅[定制音频图](https://docs.qualcomm.com/doc/80-70022-16SC/topic/agm.html#customize-audio-graph)。

PulseAudio 对不同的音频用例使用相同的 PAL API。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\_init

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

int32_t pal_init( )
    Copy to clipboard

**参数**

无

**返回值**

- 成功时为 0
- 失败时为错误代码

### pal\_deinit

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

void pal_deinit()
    Copy to clipboard

**参数**

无

**返回值**

无

### 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)
    Copy to clipboard

**参数**

| attributes | 从 pal\_stream\_open 获取的有效流属性 |
| --- | --- |
| no\_of\_devices | 首次启动流的音频设备数量。 |
| devices | pal\_devices 的数组。根据客户端在 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)
    Copy to clipboard

**参数**

| stream\_handle | 来自 pal\_stream\_open 的有效流句柄。 |
| --- | --- |

**返回值**

- 成功时为 0
- 失败时为错误代码

### pal\_stream\_read

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

ssize_t pal_stream_read(
         pal_stream_handle_t *stream_handle,
         struct pal_buffer *buf)
    Copy to clipboard

**参数**

| 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)
    Copy to clipboard

**参数**

| stream\_handle | 来自 pal\_stream\_open 的有效流句柄。 |
| --- | --- |
| buf | 指向具有音频样本和元数据的 pal\_buffer 的指针。 |

**返回值**

- 写入的字节数
- 失败时为错误代码

### pal\_stream\_stop

停止流。

int32_t pal_stream_stop(
         pal_stream_handle_t *stream_handle)
    Copy to clipboard

**参数**

| stream\_handle | 来自 pal\_stream\_open 的有效流句柄。 |
| --- | --- |

**返回值**

- 成功时为 0
- 失败时为错误代码

### pal\_stream\_close

关闭流。

int32_t pal_stream_close(
         pal_stream_handle_t *stream_handle)
    Copy to clipboard

**参数**

| stream\_handle | 来自 pal\_stream\_open 的有效流句柄。 |
| --- | --- |

**返回值**

- 成功时为 0
- 失败时为错误代码

## 配置文件

使用 `mixer_paths`、`resourcemanager` 和 `usecasekvmanager` XML 文件在 PAL 级别配置音频用例。

下表显示了不同硬件版本的配置文件：

QCS6490 配置文件

| 版本 | 声卡名称 | Conf 文件 | mixer\_paths.xml | ResourceManager.xml |
| --- | --- | --- | --- | --- |
| 核心套件 (Qualcomm RB3 Platform) | qcm6490-rb3-snd-card | qcm6490-rb3-snd-card.conf | mixer\_paths\_qcm6490\_rb3.xml | resourcemanager\_qcm6490\_rb3.xml |
| 机器视觉套件 | qcm6490-vision-snd-card | qcm6490-vision-snd-card.conf | mixer\_paths\_qcm6490\_vision.xml | resourcemanager\_qcm6490\_vision.xml |
| 视频协作套件 | qcm6490-vc-snd-card | qcm6490-vc-snd-card.conf | mixer\_paths\_qcm6490\_vc.xml | resourcemanager\_qcm6490\_vc.xml |

Qualcomm Dragonwing IQ-9075 配置文件

| 版本 | 声卡名称 | Conf 文件 | mixer\_paths.xml | ResourceManager.xml |
| --- | --- | --- | --- | --- |
| 核心套件 (RB8) | qcs9075-rb8-snd-card | qcs9075-rb8-snd-card.conf | mixer\_paths\_qcs9075\_rb8.xml | resourcemanager\_qcs9075\_rb8.xml |

Qualcomm Dragonwing IQ-8275 配置文件

| 版本 | 声卡名称 | Conf 文件 | mixer\_paths.xml | ResourceManager.xml |
| --- | --- | --- | --- | --- |
| Dragonwing IQ-8275 Beta 评估套件 | qcs8300-ridesx-snd-card | qcs8300-ridesx-snd-card.conf | mixer\_paths\_qcs8300\_ridesx.xml | resourcemanager\_qcs8300\_ridesx.xml |

### 定制混音器路径 XML 文件

混音器控件是从 ALSA 混音器公开到用户空间的控制变量。支持用户空间访问、设置和获取函数，以及将参数传递给 ALSA 混音器。

例如，以下是用于在 `mixer_path.xml` 文件中启用单目扬声器设备的条目。当播放触发且所选设备为扬声器时，以下混音器控件将在音频路由帮助程序类的帮助下运行。

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

平台使用 `mixer_paths_<sound-card-name>.xml` 文件作为混音器路径。此文件位于目标上的 `/etc/` 文件夹中。

### 定制资源管理器 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>
    Copy to clipboard

### 定制 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>
    Copy to clipboard

**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>
    Copy to clipboard

**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>
    Copy to clipboard

Last Published: Nov 04, 2025

[Previous Topic
定制音频用例](https://docs.qualcomm.com/bundle/publicresource/80-70022-16SC/topics/customize.md) [Next Topic
启用基于 TinyALSA 的应用程序](https://docs.qualcomm.com/bundle/publicresource/80-70022-16SC/topics/tinyalsa.md)