音频驱动调试指南

本文档提供 HiDiTing V100 音频驱动的最小化定位方法。通过运行 sample_ai_ao 建立稳定的数据流，再使用 sample_proc 读取模块状态、使用 sample_dump 导出 PCM，可把问题定位到输入、算法、编解码、输出或板级硬件。

音频驱动调试背景知识

调试目的

本文适用于无声、录音异常、杂音、回声、算法前后数据不一致等问题。它不是音效参数手册：调参前应先确认数据流和模块状态正确。音频业务实现请参阅音频驱动开发指南。

调试数据流与操作流程

SDK 已将调试入口注册到 src/application/audio/sample_audio.c：sample_proc 用于读取 AI、SEA、AENC、ADEC、AO、AB、SYS、SYNC、ADP（以及启用 HAID 时的 HAID）状态；sample_dump 用于从指定模块句柄抓取 PCM 或处理数据。AT 音频命令在 src/middleware/utils/at/at_audio_cmd/at/at_audio.c 中按空格拆分参数并转交给场景函数。

图 1 音频调试命令与数据流关系

该图描述完整业务链路及调试命令的作用范围：sample_ai_ao 或业务场景建立 AI → SEA/AENC → ADP → AO 的数据流；sample_proc 读取各节点状态，sample_dump 则从 AI 或 SEA 的指定句柄导出数据。图中的 SEA、AENC、ADP、AO 都是可选或后续节点，不能把它理解为单纯的麦克风输入测试链路。

图 2 AI 输入采集与编码调测链路

该图仅用于 AI 输入采集与 AENC 编码调测：将 Input_Sin 声源放在麦克风约 50 cm 处，音频依次经过 Mic、Audio Codec、AENC，最后在 Rec_Sout 侧取得录音/编码结果。它不包含 ADP、AO 播放或 SEA 算法链路；需要验证播放回路时，应以前图的 AI → ADP → AO 路径和对应 PROC/DUMP 结果为准。

模块与参数说明

原始 PROC 工具的各模块分工如下。实际业务未创建对应模块时，PROC 输出为空是正常现象，应先启动待测场景再查询。

PROC 模块	重点观察内容	用于定位的问题
ab	DSP 版本、主频、编译时间和模块 attach 关系	DSP 镜像是否匹配、模块是否按预期级联。
sys	dump/proc 掩码、性能、共享内存、静态段和动态段	DSP 资源、内存占用与调试开关。
sync	中断、时钟同步与偏差统计	音频时基或外设同步异常。
ai	输入端口格式、DMA、运行异常、输出缓冲区	无录音、底噪、输入溢出或端口格式异常。
adp	数据/信息缓冲区、送帧和取帧统计	数据转发失败、缓冲区不足、帧处理异常。
sea	算法实例、算法处理状态和输出关系	唤醒、语音增强或算法输出异常。
aenc / adec	编码/解码实例、码流和帧统计	编解码格式、送帧或取流异常。
ao	输出端口、格式和运行状态	无声、输出端口或播放链路异常。

API 接口列表

接口或工具	用途	参考
sample_proc	输出 ai、sea、adec、aenc、ao、ab、adp 的状态	源码实现
sample_dump	按模块类型和句柄抓取数据	源码实现
uapi_audio_get_debug_cfg、uapi_audio_set_debug_cfg	读取和设置音频调试配置	头文件声明
AudioManagerDumpInfo	导出应用层 AudioManager 状态	API 参考：AudioManagerDumpInfo
DumpInfo	导出应用层音频管理对象信息	API 参考：DumpInfo

快速跑通音频调试 Demo

功能说明

本 Demo 以麦克风直通为被测链路。先启动 sample_ai_ao，再查询 AI、ADP、AO 的 proc 状态；若需要波形证据，从 proc 输出中取得句柄后，用 sample_dump 导出 AI 或 SEA 的数据。

Demo 流程

编译

说明：本文示例命令以一站式 CLI 为主。实际开发可从以下三种环境中选择，推荐使用一站式 CLI。

开发环境	适用场景	使用指南
一站式 CLI（推荐）	快速完成目标选择、构建、烧录和串口监视	一站式 CLI 开发环境使用指南
HiSpark Studio for VS Code	图形化编辑、编译、烧录和调试	HiSpark Studio for VS Code 开发环境使用指南
WSL 与 Docker	在 Windows 上使用一致的 Linux 容器构建环境	WSL 与 Docker 环境使用指南

1. 按 一站式 CLI 开发环境使用指南 准备环境、构建和烧录；构建前必须确保 fbb doctor 成功。
2. 保证设备端有可写文件系统；抓取文件路径必须是当前目标实际可访问的路径。
3. 明确要观察的链路和格式，例如 adc0、16 kHz、16 bit、单声道。
4. 调试时只运行一个音频 sample，关闭音乐、通话和其他可能占用输入/输出设备的业务。

使用方式

按以下顺序执行；<ai_handle> 必须替换为本次 sample_proc ai 输出的十六进制句柄。

AT^AUDIO=sample_ai_ao -p adc0 -c 1 -s 16000
AT^AUDIO=sample_proc ai
AT^AUDIO=sample_proc adp
AT^AUDIO=sample_proc ao
AT^AUDIO=sample_dump /user/ai.pcm 1024 ai <ai_handle> 0
AT^AUDIO=sample_ai_ao q

命令参数、句柄来源和异常分支说明见“核心调试流程”。

预期结果

