> ## Documentation Index
> Fetch the complete documentation index at: https://dragonwingdocs-staging.qualcomm.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 自定义语音唤醒引擎与并发 VA 的 ADSP 内存管理
> 当 Qualcomm SVA 与自定义语音激活引擎在同一 ADSP 镜像中运行时，配置并验证 ADSP island TCM 内存。
## 概述
本应用说明介绍了当 Qualcomm SVA（Sound Trigger Engine）与自定义语音激活或热词引擎集成在同一 ADSP 镜像中时，如何配置和验证 ADSP island TCM 内存。它涉及两种相关的故障模式：
* 创建 ADSP 镜像时出现构建时内存不足（OOM）故障。
* SVA 与自定义引擎同时处于活动状态时出现运行时 TCM 分配故障或 ADSP 崩溃（panic）。
相关建议侧重于 island 放置、共享池大小设置、配置审查和端到端验证。本说明中的示例大小特定于具体配置，不得视为通用默认值。
## 适用范围
本说明面向在所有基于 Qualcomm ADSP 的平台上集成、配置、构建和验证并发语音唤醒引擎的工程师。读者应熟悉 ADSP 镜像生成、island 内存放置、`pp_libs_cfg.json`、`cust_config.xml` 以及 ADSP 运行时日志分析。
## ADSP island TCM 内存架构
相关的 island TCM 被划分为两个逻辑池。两个池共用同一个固定的物理 island TCM 预算；因此，增大一个池就需要减小另一个池。
ADSP Island TCM 的层次结构：它分为 QURTOS\_VA\_ISLAND\_POOL 和 TCM\_PHYSPOOL，分别对应 SVA/Sound Trigger Engine 和自定义 VA 引擎，以支持并发语音引擎运行。
| 内存池 | 用途 | 示例大小 |
| - | - | - |
| `QURTOS_VA_ISLAND_POOL` | Sound Trigger Engine 使用的语音激活 island 堆。 | 512 KB (`0x80000`) |
| `TCM_PHYSPOOL` | 自定义热词 DSP 模块使用的紧耦合内存（TCM）池。 | 256 KB (`0x40000`) |
可用的 island TCM 总量由硬件和软件配置决定，是固定的。请综合评估池大小、模块放置和模型占用。
## 自定义 VA 集成期间的构建时 OOM
### 症状
添加自定义语音激活模块时，ADSP 镜像创建可能会失败，并出现类似以下的错误：
```text theme={null}
Exception: !!!OOM!!!, Unable to fit 0x34 in QURTOS_VA_ISLAND_POOL
```
在所记录的配置中，`QURTOS_VA_ISLAND_POOL` 中仅剩约 16 KB，而自定义引擎的小模型需要约 37,000 字节，大模型需要 46,080 字节。
### 根本原因
目标配置不需要的模块仍被放置在 island 内存中。它们预留的空间减少了自定义热词模块可用的余量。
### 解决方法
审查 `pp_libs_cfg.json`，并为未使用的模块设置 `island: False`。所记录的示例包括：
* `voice_wakeup_v2_module`，当该配置中未使用 Qualcomm 语音激活时。
* `stage1_pdk_module`，当目标配置不需要它时。
移除不必要的 island 放置后，所记录配置中的可用 VA island 空间从约 16 KB 增加到 28 KB。如果需要更多余量，请将其他未使用的模块移出 island 内存。
`pp_libs_cfg.json` 中的示例概念：
```json theme={null}
"": { "island": false }
```
不要仅仅为了遵循此示例而将模块移出 island 内存。请确认该模块未被使用，或者目标配置支持将其放置在非 island 内存中。
## 并发语音激活时的运行时故障
### 症状
先启用 SVA、随后启用自定义关键词引擎时，ADSP 可能会报告 TCM 分配故障，例如：
```text theme={null}
ADSP: posal_tcm_island_heap_mgr_malloc: failure occurred - no TCM memory of size 46095 bytes available
```
### 根本原因
所记录的配置使用 `TCM_PHYSPOOL = 0x40000`（256 KB）。在 SVA 已占用部分共享 island TCM 预算之后，这不足以满足自定义引擎约 46 KB 的运行时分配。该问题仅在并发使用场景中出现，因为合并后的峰值需求超出了可用分区。
### 池重新平衡示例
| 池 | 原始值 | 修复后的示例大小 | 变化 |
| - | - | - | - |
| `QURTOS_VA_ISLAND_POOL` | `0x80000` (512 KB) | `0x70000` (448 KB) | -64 KB |
| `TCM_PHYSPOOL` | `0x40000` (256 KB) | `0x50000` (320 KB) | +64 KB |
64 KB 的转移是针对所记录配置验证过的示例。如果平台、ADSP 镜像、SVA 配置、自定义引擎、模型或模块放置发生变化，请重新评估。
减小 `QURTOS_VA_ISLAND_POOL` 可以为 `TCM_PHYSPOOL` 提供更多内存，但会减少 SVA 和其他 VA island 使用者可用的内存。如果剩余的池不足，或者缺少大小合适的对齐空闲块，SVA 初始化、运行时分配、动态映射或并发语音运行可能会失败。
此更改特定于具体配置。在用于生产之前，请通过构建检查、池使用分析以及 SVA/自定义 VA 并发测试进行验证。
## 内存大小计算方法
在最终确定池大小之前，请执行以下步骤：
1. 测量每个语音唤醒引擎的 island 和 TCM 占用，包括自定义的小模型和大模型。
2. 确定最坏情况下的同时激活场景。
3. 计入固定的平台预留以及放置在 island 内存中的所有模块。
4. 分配 `QURTOS_VA_ISLAND_POOL` 和 `TCM_PHYSPOOL`，使合并后的峰值需求处于固定的物理 island TCM 预算之内。
5. 为分配器开销和配置增长保留实际可用的余量。
大小设置决策至少应涵盖仅 SVA、仅自定义引擎以及 SVA 加自定义引擎三种运行情况。
## 配置文件
| 文件 | 用途 |
| - | - |
| `pp_libs_cfg.json` | 控制 ADSP 模块的 island 放置。对于已确认在目标配置中未使用的模块，请使用 `island: False`。 |
| `cust_config.xml` | 包含客户特定的 ADSP 配置，视情况包括池设置或相关的平台定制。 |
验证池大小更改时，请记录所使用的确切分支、平台、配置修订版本和模型修订版本。
## 验证
| 步骤 | 验证操作 |
| - | - |
| 1 | 审核 `pp_libs_cfg.json`，找出目标配置未使用的模块。 |
| 2 | 确认每个所需模块的 island 放置，并且仅将已批准的未使用模块移出 island 内存。 |
| 3 | 测量每个语音唤醒引擎的小模型和大模型内存占用。 |
| 4 | 计算最坏情况并发场景下的峰值需求。 |
| 5 | 设置 `QURTOS_VA_ISLAND_POOL` 和 `TCM_PHYSPOOL` 的大小，以便在固定的 island TCM 预算内满足该需求。 |
| 6 | 构建 ADSP 镜像，并确认未出现 OOM 错误。 |
| 7 | 运行仅 SVA、仅自定义引擎以及 SVA 加自定义引擎并发测试。 |
| 8 | 使用支持的最大模型重复验证，并监控运行时日志中的 TCM 分配故障。 |
## 总结
| 问题 | 典型原因 | 建议操作 |
| - | - | - |
| `QURTOS_VA_ISLAND_POOL` 中的构建时 OOM | 未使用的模块占用 island 内存。 | 审核 `pp_libs_cfg.json`，并且仅为未使用且已批准的模块设置 `island: False`。 |
| 运行时 TCM 分配故障 | 并发运行期间，`TCM_PHYSPOOL` 对于自定义引擎而言过小。 | 根据测得的峰值需求重新平衡共享 island TCM 池。 |
| 更改后的配置回归 | 池或模块放置值被复制到不兼容的平台或版本。 | 针对目标平台、分支、镜像和模型修订版本重新验证。 |
请按照最坏情况下的并发语音唤醒工作负载设置共享 island TCM 分区的大小，移除不必要的 island 放置，并在生产部署之前完成构建和运行时验证。