版本：0.1 | 日期：2026-07-03 | 路径： platforms/components/xtiny/xt_hal/

一、概述

xt_hal_i2s 是 xtiny 平台的 I2S（Inter-IC Sound）驱动模块，仅支持 Master 模式。提供阻塞传输、非阻塞 0 拷贝传输、流式传输和连续 pingpong 传输四种模式，覆盖从简单测试到低延迟实时音频的完整场景。

设计理念： 多种传输模式，按需选择 。从最简单的阻塞 API 到零拷贝连续流式传输，用户根据实时性要求自由选用。

1.1 设计原则

仅 Master 模式 ：所有函数名中的 m 表示 Master，模块不提供 Slave 模式接口
传输模式分层 ：阻塞（最简单）→ 非阻塞（带回调）→ 流式（缓冲队列）→ 连续 pingpong（零延迟），层次递进
全双工支持 ： txrx 系列函数同时收发，适用于双向音频场景
采样点计数 ：所有 size 参数和返回值以采样点（sample）为单位，非字节数

1.2 依赖

仅依赖 xt_hal_internal.h （ xt_error.h ）。

二、核心概念

2.1 传输模式对比

模式	函数后缀	阻塞	缓冲区管理	适用场景
阻塞	_block	是	用户提供	简单测试、初始化配置
0 拷贝	_0copy	否	用户提供	低延迟单次传输
流式	（无后缀）	否	内部缓冲队列	实时音频流
连续 pingpong	_continuous	否	用户提供，对半拆分	极低延迟实时音频

2.2 流式传输机制

流式（ tx / rx / txrx ）基于内部缓冲队列：用户先通过 set_tx_buf / set_rx_buf 注册缓冲区，再通过 tx / rx / txrx 推送/拉取数据。通过 get_rx_count / get_tx_free 查询缓冲区水位。

2.3 连续 pingpong 传输

_continuous 系列将用户提供的缓冲区对半拆分为前后两段：

启动后，硬件从前半段开始传输
前半段完成时，触发回调（事件 XT_HAL_I2S_EVENT_BATCH_DONE ），用户可填充/读取前半段
后半段完成时，再次触发回调，用户操作后半段
如此循环，直到调用 stop_continuous

用户必须在回调中及时处理数据，否则下一次 BATCH_DONE 到来时数据尚未更新。

2.4 回调与结果获取

xt_hal_i2s_set_cb 注册回调，事件类型： XT_HAL_I2S_EVENT_DONE （传输完成）、 XT_HAL_I2S_EVENT_BATCH_DONE （pingpong 半段完成）、 XT_HAL_I2S_EVENT_ERROR （错误）
xt_hal_i2sm_get_result 仅在回调函数中调用，获取当前完成的传输结果（缓冲区指针和采样点数）

三、API 参考

以下为函数签名大纲，完整的参数说明、返回值、注意事项请查看 xt_hal_i2s（I2S 驱动）。

3.1 生命周期

函数签名	说明
xt_err_t xt_hal_i2sm_setup(uint8_t i2s_id, uint32_t mode, uint32_t sample_rate_hz, uint8_t mck_pin, uint8_t sck_pin, uint8_t ws_pin, uint8_t sd_tx_pin, uint8_t sd_rx_pin)	初始化 I2S Master 模式
xt_err_t xt_hal_i2sm_close(uint8_t i2s_id)	关闭 I2S 接口

3.2 回调与结果

函数签名	说明
xt_err_t xt_hal_i2s_set_cb(uint8_t i2s_id, xt_hal_i2s_cb_t cb)	设置回调函数
xt_err_t xt_hal_i2sm_get_result(uint8_t i2s_id, struct xt_hal_i2s_result *result)	获取传输结果（仅可在回调中调用）

3.3 流式传输

函数签名	说明
xt_err_t xt_hal_i2sm_set_rx_buf(uint8_t i2s_id, void *buffer, size_t size)	设置流式接收缓冲区
xt_err_t xt_hal_i2sm_set_tx_buf(uint8_t i2s_id, void *buffer, size_t size)	设置流式发送缓冲区
int32_t xt_hal_i2sm_tx(uint8_t i2s_id, const void *tx_buffer, size_t size)	流式非阻塞发送
int32_t xt_hal_i2sm_rx(uint8_t i2s_id, void *rx_buffer, size_t size)	流式非阻塞接收
int32_t xt_hal_i2sm_txrx(uint8_t i2s_id, const void tx_buffer, void rx_buffer, size_t size)	流式非阻塞全双工
int32_t xt_hal_i2sm_get_rx_count(uint8_t i2s_id)	获取流缓冲区中已接收采样点数
int32_t xt_hal_i2sm_get_tx_free(uint8_t i2s_id)	获取流缓冲区中剩余空闲采样点数