完成构建和烧录后，依次执行“启动链路 → 查询 PROC → 可选 DUMP → 停止链路”。预期结果如下：

• sample_proc 能输出对应模块信息，且格式与启动参数一致。
• AI、ADP、AO 均处于已创建/运行状态，模块句柄有效。
• DUMP 文件大小达到指定上限或场景停止后结束，PCM 可按正确格式打开。

文件结构与代码走读

文件结构

/src/application/audio/
├── sample_audio.c
└── tools/
    ├── sample_proc.c
    └── sample_dump.c
/src/middleware/utils/at/at_audio_cmd/at/at_audio.c

各文件职责

文件	职责
/src/application/audio/sample_audio.c	注册 sample_proc、sample_dump 等音频样例入口，并将 AT 音频子命令分发到对应函数。
/src/application/audio/tools/sample_proc.c	维护 g_proc_mod_list，按模块名读取驱动 PROC 状态。
/src/application/audio/tools/sample_dump.c	校验路径、大小、模块和句柄后创建数据抓取任务。
/src/middleware/utils/at/at_audio_cmd/at/at_audio.c	解析 AT^AUDIO 参数并转交音频场景函数。

代码走读

核心调试流程

步骤 1：建立最小链路

AT^AUDIO=sample_ai_ao -p adc0 -c 1 -s 16000

先确认扬声器能够听到实时声音。此步骤失败时，先处理硬件、端口和格式问题，不要直接开始抓取算法数据。

步骤 2：读取模块状态

AT^AUDIO=sample_proc ai
AT^AUDIO=sample_proc adp
AT^AUDIO=sample_proc ao

sample_proc 的模块映射表位于 sample_proc.c 的 g_proc_mod_list：run_mod_proc() 先按模块名查找，再调用对应的 ai_read_proc()、sea_read_proc()、ao_read_proc() 等驱动 PROC 函数。除常用的 ai、sea、adec、aenc、ao、ab、adp 外，当前代码也支持 sys、sync 和按特性启用的 haid。

static const proc_mod_item g_proc_mod_list[] = {
    {PROC_MOD_AI, "ai", ai_read_proc},
    {PROC_MOD_SEA, "sea", sea_read_proc},
    {PROC_MOD_AO, "ao", ao_read_proc},
    {PROC_MOD_SYS, "sys", sys_read_proc},
    {PROC_MOD_ADP, "adp", adp_read_proc},
};

记录 PROC 输出中的句柄、输入输出格式、端口和运行状态；后续 sample_dump 的句柄必须来自同一次运行的 PROC 输出。

步骤 3：抓取输入或算法数据

以下命令中的 <ai_handle> 是步骤 2 获取的十六进制句柄，路径按实际文件系统修改：

# 从 AI 模块抓取 1024 KB 数据到文件
AT^AUDIO=sample_dump /user/ai.pcm 1024 ai <ai_handle> 0

抓取 SEA 输出时，将模块类型换为 sea，并提供相应的 SEA 句柄和输出类型。sample_dump 的 g_dump_mod_name_list 支持 ai、sea、adec、aenc、track 和 sound；它最多可同时抓取两个模块，每个抓取单元由“路径、KB 大小、模块名、句柄、输出类型”组成。

sample_dump_entry() 会先校验文件大小、模块名和句柄，再创建抓取任务。因此 DUMP 文件为 0 时，除了检查文件系统，也应确认句柄没有因停止或重启场景而失效。

步骤 4：比较数据并停止链路

把导出的 PCM 用与 proc 一致的采样率、位宽和声道数播放或做频谱分析。若 AI 数据正常而 AO 无声，问题在 ADP/SOUND/AO 或板级输出；若 AI 数据已异常，优先检查输入设备和增益。

AT^AUDIO=sample_ai_ao q

基于音频调试 Demo 开发自己的音频业务

测试验证

观察结果	优先结论	下一步
AI proc 不存在或无数据	输入端未打开或端口/硬件异常	检查 -p 参数、MIC 供电和板级引脚配置
AI DUMP 正常、AO 无声	输入正常，问题在 ADP/SOUND/AO 或扬声器	查询 adp、ao，再播放独立 PCM 验证输出
AI DUMP 有削波/底噪	输入增益或电路质量异常	降低增益并按输入调测图检查底噪、干扰
SEA 前正常、SEA 后异常	算法/overlay/参数问题	先关闭 SEA，再检查算法版本和输入格式
时有时无或出现抢占	音频资源或中断策略导致	检查并停掉其他音频业务，必要时导出 AudioManager 信息

注意事项

• sample_dump 的句柄只在当前实例生命周期内有效；停止或重启 sample 后必须重新查询。
• 路径不可写、剩余空间不足或抓取大小过大时，DUMP 会失败；先用较小容量验证。
• 调试数据可能包含用户语音；导出、传输和保存时需遵守数据安全要求。
• 不要以耳听结果替代格式检查。PCM 的格式一旦选错，正常数据也会听起来像噪声。

常见编译错误

常见运行错误

问题	处理
sample_proc 提示模块名错误	使用 g_proc_mod_list 支持的 ai、sea、adec、aenc、ao、ab、sys、sync、adp，以及按特性启用的 haid。
DUMP 立即结束或文件为 0	检查模块是否在运行、句柄是否来自当前 proc、路径是否可写。
不知道 DUMP 使用什么格式播放	以 proc 输出或启动 sample 时的格式为准，不能凭文件扩展名推断。
同一问题反复出现但日志不同	固化测试命令、端口、格式和固件版本；每次只修改一个变量。