I2S
简要说明
- I2S(Inter—IC Sound)总线,
- 又称集成电路内置音频总线,是飞利浦公司为数字音频设备之间的音频数据传输而制定的一种总线标准,该总线专门用于音频设备之间的数据传输,广泛应用于各种多媒体系统。I2S总线接口通常为三线:I2S_SCLK, I2S_WS, I2S_SDA,也有四线接口: I2S_SCLK,I2S_WS, I2S_SDA, I2S_MCLK(用作codec的时钟源),以及五线双工接口:I2S_SCLK,I2S_WS, I2S_SDA, I2S_SDI,I2S_MCLK。
接口描述
csi_i2s_initialize
i2s_handle_t csi_i2s_initialize(int32_t idx, i2s_event_cb_t cb_event, void *cb_arg);
功能描述:
- 通过设备号初始化对应的i2s实例,返回i2s实例的句柄。
参数:
idx
: 设备号。cb_event
: i2s 实例的事件回调函数(一般在中断上下文执行)。回调函数原型定义见i2s_event_cb_t。 回调函数类型i2s_event_cb_t定义如下:typedef void (*i2s_event_cb_t)(int32_t idx, i2s_event_e event);
其中idx为设备号,event 为传给回调函数的事件类型。
i2s 回调事件枚举类型见i2s_event_e定义。
cb_arg
:回调函数用户参数。
返回值:
- NULL: 初始化失败。
- 其它: 实例句柄。
i2s_event_e:
名称 | 定义 | 备注 |
---|---|---|
I2S_EVENT_SEND_COMPLETE | 周期数据发送完成事件 | (见i2s_config_t定义tx_period) |
I2S_EVENT_RECEIVE_COMPLETE | 周期数据接收完成事件 | (见i2s_config_t定义rx_period) |
I2S_EVENT_TX_UNDERFLOW | 发送下溢事件 | |
I2S_EVENT_TX_OVERFLOW | 接收溢出事件 | |
I2S_EVENT_FRAME_ERROR | 传输帧格式错误事件 |
csi_i2s_uninitialize
int32_t csi_i2s_uninitialize(i2s_handle_t handle)
功能描述:
- i2s实例反初始化。该接口会停止i2s
- 实例正在进行的传输(如果有),并且释放相关的软硬件资源。
参数:
handle
: 实例句柄。
返回值:
- 错误码。
csi_i2s_enable
void csi_i2s_enable(i2s_handle_t handle, int en);
- 功能描述:
- 控制i2s模块使能,开启后i2s开始输出时钟信号。
- 参数:
handle
: 实例句柄。- en:1使能,0关闭
- 返回值:
- 错误码。
csi_i2s_get_capabilities
i2s_capabilities_t csi_i2s_get_capabilities(int32_t idx)
功能描述:
- 获取i2s实例支持的能力。
参数:
idx
: 设备号。
返回值:
- 描述i2s 能力的结构体,i2s功能定义见i2s_capabilities_t 。
i2s_capabilities_t:
名称 | 定义 | 备注 |
---|---|---|
uint32_t protocol_user : 1 | 支持自定义协议 | |
uint32_t protocol_i2s : 1 | 支持i2s协议 | |
uint32_t protocol_justified : 1 | 支持左右对齐协议 | |
uint32_t mono_mode : 1 | 支持单通道 | |
uint32_t mclk_pin : 1 | 支持提供主机时钟脚 | |
uint32_t event_frame_error : 1 | 支持帧格式错误事件上报 |
csi_i2s_config
int32_t csi_i2s_config(i2s_handle_t handle, i2s_config_t *config);
- 功能描述:
- 配置i2s参数。
- 参数:
handle
: 实例句柄。config
: 配置参数,见i2s_config_t定义。
- 返回值:
- 错误码。
名称 | 定义 | 备注 |
---|---|---|
cfg | i2s 协议配置参数,见i2s_config_type_t定义 | |
rate | 采样率 | |
tx_period | i2s 传输完毕tx_period bytes数据,触发用户回调函数,上报 I2S_EVENT_SEND_COMPLETE事件。 | |
rx_period | i2s 接收完毕tx_period bytes数据,触发用户回调函数,上报 I2S_EVENT_RECEIVE_COMPLETE事件。 | |
tx_buf | 发送缓存区 | |
tx_buf_length | 发送缓存区长度(bytes) | |
rx_buf | 接收缓存区 | |
rx_buf_length | 接收缓存区长度(bytes) |
csi_i2s_send
uint32_t csi_i2s_send(i2s_handle_t handle, const uint8_t *data, uint32_t length);
- 功能描述:
- i2s发送数据。
- 参数:
handle
: 实例句柄。data
:发送数据length
:发送数据长度
- 返回值:
- 实际写入缓存区的数据长度,例如:length=1000,实际缓存区空余100bytes,则只可写入100bytes数据,返回值为100。
csi_i2s_receive
uint32_t csi_i2s_receive(i2s_handle_t handle, uint8_t *buf, uint32_t length);
- 功能描述:
- i2s接收数据。
- 参数:
handle
: 实例句柄。buf
:存储接收数据length
:接收数据长度
- 返回值:
- 实际获取的数据长度,例如:length=1000,实际缓存区拥有100bytes,则只可读出100bytes数据,返回值为100。
csi_i2s_send_ctrl
int32_t csi_i2s_send_ctrl(i2s_handle_t handle, i2s_ctrl_e cmd);
功能描述:
- i2s发送控制。
- 参数:
handle
: 实例句柄。cmd
:控制指令,见i2s_ctrl_e 定义
返回值:
0:成功
其他:错误码
csi_i2s_receive_ctrl
int32_t csi_i2s_receive_ctrl(i2s_handle_t handle, i2s_ctrl_e cmd);
功能描述:
- i2s接收控制。
参数:
handle
: 实例句柄。cmd
:控制指令,见i2s_ctrl_e 定义
返回值:
0:成功
其他:错误码
i2s_ctrl_e:
名称 | 定义 | 备注 |
---|---|---|
I2S_STREAM_PAUSE | I2S传输暂停(缓存区数据保持) | |
I2S_STREAM_RESUME | I2S传输解除暂停(从缓存区断点继续) | |
I2S_STREAM_STOP | I2S停止传输(缓存区数据清空) | |
I2S_STREAM_START | I2S启动传输 |
csi_i2s_get_status
i2s_status_t csi_i2s_get_status(i2s_handle_t handle)
功能描述:
- 获取当前时刻i2s的状态。
参数:
handle
: 实例句柄。
返回值:
- i2s状态的结构体,i2s的状态定义见 i2s_status_t \<i2s_status_t\ * 。
i2s_status_t:
名称 | 定义 | 备注 |
---|---|---|
int32_t tx_runing: 1 | 发送忙 | |
uint32_t rx_runing: 1 | 接收忙 | |
uint32_t tx_fifo_empty: 1 | 发送缓存区空 | |
uint32_t rx_fifo_full: 1 | 接收缓存区满,接收溢出 | |
uint32_t frame_error: 1 | 帧数据错误 |
csi_i2s_power_control
int32_t csi_i2s_power_control(i2s_handle_t handle, csi_power_stat_e state)
功能描述:
- 配置设备实例的功耗模式。
参数:
handle
: 实例句柄。state
: 设备实例的功耗模式,参看- csi_power_stat_e 的定义。
返回值:
正常:0
其他:错误码
csi_power_stat_e:
名字 | 定义 | 备注 |
---|---|---|
DRV_POWER_OFF | 关电源状态 | |
DRV_POWER_LOW | 低电平状态 | |
DRV_POWER_FULL | 全电源状态 | |
DRV_POWER_SUSPEND | 挂起电源状态 |