3.4 0 拷贝传输

函数签名	说明
int32_t xt_hal_i2sm_tx_0copy(uint8_t i2s_id, const void *tx_buffer, size_t size)	非阻塞 0 拷贝发送
int32_t xt_hal_i2sm_rx_0copy(uint8_t i2s_id, void *rx_buffer, size_t size)	非阻塞 0 拷贝接收
int32_t xt_hal_i2sm_txrx_0copy(uint8_t i2s_id, const void tx_buffer, void rx_buffer, size_t size)	非阻塞 0 拷贝全双工

3.5 连续 pingpong 传输

函数签名	说明
xt_err_t xt_hal_i2sm_tx_continuous(uint8_t i2s_id, const void *tx_buffer, size_t size)	启动连续 pingpong 发送（size 需偶数）
xt_err_t xt_hal_i2sm_rx_continuous(uint8_t i2s_id, void *rx_buffer, size_t size)	启动连续 pingpong 接收（size 需偶数）
xt_err_t xt_hal_i2sm_txrx_continuous(uint8_t i2s_id, const void tx_buffer, void rx_buffer, size_t size)	启动连续 pingpong 全双工
xt_err_t xt_hal_i2sm_stop_continuous(uint8_t i2s_id)	停止连续 pingpong 传输

3.6 阻塞传输

函数签名	说明
int32_t xt_hal_i2sm_tx_block(uint8_t i2s_id, const void *tx_buffer, size_t size)	阻塞发送
int32_t xt_hal_i2sm_rx_block(uint8_t i2s_id, void *rx_buffer, size_t size)	阻塞接收
int32_t xt_hal_i2sm_txrx_block(uint8_t i2s_id, const void tx_buffer, void rx_buffer, size_t size)	阻塞全双工

3.7 类型

类型签名	说明
typedef void (*xt_hal_i2s_cb_t)(uint8_t i2s_id, uint32_t event_id)	I2S 回调函数类型
struct xt_hal_i2s_result { void tx_buffer; void rx_buffer; size_t size; }	I2S 传输结果

3.8 配置常量

常量	说明
XT_HAL_I2S_INVALID_ID	无效 I2S ID（ 0xFF ）
XT_HAL_I2S_PROTOCOL_I2S	标准 I2S 格式
XT_HAL_I2S_PROTOCOL_MSB_JUST	MSB 对齐格式
XT_HAL_I2S_PROTOCOL_LSB_JUST	LSB 对齐格式
XT_HAL_I2S_PROTOCOL_PCM	PCM 格式
XT_HAL_I2S_DATA_BITS_8 / _16 / _24 / _32	数据位宽
XT_HAL_I2S_CHANNELS_MONO	单声道
XT_HAL_I2S_CHANNELS_STEREO	立体声
XT_HAL_I2S_MCLK_64FS ~ _512FS	MCLK 倍频

四、常见模式

4.1 阻塞发送（最简单）

#include "xt_hal_i2s.h"
 
uint8_t id = 0;
uint32_t mode = XT_HAL_I2S_PROTOCOL_I2S
              | XT_HAL_I2S_DATA_BITS_16
              | XT_HAL_I2S_CHANNELS_STEREO
              | XT_HAL_I2S_MCLK_256FS;
 
xt_hal_i2sm_setup(id, mode, 48000, XT_HAL_GPIO_INVALID_ID, 1, 2, 3, XT_HAL_GPIO_INVALID_ID);
 
int16_t buf[256];
xt_hal_i2sm_tx_block(id, buf, 256);
 
xt_hal_i2sm_close(id);

4.2 连续 pingpong 发送

#include "xt_hal_i2s.h"
 
static int16_t tx_buf[512];
 
static void i2s_cb(uint8_t i2s_id, uint32_t event_id)
{
    struct xt_hal_i2s_result res;
    if (event_id == XT_HAL_I2S_EVENT_BATCH_DONE) {
        xt_hal_i2sm_get_result(i2s_id, &res);
        fill_audio_data(res.tx_buffer, res.size);
    }
}
 
void start_audio(uint8_t id, uint32_t mode)
{
    xt_hal_i2sm_setup(id, mode, 48000, XT_HAL_GPIO_INVALID_ID, 1, 2, 3, XT_HAL_GPIO_INVALID_ID);
    xt_hal_i2s_set_cb(id, i2s_cb);
    xt_hal_i2sm_tx_continuous(id, tx_buf, 512);
}

五、已知行为与限制

仅支持 Master 模式，不支持 Slave
_continuous 的 size 必须是偶数（内部对半分）
_continuous 的缓冲区必须在整个传输期间保持有效，直到 stop_continuous
get_result 仅可在回调函数中调用，其他时机行为未定义
mode 参数由多个 XT_HAL_I2S_* 常量组合，无效组合行为由平台决定