I2S API 参考
Macros
-
WM_DRV_I2S_RX_MIN_PKT_LEN
The number of TX and RX packets and the size boundary detection value. The actual size is passed in the initialization parameters, but cannot exceed these boundary values, how to use pkt_size and pkt num, wm_drv_i2s_cfg_t*.
RX: minimum packet size
-
WM_DRV_I2S_RX_MAX_PKT_LEN
RX: maximum packet size
-
WM_DRV_I2S_RX_MIN_PKT
RX: minimum number of packets
-
WM_DRV_I2S_RX_MAX_PKT
RX: maximum number of packets
-
WM_DRV_I2S_TX_MIN_PKT
TX: minimum number of packets
-
WM_DRV_I2S_TX_MAX_PKT
TX: maximum number of packets
Enumerations
-
enum wm_drv_i2s_ioctl_cmd_t
command id for I2S IOCTL
Values:
-
enumerator WM_DRV_I2S_CMD_SET_TX_BITSHIFT
enable / disable tx clock phase shift mode (disable by default)
-
enumerator WM_DRV_I2S_CMD_SET_RX_BITSHIFT
enable / disable rx clock phase shift mode (disable by default)
-
enumerator WM_DRV_I2S_CMD_SET_LZC
enable / disable left zero cross check for rx(disable by default)
-
enumerator WM_DRV_I2S_CMD_SET_RZC
enable / disable right zero cross check for rx(disable by default)
-
enumerator WM_DRV_I2S_CMD_SET_MAX
-
enumerator WM_DRV_I2S_CMD_SET_TX_BITSHIFT
-
enum wm_drv_i2s_sample_rates
sample rate supported by HW
备注
The following supported sampling rates may not result in an exact master clock output under different configurations because, according to the formula: clock_div = clock_master / (sample_rate * channels * bitwidth), it may not be possible to obtain an integer value for clock_div. The default value of the current I2S’s clock_master is 160000000. Please refer to the RCC module for the final effective value.
Values:
-
enumerator WM_DRV_I2S_SP_8000
i2s sample rate set to 8KHz
-
enumerator WM_DRV_I2S_SP_11025
i2s sample rate set to 11.025KHz
-
enumerator WM_DRV_I2S_SP_16000
i2s sample rate set to 16KHz
-
enumerator WM_DRV_I2S_SP_22050
i2s sample rate set to 22.05KHz
-
enumerator WM_DRV_I2S_SP_24000
i2s sample rate set to 24KHz
-
enumerator WM_DRV_I2S_SP_32000
i2s sample rate set to 32KHz
-
enumerator WM_DRV_I2S_SP_44100
i2s sample rate set to 44.1KHz
-
enumerator WM_DRV_I2S_SP_47250
i2s sample rate set to 47.25KHz
-
enumerator WM_DRV_I2S_SP_48000
i2s sample rate set to 48KHz
-
enumerator WM_DRV_I2S_SP_50000
i2s sample rate set to 50KHz
-
enumerator WM_DRV_I2S_SP_50400
i2s sample rate set to 50.04KHz
-
enumerator WM_DRV_I2S_SP_96000
i2s sample rate set to 96KHz
-
enumerator WM_DRV_I2S_SP_192000
i2s sample rate set to 192KHz
-
enumerator WM_DRV_I2S_SP_MAX
-
enumerator WM_DRV_I2S_SP_8000
Type Definitions
-
typedef int (*wm_drv_i2s_callback_t)(wm_device_t *dev, wm_drv_i2s_event_t *event)
callback type
- Param dev:
[in] The I2S device.
- Param event:
[in] event type, wm_drv_i2s_event_t
Structures
-
struct wm_drv_i2s_event_t
The TX (transmit) and RX (receive) event.
备注
Event has the following cases WM_DRV_I2S_EVENT_TX_DONE len > 0 notify user 1 pkt sent WM_DRV_I2S_EVENT_TX_DONE len == 0 notify user to remove buffer when tx stoped WM_DRV_I2S_EVENT_RX_READY len > 0 notify user 1 pkt ok received WM_DRV_I2S_EVENT_RX_READY len == 0 notify user to remove buffer when rx stoped WM_DRV_I2S_EVENT_RX_DONE len == 0 rx no data now, the peer send end
Public Members
-
wm_drv_i2s_event_type_t type
curernt event type
-
uint8_t *buf
curernt transfer end buffer
-
int len
the actual length of received data
-
void *priv
For user use, not use by i2s driver
-
wm_drv_i2s_event_type_t type
-
struct wm_drv_i2s_cfg_t
configuration of I2S controller
Public Members
-
enum wm_i2s_mode mode
I2S role mode
-
enum wm_i2s_dir dir
I2S xfer direction
-
enum wm_i2s_std std
I2S protocol standard
-
enum wm_i2s_xfer_type xtype
the transfer type select from DMA or others
-
uint32_t rx_pkt_size
The buffer size of each received packet [80 ~ 15360]. Usually set to 10/20 millisecond transmission data size. 4 bytes aligned. The larger the rx_pkt_size, the longer the delay of notifying the upper layer of processing, and the longer the delay of sound output
-
uint8_t rx_pkt_num
Max number of the RX package receive buffer [2~16], recommended 4, can be large if rx_pkt_size is small
-
uint8_t tx_pkt_num
Max number of the TX packages wait to send, [2~16] recommended 4, can be large if tx send pkt size is small
-
enum wm_i2s_mode mode
-
struct wm_drv_i2s_format_t
I2S format information.
Public Members
-
uint32_t sample_rate_hz
the sample rate for the audio data
-
enum wm_i2s_bits bits
I2S frame format standard
-
enum wm_i2s_chan_type ctype
the channel type, mono or stereo
-
uint32_t sample_rate_hz
Functions
-
wm_device_t *wm_drv_i2s_init(const char *name, wm_drv_i2s_cfg_t *cfg)
Initializes the I2S driver with the given configuration.
This function initializes the I2S driver with the provided configuration. It sets up the I2S controller according to the specified parameters and prepares the driver for data transfer.
备注
I2S transmit and receive data will be valid on the rising edge of BCLK.
警告
For 24 bit sampling, it is necessary to expand 24 bits to 32 bits for each sample before sending, and all the high 8 bits are 0. After receiving, it is necessary to remove the high 8 bits and restore the samples to 24 bits.
- 参数:
name – [in] The name of the I2S device.
cfg – [in] A pointer to the configuration structure for the I2S driver.
- 返回:
A pointer to the initialized I2S device.
NULL: If the initialization fails,
-
int wm_drv_i2s_deinit(wm_device_t *device)
Deinitializes the I2S driver and releases all associated resources.
This function deinitializes the I2S driver and releases all associated resources. It stops any ongoing data transfers, disables the I2S controller, and frees any allocated memory.
- 参数:
device – [in] A pointer to the I2S device to be deinitialized.
- 返回:
WM_ERR_SUCESS: If the deinitialization is successful.
others: If the deinitialization fails
-
int wm_drv_i2s_set_format(wm_device_t *device, uint32_t sample_rate_hz, enum wm_i2s_bits bits, enum wm_i2s_chan_type channel)
set xfer audio format
备注
Called before starting read/write
- 参数:
device – [in] A pointer to the I2S device to be deinitialized.
sample_rate_hz – [in] sample rate, unit Hz.
bits – [in] the sample bits witdh
channel – [in] channel type
- 返回:
WM_ERR_SUCESS: If the deinitialization is successful.
others: If the deinitialization fails
-
int wm_drv_i2s_set_mclk(wm_device_t *device, uint32_t mclk_hz)
set mclk, Usually output to codec for use
备注
Called before starting read/write
- 参数:
device – [in] A pointer to the I2S device to be deinitialized.
mclk_hz – [in] mclk, unit Hz.
- 返回:
WM_ERR_SUCESS: If the deinitialization is successful.
others: If the deinitialization fails
-
int wm_drv_i2s_write_async(wm_device_t *device, void *buf, int len)
Asynchronously writes data to the I2S device.
This function asynchronously writes data to the I2S device. The data is stored in a buffer provided by the user and is written to the device when the driver is ready. The user can register a callback function to be notified when the data has been successfully transmitted.
备注
Please note that after the user’s buffer is sent, the registered tx done callback will be called to notify the user to complete operations such as releasing.
备注
The starting address of buf must be 4-byte aligned; otherwise, otherwise the driver will report an error.
备注
The data length needs to 4bytes aligned , otherwise the driver will report an error.
备注
The maximum transfer length is less than 64K.
- 参数:
device – [in] A pointer to the I2S device to which the data will be written.
buf – [in] A pointer to the buffer containing the data to be written.
len – [in] The length of the data in the buffer.
- 返回:
WM_ERR_SUCCESS: If the write operation is successful.
WM_ERR_NO_MEN: The DMA list is full, Can’t append write buffer now, wait until the TX done event
others: If the write operation fails
-
int wm_drv_i2s_write_pause(wm_device_t *device)
Pauses the ongoing write operation to the I2S device.
This function pauses the ongoing write operation to the I2S device. It stops any further data transmission and prevents any new write operations. The clock is not stoped if it is master mode. The peer side can receive dummy data continuously. The buffer data is hold on. Call `wm_drv_i2s_write_resume()` to resume.
- 参数:
device – [in] A pointer to the I2S device to which the data will be written.
- 返回:
WM_ERR_SUCCESS: If the write operation is successfully paused.
others: If the write operation fails
-
int wm_drv_i2s_write_resume(wm_device_t *device)
Resumes the ongoing write operation to the I2S device.
This function resumes the ongoing write operation to the I2S device. It allows any previously paused write operations to continue data transmission. The write operation must be paused using `wm_drv_i2s_write_pause()` before it can be resumed.
- 参数:
device – [in] A pointer to the I2S device to which the data will be written.
- 返回:
WM_ERR_SUCCESS: If the write operation is successfully resumed.
others: If the write operation fails
-
int wm_drv_i2s_write_stop(wm_device_t *device)
Stops the ongoing write operation to the I2S device.
This function stops the ongoing write operation to the I2S device. It stops any further data transmission and prevents any new write operations from being initiated. All write data buffers are released. The clock is stoped if it is master mode and duplex mode.
- 参数:
device – [in] A pointer to the I2S device to which the data will be written.
- 返回:
WM_ERR_SUCCESS: If the write operation is successfully stopped.
others: If the write operation fails
-
int wm_drv_i2s_read_async(wm_device_t *device, void *buf, int len)
Append a read buffer to DMA receive list.
This function asynchronously reads data from the I2S device. The data is stored in a buffer provided by the user and is read from the device when the driver is ready. The user can register a callback function to be notified when the data has been successfully received.
备注
When receiving is started, call rx_pkt_num times, and then call once for each packet of data received. Do not execute in an interrupt
- 参数:
device – [in] A pointer to the I2S device from which the data will be read.
buf – [in] buffer for recevie data, must 4 bytes align
len – [in] recive buffer size, must equal to rx_pkt_size.
- 返回:
WM_ERR_SUCCESS: If the read operation is successful.
WM_ERR_NO_MEN: The DMA list is full, Can’t append read buffer now, wait until the RX ready event
others: If the read operation fails
-
int wm_drv_i2s_read_pause(wm_device_t *device)
Pauses the ongoing read operation to the I2S device.
This function pauses the ongoing read operation to the I2S device. It stops any further data reception and prevents any new read operations from being initiated until the read operation is resumed using The receive buffers with data will not be freed `wm_drv_i2s_read_resume()`.
- 参数:
device – [in] A pointer to the I2S device from which the data will be read.
- 返回:
WM_ERR_SUCCESS: If the read operation is successfully paused.
others: If the read operation fails
-
int wm_drv_i2s_read_resume(wm_device_t *device)
Resumes the ongoing read operation to the I2S device.
This function resumes the ongoing read operation to the I2S device. It allows any previously paused read operations to continue data reception. The read operation must be paused using `wm_drv_i2s_read_pause()` before it can be resumed.
- 参数:
device – [in] A pointer to the I2S device from which the data will be read.
- 返回:
WM_ERR_SUCCESS: If the read operation is successfully resumed.
others: If the read operation fails
-
int wm_drv_i2s_read_stop(wm_device_t *device)
Stops the ongoing read operation to the I2S device.
This function stops the ongoing read operation to the I2S device. It stops any further data reception and prevents any new read operations It will free the read buffers. from being initiated.
- 参数:
device – [in] A pointer to the I2S device from which the data will be read.
- 返回:
WM_ERR_SUCCESS: If the read operation is successfully stopped.
others: If the read operation fails
-
int wm_drv_i2s_register_write_cb(wm_device_t *device, wm_drv_i2s_callback_t callback)
Registers a callback function to be called when the data has been successfully transmitted.
This function registers a callback function to be called when the data has been successfully transmitted during an asynchronous write operation. The callback function is called with the buffer that was written to the I2S device.
备注
The registered callback function SHOULD NOT be blocked
- 参数:
device – [in] A pointer to the I2S device to which the data will be written.
callback – [in] A pointer to the callback function that will be called when the data has been successfully transmitted.
- 返回:
WM_ERR_SUCCESS: If the callback function is successfully registered.
others: If the callback function registration fails
-
int wm_drv_i2s_register_read_cb(wm_device_t *device, wm_drv_i2s_callback_t callback)
Registers a callback function to be called when the data has been successfully received.
This function registers a callback function to be called when the data has been successfully received during an asynchronous read operation. The callback function is called with the buffer that was read from the I2S device.
备注
User SHOULD remember to free the buffer by calling the free in the buffer structure
- 参数:
device – [in] A pointer to the I2S device from which the data will be read.
callback – [in] A pointer to the callback function that will be called when the data has been successfully received.
- 返回:
WM_ERR_SUCCESS: If the callback function is successfully registered.
others: If the callback function registration fails
-
int wm_drv_i2s_ioctl(wm_device_t *device, wm_drv_i2s_ioctl_cmd_t cmd, bool enable, uint32_t arg)
Performs input/output control operations on the specified I2S device.
This function allows the user to perform various input/output control operations on the I2S device, such as setting configuration parameters, enabling/disabling features, and retrieving status information.
备注
when the cmd use WM_DRV_I2S_CMD_SET_CLK_SRC, arg is the external clock, unit in HZ, If set to true, a valid mclk_hz must be input from the GPIO bound to mclk (e.g., PA7), which should be at least 2 * 256 * N * Fs Hz (where N is an integer), this is set to false by default that means generate mclk with internal PLL
- 参数:
device – [in] A pointer to the I2S device on which the IOCTL operation will be performed.
cmd – [in] command type, wm_drv_i2s_ioctl_cmd_t
enable – [in] enable or not
arg – [in] external argument for the spedific command
- 返回:
WM_ERR_SUCCESS: If the IOCTL operation is successful.
others: If the IOCTL operation fails.
-
int wm_drv_i2s_dump_info(wm_device_t *device)
dump i2s information, Used for debug.
- 参数:
device – [in] A pointer to the I2S device.
- 返回:
WM_ERR_SUCCESS: If the callback function is successfully registered.
WM_ERR_INVALID_PARAM: invalid param