This section introduces the I2S APIs including terms and acronyms, supported features, software architecture, details on how to use this driver, I2S function groups, enums, structures and functions.
More...
This section introduces the I2S APIs including terms and acronyms, supported features, software architecture, details on how to use this driver, I2S function groups, enums, structures and functions.
Terms and acronyms
| Terms | Details |
| I2S | Inter-IC Sound is a standard electrical serial bus interface used for connecting digital audio devices. |
| TDM | Time division multiplexed (TDM) formats are used when more than two channels of data are to be transferred on a single data line. |
| VFIFO DMA | A virtual first in first out (VFIFO) direct memory access (DMA) device applied in an electronic device having a processor, a I2S unit and a VFIFO unit is provided. In the VFIFO DMA device, a DMA unit is for transferring data between the I2S unit and the VFIFO unit. A VFIFO controller, which has a read pointer and a write pointer, is electrically connected with the DMA unit. When the DMA unit reads data from or writes data into the VFIFO unit, the VFIFO controller correspondingly changes the value of the read pointer or the write pointer. A virtual port is electrically connected to the DMA unit and the processor. A processor reads data from or writes data into the VFIFO unit via the virtual port and the DMA unit. |
| ISR | Interrupt service routine is a software routine that is executed in response to an interrupt. |
| NVIC | Nested Vectored Interrupt Controller is the interrupt controller of ARM Cortex-M. For more details, please refer to NVIC introduction in ARM Cortex-M4 Processor Technical Reference Manual. |
| TX/RX | Transmitter/Receiver. |
| PINMUX | Pin Multiplexer provides a method of configuring the individual pin peripheral multiplexers to select alternate pin functions. |
Supported features
- Note.
User must configure the I2S and use this driver based on the hardware platform design. For more details about the I2S functions, please refer to platform specification document.
- Master and slave mode.
Based on the diversities of audio applications and hardware capabilities of external codec components, the I2S operates in different modes. In master mode, bit clock and word select lines are driven by the I2S master, while all other devices derive their internal clocks from this reference. On the contrary, bit clock and word select are derived from the external devices when slave mode is configured. Except for the clock source, the I2S in master and slave mode also provide different capabilities in sample rate, channel number and applications.
- Support callback function registration.
An interrupt will be triggered when the data is ready to be transferred using the I2S interface. A callback function must be registered and called to handle data transfer in the I2S interrupt service routine.
Software architecture of I2S
- The VFIFO DMA hardware is a special DMA used with the I2S data transmit and receive operations. The VFIFO DMA hardware assists the MCU to transmit or receive data. TX/RX VFIFO buffers are used to cache the data during transmit and receive operations. The user should initialize the DMA hardware before transmitting or receiving the data. The TX/RX VFIFO buffers are registered in DMA hardware with their corresponding addresses and sizes.
- For transmit operation, call hal_i2s_tx_write() function to transmit data. The user must query the free space in the TX VFIFO buffer to ensure there is enough free space in the TX VFIFO buffer for the write operation. The TX VFIFO DMA interrupt will be triggered if the remaining data length in the TX VFIFO buffer is less than the threshold of the TX VFIFO buffer. Then the TX VFIFO DMA interrupt handler will call user's callback to notify that the TX VFIFO buffer is available. User can write data to the TX VFIFO buffer again by calling hal_i2s_tx_write() function.
- For receive operation, hal_i2s_rx_read() function is used. The user must check the RX VFIFO buffer and fetch data from the RX VFIFO buffer until it's empty. The RX VFIFO DMA interrupt will be triggered if the data length in the RX VFIFO buffer is larger than the threshold of the RX VFIFO buffer. Then the RX VFIFO DMA interrupt handler calls the user's callback to notify that the data is available. User can fetch the data from the RX VFIFO buffer again by calling hal_i2s_rx_read() function.
How to use this driver
- Configure the GPIO pins used by the I2S.
- Set the GPIO pins for Bit clock line(BCK), word select line(WS), master clock(MCLK), data in line(DI) and data out line(DO) to support the I2S, based on the user`s hardware platform design. For more details about the PINMUX setting of the I2S functions, please refer to GPIO driver document.
- Use I2S transmit/receive (TX/RX) both on for external codec functionality.
- Event handling for TX and RX links data transfer operations.
- The callback functions of TX and RX links are always invoked in the NVIC ISR. It is recommended to send the events of TX and RX links to user-defined media task in callback functions and handle the corresponding data operations in media task to avoid long operations in the ISR.
- An example implementation below explain how to handle events in a user-defined media task.
{
}
{
}
{
switch(event) {
break;
break;
}
}
I2S function groups description
The APIs are grouped by their functionality for an easier use. User can refer to the details of each function by clicking the function name.
- Initialization and configuration functions
The hal_i2s_init() function configures the I2S type to be set at the beginning of an I2S operation.
The hal_i2s_deinit() function resets the I2S type configuration.
The hal_i2s_set_config() function configures the I2S settings providing the respective sampling rate, downsampling rate in RX mode, data swapping between right and left channels, word select(WS) inverting, mono duplication in TX mode, bits delay from frame sync and channel number for TX and RX links as well as the clock mode for the whole I2S. The user should configure settings before enabling the I2S functions.
The hal_i2s_get_config() function gets the current I2S settings.
The hal_i2s_setup_tx_vfifo() function configures DMA TX VFIFO.
The hal_i2s_setup_rx_vfifo() function configures DMA RX VFIFO.
The functions are:
- Callback register functions
Use these functions to register callback functions for TX and RX link data operation.
The functions are:
- Enable and disable functions
Call hal_i2s_enable_tx() function to enable the I2S TX link to transmit the data.
Call hal_i2s_disable_tx() function to disable the I2S TX data transmission immediately.
Call hal_i2s_enable_rx() function to enable the I2S RX link to receive data.
Call hal_i2s_disable_rx() function to disable the I2S RX immediately.
Call hal_i2s_enable_audio_top() function to enable the I2S audio top immediately.
Call hal_i2s_disable_audio_top() function to disable the I2S audio top immediately.
The functions are:
- Data transfer functions
- TX link data transfer
Call hal_i2s_get_tx_sample_count() function before hal_i2s_tx_write() function to determine the free space available in the TX VFIFO buffer for the write operation.
The functions are:
- hal_i2s_tx_write()
- hal_i2s_get_tx_sample_count()
- sample code:
uint32_t user_buffer[data_buffer_length] = {
static void i2s_write_data(void)
{
uint32_t sample_count = 0;
uint32_t write_count = 0;
if( data_buffer_length < sample_count) {
for(write_count=0;write_count<data_buffer_length;write_count++)
}
}
- RX link data transfer
Call hal_i2s_get_rx_sample_count() function before hal_i2s_rx_read() function to determine the samples available in the RX VFIFO buffer for the I2S read operation.
The functions are:
- hal_i2s_rx_read()
- hal_i2s_get_rx_sample_count()
- sample code:
static void i2s_read_data(void)
{
uint32_t user_buffer[data_buffer_length];
uint32_t sample_count = 0;
uint32_t read_count = 0;
uint32_t store_data = 0;
memset(user_buffer, 0, sizeof user_buffer);
while(sample_count!=0) {
if(read_count<data_buffer_length){
user_buffer[read_count]=store_data;
read_count++;
}
else
break;
}
}
This function queries length of the received data available in the RX VFIFO.
- Parameters
-
| [out] | sample_count | is the length of the received data available in the RX VFIFO. |
- Returns
- HAL_I2S_STATUS_OK, if the operation is successful.
The return value is reserved for further expansion. The current value is always set to HAL_I2S_STATUS_OK.
- Note
- Call this function before hal_i2s_rx_read() function to ensure there is data available in the RX VFIFO buffer to perform read operation.
- See also
- hal_i2s_rx_read()
This function queries available free space in the TX VFIFO.
- Parameters
-
| [out] | sample_count | is the available free space in the TX VFIFO.(Number of data words to write) |
- Returns
- HAL_I2S_STATUS_ERROR, if the user do not configure the buffer length for TX VFIFO by hal_i2s_setup_tx_vfifo().
HAL_I2S_STATUS_OK, if the operation is successful.
- Note
- Call this function before hal_i2s_tx_write() function to ensure there is enough free space in the TX VFIFO buffer for the write operation.
- See also
- hal_i2s_tx_write()
This function registers the callback function for input data.
- Parameters
-
| [in] | rx_callback | is a callback function for the received data control. |
| [in] | user_data | is a user defined input data. |
- Returns
- HAL_I2S_STATUS_INVALID_PARAMETER, if the rx_callback is invalid.
HAL_I2S_STATUS_OK, if the operation is successful.
- Note
- Send I2S RX events to a user-defined task and handle the data transfer there to avoid longer performances in the NVIC ISR.
This function registers the callback function for output data.
- Parameters
-
| [in] | tx_callback | is a pointer to the callback function to control data transmission. |
| [in] | user_data | is a user defined input data. |
- Returns
- HAL_I2S_STATUS_INVALID_PARAMETER, if the tx_callback is invalid.
HAL_I2S_STATUS_OK, if the operation is successful.
- Note
- Send I2S TX events to a user-defined task and handle the data transfer there to avoid longer performances in the NVIC ISR.
This function receives data from the I2S input link.
- Parameters
-
| [out] | data | is the 32-bit data buffer to receive, bit[31:16] means the data of right channel and bit[15:0] means the data of left channel. |
- Returns
- HAL_I2S_STATUS_OK, if the operation is successful.
The return value is reserved for further expansion. The current value is always set to HAL_I2S_STATUS_OK.
- Note
- Call this function after hal_i2s_get_rx_sample_count() function to ensure there is data available in the RX VFIFO buffer to perform read operation.
- See also
- hal_i2s_get_rx_sample_count()
This function sets the I2S configuration details.
- Parameters
-
| [in] | config | is the link configuration of the I2S module. For more details about this parameter, please refer to hal_i2s_config_t. |
- Returns
- HAL_I2S_STATUS_INVALID_PARAMETER, if wrong parameter is given. User should check the parameter when receiving this value.
HAL_I2S_STATUS_ERROR, if one of the I2S links is still available. Call hal_i2s_disable_tx() and hal_i2s_disable_rx() to disable the TX/RX links before calling this function.
HAL_I2S_STATUS_OK, if the operation is successful.
- Note
- To avoid unpredictable system operation, calling hal_i2s_set_config() during the I2S execution is not allowed. User should disable the TX/RX links before setting the configuration.
Set the sampling rates of the TX and RX to the same value. Different values are not allowed.
- See also
- hal_i2s_get_config()
| hal_i2s_status_t hal_i2s_setup_rx_vfifo |
( |
uint32_t * |
buffer, |
|
|
uint32_t |
threshold, |
|
|
uint32_t |
buffer_length |
|
) |
| |
This function sets up the receive operation.
The FIFO starts to pump data from I2S RX into the RX VFIFO buffer if the I2S RX is enabled.
VFIFO DMA will trigger an interrupt when the amount of available receive data in the RX VFIFO is larger than the RX VFIFO threshold.
- Parameters
-
| [in] | buffer | is the pointer to memory buffer for the RX VFIFO. |
| [in] | threshold | is the value of the RX VFIFO threshold. |
| [in] | buffer_length | is the length of the memory buffer for the RX VFIFO. |
- Returns
- HAL_I2S_STATUS_ERROR, if one of I2S links is still available. Call hal_i2s_disable_tx(), hal_i2s_disable_rx() and hal_i2s_disable_audio_top() to disable the TX/RX links before calling this function.
HAL_I2S_STATUS_INVALID_PARAMETER, if the buffer is a NULL pointer.
HAL_I2S_STATUS_OK, if the operation is successful.
- See also
- hal_i2s_stop_rx_vfifo()
- Note
- To avoid unpredictable system operation, calling hal_i2s_setup_rx_vfifo() during the I2S execution is not allowed. User should disable the I2S links before setting the configuration.
Buffer is occupied by VFIFO until the transmission is complete.
| hal_i2s_status_t hal_i2s_setup_tx_vfifo |
( |
uint32_t * |
buffer, |
|
|
uint32_t |
threshold, |
|
|
uint32_t |
buffer_length |
|
) |
| |
This function sets up the transmit operation.
The FIFO starts to pump data from the TX VFIFO buffer into I2S TX if the I2S TX is enabled.
VFIFO DMA will trigger an interrupt when the amount of output data in TX VFIFO is lower than the TX VFIFO threshold.
- Parameters
-
| [in] | buffer | is the pointer to memory buffer for the TX VFIFO. |
| [in] | threshold | is the value of the TX VFIFO threshold. |
| [in] | buffer_length | is the length to memory buffer for the TX VFIFO. |
- Returns
- HAL_I2S_STATUS_ERROR, if one of I2S links is still available. Call hal_i2s_disable_tx(), hal_i2s_disable_rx() and hal_i2s_disable_audio_top() to disable the TX/RX links before calling this function.
HAL_I2S_STATUS_INVALID_PARAMETER, if the buffer is a NULL pointer.
HAL_I2S_STATUS_OK, if the operation is successful.
- See also
- hal_i2s_stop_tx_vfifo()
- Note
- To avoid unpredictable system operation, calling hal_i2s_setup_tx_vfifo() during the I2S execution is not allowed. User should disable the I2S links before setting the configuration.
Buffer is occupied by VFIFO until the transmission is complete.
This function stops the receive operation.
The FIFO will stop to pump data from the I2S RX into the RX VFIFO buffer.
- Returns
- HAL_I2S_STATUS_OK, if the operation is successful.
The return value is reserved for further expansion. The current value is always set to HAL_I2S_STATUS_OK.
- See also
- hal_i2s_setup_rx_vfifo()
This function stops the transmit operation.
The FIFO will stop to pump data from the TX VFIFO buffer into I2S TX.
- Returns
- HAL_I2S_STATUS_OK, if the operation is successful.
The return value is reserved for further expansion. The current value is always set to HAL_I2S_STATUS_OK.
- See also
- hal_i2s_setup_tx_vfifo()
1.8.11 
