The latest development version of this page may be more current than this released 2.3-beta.1 version.

I2S API Reference

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
enum wm_drv_i2s_sample_rates

sample rate supported by HW

Note

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
enum wm_drv_i2s_event_type_t

i2s event type

Values:

enumerator WM_DRV_I2S_EVENT_TX_DONE

send one packet end

enumerator WM_DRV_I2S_EVENT_RX_READY

one packet receive end

enumerator WM_DRV_I2S_EVENT_RX_DONE

hardware detect no rx data for a moment

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.

Note

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

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

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

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.

Note

I2S transmit and receive data will be valid on the rising edge of BCLK.

Warning

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.

Parameters:

  • name – [in] The name of the I2S device.

  • cfg – [in] A pointer to the configuration structure for the I2S driver.

Returns:

  • 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.

Parameters:

device – [in] A pointer to the I2S device to be deinitialized.

Returns:

  • 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

Note

Called before starting read/write

Parameters:

  • 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

Returns:

  • 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

Note

Called before starting read/write

Parameters:

  • device – [in] A pointer to the I2S device to be deinitialized.

  • mclk_hz – [in] mclk, unit Hz.

Returns:

  • 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.

Note

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.

Note

The starting address of buf must be 4-byte aligned; otherwise, otherwise the driver will report an error.

Note

The data length needs to 4bytes aligned , otherwise the driver will report an error.

Note

The maximum transfer length is less than 64K.

Parameters:

  • 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.

Returns:

  • 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.

Parameters:

device – [in] A pointer to the I2S device to which the data will be written.

Returns:

  • 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.

Parameters:

device – [in] A pointer to the I2S device to which the data will be written.

Returns:

  • 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.

Parameters:

device – [in] A pointer to the I2S device to which the data will be written.

Returns:

  • 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.

Note

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

Parameters:

  • 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.

Returns:

  • 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()`.

Parameters:

device – [in] A pointer to the I2S device from which the data will be read.

Returns:

  • 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.

Parameters:

device – [in] A pointer to the I2S device from which the data will be read.

Returns:

  • 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.

Parameters:

device – [in] A pointer to the I2S device from which the data will be read.

Returns:

  • 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.

Note

The registered callback function SHOULD NOT be blocked

Parameters:

  • 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.

Returns:

  • 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.

Note

User SHOULD remember to free the buffer by calling the free in the buffer structure

Parameters:

  • 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.

Returns:

  • 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.

Note

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

Parameters:

  • 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

Returns:

  • 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.

Parameters:

device – [in] A pointer to the I2S device.

Returns:

  • WM_ERR_SUCCESS: If the callback function is successfully registered.

  • WM_ERR_INVALID_PARAM: invalid param