I2S API 参考
Macros
-
WM_DRV_I2S_NBC_TDEPTH
During the transmission process, the buffer will be cached at the driver (BD) layer, and will be appropriately handed down as needed. The macro `WM_DRV_I2S_NBC_TDEPTH` is used to determine the number of Buffer Descriptors (BDs) of TX at the driver layer. Each BD can be associated with a user buffer, so a larger value indicates that more user buffers can be cached, which means a greater tolerance for link fluctuations. Conversely, a smaller value indicates fewer BDs at the driver layer, which results in less memory usage, but also less tolerance for link fluctuations
-
WM_DRV_I2S_NBC_RDEPTH
During the reception process, the buffer will be cached at the driver (BD) layer, and will be appropriately handed up as needed. The macro `WM_DRV_I2S_NBC_RDEPTH` is used to determine the number of Buffer Descriptors (BDs) of RX at the driver layer. Each BD can be associated with a user buffer, so a larger value indicates that more user buffers can be cached, which means a greater tolerance for link fluctuations. Conversely, a smaller value indicates fewer BDs at the driver layer, which results in less memory usage, but also less tolerance for link fluctuations
-
WM_DRV_I2S_DESC_TDEPTH
During the transmission process, the buffer will be cached at the HAL (Hardware Abstraction Layer) (DESC) layer, and will be appropriately handed up or down as needed. The macro `WM_DRV_I2S_DESC_TDEPTH` will determine the number of DMA descriptors at the HAL layer, similar to `WM_DRV_I2S_NBC_TDEPTH`, which will determine the maximum allowable link fluctuation tolerated by the DMA hardware. The larger this value is set, the more buffers can be provided to the DMA. This allows for more continuous and smooth data transfer by the hardware, reducing the probability of DMA stopping due to lack of data to transmit.
-
WM_DRV_I2S_DESC_RDEPTH
During the reception process, the buffer will be cached at the HAL (Hardware Abstraction Layer) (DESC) layer, and will be appropriately handed up or down as needed. The macro `WM_DRV_I2S_DESC_RDEPTH` will determine the number of DMA descriptors at the HAL layer, similar to `WM_DRV_I2S_NBC_TDEPTH`, which will determine the maximum allowable link fluctuation tolerated by the DMA hardware. The larger this value is set, the more buffers can be provided to the DMA. This allows for more continuous and smooth data transfer by the hardware, reducing the probability of DMA stopping due to lack of data to transmit.
-
WM_DRV_I2S_DESC_MAX_BUF_LEN
The macro `WM_DRV_I2S_DESC_MAX_BUF_LEN` represents the maximum buffer length that each RX DMA descriptor can be associated with, and the user’s initialization configuration parameter `rx_pkt_size` must not exceed this set value.
-
WM_DRV_I2S_DESC_DEF_BUF_LEN
The default buffer size for the RX DMA DESC, when the user does not set `rx_pkt_size` in the configuration parameters.
Enumerations
-
enum wm_drv_i2s_ioctl_cmd
command id for I2S IOCTL
Values:
-
enumerator WM_DRV_I2S_CMD_SET_MUTE
enable / disable mute for tx/rx(disable mute by default)
-
enumerator WM_DRV_I2S_CMD_SET_BITSHIFT
enable / disable clock phase shift mode for tx/rx(enable 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_MONO_LEFT
true if set mono channel to left, else right channel(left channel by default)
-
enumerator WM_DRV_I2S_CMD_SET_CLK_SRC
set I2S clock source and mclk source(internal clock by default)
-
enumerator WM_DRV_I2S_CMD_SET_MAX
-
enumerator WM_DRV_I2S_CMD_SET_MUTE
-
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 struct wm_drv_i2s_rbuf wm_drv_i2s_rxbuf_t
-
typedef int (*i2s_tx_done_cb_t)(void *buf)
User callback interface for the completion of `buf` transmission, generally used for operations such as release.
- Param buf:
[in] the buffer from user to be transmitted
- Return:
WM_ERR_SUCCESS: succeed
others: failed
-
typedef int (*i2s_rx_ready_cb_t)(wm_drv_i2s_rxbuf_t *buf)
User callback interface for data reception completion; after the user is finished with it, they need to call the ‘free’ function carried in the structure to release the resources.
- Param buf:
[in] the buffer from driver which include valid data and some helper function
- Return:
WM_ERR_SUCCESS: succeed
others: failed
-
typedef int (*i2s_free_buf_cb_t)(void *buf)
Used for releasing the RX buffer.
- Param buf:
[in] the buffer from driver which include valid data and some helper function
- Return:
WM_ERR_SUCCESS: succeed
others: failed
Structures
-
typedef struct wm_drv_i2s_tbuf wm_drv_i2s_tx_nb_t
ring node body for user ready buffers
-
struct wm_drv_i2s_ioctl_args_t
parameter struct for I2S IOCTL
备注
The clock configuration section must be carried out after I2S initialization and before starting data transmission and reception; otherwise, it will affect the data transfer.
Public Members
-
bool tx
Select tx/rx for the relevant CMD
-
bool extal_en
Used to select whether to use an external clock to generate mclk. If set to true, a valid extal_clock_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
-
uint32_t extal_clock_hz
the external clock value in unit Hz
-
bool en
If the corresponding function of the enable command is activated, set it to true; otherwise, set it to false.
-
bool tx
-
struct wm_drv_i2s_tbuf
ring node body for user ready buffers
-
struct wm_drv_i2s_rbuf
ring node body for received ready buffers
Public Members
-
uint32_t magic
Used to check if the memory space is valid
-
struct wm_drv_i2s_rbuf *next
privated field used by driver internal
-
i2s_free_buf_cb_t free
the next rx ready buffer
-
int len
used to free this node Typically, equal to rx_pkt_size, the actual received length in case of exceptions or timeouts.
-
char data[]
size from rx_pkt_size in user cfg
-
uint32_t magic
-
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_fmt fmt
I2S frame format standard
-
enum wm_i2s_chan_type ctype
the channel type, mono or stereo
-
enum wm_i2s_xfer_type xtype
the transfer type select from DMA or others
-
uint32_t sample_rate_hz
the sample rate for the audio data
-
uint32_t rx_pkt_size
max size in bytes for each received pkt, should be 4-bytes aligned
-
uint32_t rx_ready_th
rx ready pkts cache threshold number before upload to user
-
uint32_t tx_ready_th
tx ready pkts cache threshold number before deliver to HAL
-
enum wm_i2s_mode mode
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.
- 参数:
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_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 also needs to be aligned to a 4-byte boundary, otherwise the driver will report an error.
备注
The maximum transfer length is determined by the DMA attributes, wm_drv_dma_xfer_cfg_t;
- 参数:
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.
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 from being initiated until the write operation is resumed using `wm_drv_i2s_write_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.
- 参数:
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)
Asynchronously reads data start from the I2S device.
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.
备注
This function can not be called more than once, it used to start the asynchronous read operation
- 参数:
device – [in] A pointer to the I2S device from which the data will be read.
- 返回:
WM_ERR_SUCCESS: If the read operation is successful.
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 `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 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, i2s_tx_done_cb_t cb)
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.
cb – [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, i2s_rx_ready_cb_t cb)
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.
cb – [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_args_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.
备注
The specific IOCTL operations and their parameters are defined by the `wm_drv_i2s_ioctl_args_t` structure and the `wm_drv_i2s_ioctl_cmd` enum.
- 参数:
device – [in] A pointer to the I2S device on which the IOCTL operation will be performed.
arg – [in] A pointer to the structure containing the IOCTL arguments.
- 返回:
WM_ERR_SUCCESS: If the IOCTL operation is successful.
others: If the IOCTL operation fails.
-
void wm_drv_i2s_dump_cfgs(wm_device_t *device)
Dumps the configuration of the specified I2S device.
This function dumps the configuration of the specified I2S device. It prints the configuration parameters of the I2S device to the console, including the mode, direction, standard, format, channel type, transfer type, mclk enable status, left channel status, and sample rate.
备注
TODO: this function will be removed
- 参数:
device – [in] A pointer to the I2S device whose configuration will be dumped.