docs: 补充核心分层中文注释
This commit is contained in:
chenjintao
@@ -32,6 +32,12 @@
|
||||
#include "driver/i2s_std.h"
|
||||
#include "driver/i2c_master.h"
|
||||
|
||||
/*
|
||||
* Kconfig 兼容默认值：仅在配置项缺失时生效。后面的编译期约束仍强制语音链路使用
|
||||
* 16 kHz、双物理时隙和16位 PCM，因此默认值不等于所有板型都可直接运行。
|
||||
* These are compatibility fallbacks for missing Kconfig values; compile-time
|
||||
* checks below still enforce the audio format required by voice/AEC processing.
|
||||
*/
|
||||
#ifndef CONFIG_MULTIMODAL_AUDIO_ENABLE_CODEC_PATH
|
||||
#define CONFIG_MULTIMODAL_AUDIO_ENABLE_CODEC_PATH 1
|
||||
#endif
|
||||
@@ -68,6 +74,7 @@
|
||||
#define CONFIG_MULTIMODAL_AUDIO_I2S_PORT 0
|
||||
#endif
|
||||
|
||||
/* I2C/I2S GPIO 必须由板级 Kconfig 明确提供，避免错误默认引脚驱动真实硬件。 */
|
||||
#ifndef CONFIG_MULTIMODAL_AUDIO_I2S_MCLK_GPIO
|
||||
#error "CONFIG_MULTIMODAL_AUDIO_I2S_MCLK_GPIO must be defined in Kconfig"
|
||||
#endif
|
||||
@@ -97,6 +104,10 @@
|
||||
#endif
|
||||
|
||||
#ifndef CONFIG_MULTIMODAL_AUDIO_I2S_DMA_DESC_NUM
|
||||
/*
|
||||
* I2S DMA 默认4个描述符、每描述符160帧：增加可提高抗调度抖动能力，但会占用更多
|
||||
* DMA 内存并增加排队延迟；减少则降低内存占用，但更容易出现采集/播放 underrun。
|
||||
*/
|
||||
#define CONFIG_MULTIMODAL_AUDIO_I2S_DMA_DESC_NUM 4
|
||||
#endif
|
||||
|
||||
@@ -105,6 +116,7 @@
|
||||
#endif
|
||||
|
||||
#ifndef CONFIG_MULTIMODAL_AUDIO_OUT_VOLUME
|
||||
/* codec 初始增益属于硬件安全基线；调整前需同时检查削波、啸叫和扬声器功率。 */
|
||||
#define CONFIG_MULTIMODAL_AUDIO_OUT_VOLUME 60
|
||||
#endif
|
||||
|
||||
@@ -113,6 +125,10 @@
|
||||
#endif
|
||||
|
||||
#ifndef CONFIG_MULTIMODAL_AUDIO_MIC_CHANNEL
|
||||
/*
|
||||
* 双时隙输入中，麦克风与 AEC 回采必须使用不同槽位；滤波长度增大可覆盖更长回声，
|
||||
* 但会增加运算量和工作内存。编译期检查防止两个通道配置为同一槽位。
|
||||
*/
|
||||
#define CONFIG_MULTIMODAL_AUDIO_MIC_CHANNEL 0
|
||||
#endif
|
||||
|
||||
@@ -129,6 +145,11 @@
|
||||
#endif
|
||||
|
||||
#ifndef CONFIG_MULTIMODAL_AUDIO_DOWNSTREAM_IDLE_MUTE_MS
|
||||
/*
|
||||
* 下行播放时序权衡：首次积累 PREBUFFER 后开声；断流超过 REBUFFER_GAP 后重新缓冲，
|
||||
* 最大积累量受 MAX_REBUFFER 限制以避免延迟持续增长；正常排空后等待 IDLE_MUTE
|
||||
* 再静音以减少爆音，活动响应长时间无数据则按 ACTIVE_STALL 判定卡顿。
|
||||
*/
|
||||
#define CONFIG_MULTIMODAL_AUDIO_DOWNSTREAM_IDLE_MUTE_MS 250
|
||||
#endif
|
||||
|
||||
@@ -153,6 +174,11 @@
|
||||
#endif
|
||||
|
||||
#ifndef CONFIG_MULTIMODAL_AUDIO_DOWNSTREAM_PLAYBACK_TASK_STACK
|
||||
/*
|
||||
* 下行任务承担 Opus 解码和 codec 写入，栈下限保护最深调用链。队列长度和单包容量
|
||||
* 共同决定最坏内存占用；配置值会被归一化到 MIN/CAP 范围，避免过小不可运行或
|
||||
* 过大耗尽 PSRAM。修改时应同时评估端到端延迟和网络突发大小。
|
||||
*/
|
||||
#define CONFIG_MULTIMODAL_AUDIO_DOWNSTREAM_PLAYBACK_TASK_STACK 12288
|
||||
#endif
|
||||
|
||||
@@ -173,6 +199,10 @@
|
||||
#define MULTIMODAL_AUDIO_DOWNSTREAM_PLAYBACK_PACKET_CAP_BYTES 8192U
|
||||
|
||||
#ifndef CONFIG_MULTIMODAL_AUDIO_UPLINK_TASK_STACK
|
||||
/*
|
||||
* 上行采集栈包含 I2S、AEC 和 Opus 编码调用链，因此基线大于纯发送任务。发送队列
|
||||
* 将网络抖动与实时采集隔离；5ms 入队等待刻意选择“及时丢包”而非阻塞采集。
|
||||
*/
|
||||
#define CONFIG_MULTIMODAL_AUDIO_UPLINK_TASK_STACK 32768
|
||||
#endif
|
||||
|
||||
@@ -199,6 +229,10 @@
|
||||
#endif
|
||||
|
||||
#ifndef CONFIG_MULTIMODAL_AUDIO_INIT_RETRY_COUNT
|
||||
/*
|
||||
* 初始化重试前先检查最大连续 DMA/内部内存块，避免在堆碎片严重时构建出半初始化
|
||||
* codec。阈值是创建 I2S/codec 控制对象所需的安全水位，不是总空闲内存要求。
|
||||
*/
|
||||
#define CONFIG_MULTIMODAL_AUDIO_INIT_RETRY_COUNT 1
|
||||
#endif
|
||||
|
||||
@@ -211,6 +245,10 @@
|
||||
#endif
|
||||
|
||||
#ifndef CONFIG_MULTIMODAL_OPUS_FRAME_DURATION_MS
|
||||
/*
|
||||
* 服务端协议要求 60ms raw-Opus 帧。24kbps、低复杂度和关闭 VBR/DTX/FEC 是当前
|
||||
* 实时性与 MCU 负载基线；改变任一项需同步验证服务端解码、包容量和网络带宽。
|
||||
*/
|
||||
#define CONFIG_MULTIMODAL_OPUS_FRAME_DURATION_MS 60
|
||||
#endif
|
||||
|
||||
@@ -259,6 +297,7 @@
|
||||
#endif
|
||||
|
||||
#ifndef CONFIG_MULTIMODAL_AUDIO_TASK_CORE
|
||||
/* 音频任务默认固定到本地实时核心；负数表示由调度器决定，需重新验证抖动。 */
|
||||
#define CONFIG_MULTIMODAL_AUDIO_TASK_CORE 1
|
||||
#endif
|
||||
|
||||
@@ -268,6 +307,10 @@
|
||||
#define MULTIMODAL_AUDIO_CORE_ID ((BaseType_t)CONFIG_MULTIMODAL_AUDIO_TASK_CORE)
|
||||
#endif
|
||||
|
||||
/*
|
||||
* 解码缓冲包含最小工作区和保护余量；TX bounce 缓冲用于处理 codec 短写。
|
||||
* AEC 缓冲按16字节对齐以满足 DSP/SIMD 访问要求。
|
||||
*/
|
||||
#define MULTIMODAL_PCM_SAMPLE_BYTES 2U
|
||||
#define MULTIMODAL_MIN_DECODER_PCM_BUFFER_BYTES 2048U
|
||||
#define MULTIMODAL_DECODER_BUFFER_GUARD_BYTES 512U
|
||||
@@ -280,6 +323,7 @@
|
||||
static const char *TAG = "multimodal_audio";
|
||||
static portMUX_TYPE s_audio_runtime_lock = portMUX_INITIALIZER_UNLOCKED;
|
||||
|
||||
/* 音频上下行共享 codec/I2S 资源，因此所有生命周期状态集中保存在单一上下文中。 */
|
||||
typedef struct {
|
||||
const audio_codec_data_if_t *data_if;
|
||||
const audio_codec_ctrl_if_t *ctrl_if;
|
||||
@@ -355,6 +399,7 @@ typedef struct {
|
||||
} multimodal_audio_ctx_t;
|
||||
|
||||
static multimodal_audio_ctx_t s_audio;
|
||||
/* 下行播放以 generation 标识会话，终止事件只唤醒等待同一代的调用方。 */
|
||||
static multimodal_audio_downstream_playback_callback_t s_downstream_playback_cb;
|
||||
static void *s_downstream_playback_cb_ctx;
|
||||
static SemaphoreHandle_t s_downstream_playback_completion_sem;
|
||||
@@ -423,10 +468,17 @@ typedef struct {
|
||||
uint8_t *data;
|
||||
} downstream_packet_t;
|
||||
|
||||
/* Split implementation by concern while keeping a single translation unit:
|
||||
* - helpers: memory, config normalization, utility helpers
|
||||
* - codec: codec/i2c/i2s/opus setup and teardown
|
||||
* - runtime: uplink/downlink processing and public APIs
|
||||
/*
|
||||
* 实现文件拆分规则：
|
||||
* - 下列 *_impl.c 不能单独加入 CMake 或独立编译，只能由本文件按当前顺序包含；
|
||||
* - 它们共享本文件上方定义的 static 类型、状态、宏和前置声明；
|
||||
* - 拆分仅为了按职责降低阅读长度，不形成新的模块或链接边界；
|
||||
* - include 顺序有意为 helpers -> codec -> debug -> runtime，后面的实现可以使用
|
||||
* 前面已经定义的内部辅助函数，调整顺序前必须检查可见声明和依赖方向。
|
||||
*
|
||||
* Included *_impl.c files are not standalone translation units. They share this
|
||||
* file's static state and are split only for readability. Their include order is
|
||||
* dependency-sensitive and must not be changed without reviewing symbol visibility.
|
||||
*/
|
||||
|
||||
#include "audio_pipeline/audio_pipeline_helpers_impl.c"
|
||||
|
||||
Reference in New Issue
Block a user