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. |
| 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 | Abbreviation of Transmit/Receive. |
| PINMUX | Pin Multiplexer provides a method of configuring the individual pin peripheral multiplexers to select alternate pin functions. |
Supported features
- Support 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. The feature comparisons between two modes are shown below.
- 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.
- The system architecture of the driver is shown in the diagram below.
How to use this driver
- Configure GPIO pins used by the I2S hardware.
- Set the GPIO pins to the I2S function based on the user's hardware platform design. Bit clock line(BCK) and word select line(WS) are required while either data in line(DI) or data out line(DO) is needed, depending on the user's application. For more details about the PINMUX setting of the I2S functions, please refer to GPIO driver document.
- Sample code:
void i2s_master_gpio_init(void)
{
uint32_t gpio_mode = 3;
}
- 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;
break;
}
}
{
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 sample rate and channel number for TX and RX links as well as the clock mode for the whole I2S. The channel number should be set to HAL_I2S_STEREO, and the sample rate of TX and RX links should be configured to the same one before enabling the I2S functions. The functions are:
- Memory query functions
Check the usage of the internal memory for the I2S operation, to ensure the accuracy of the data transfer. Call memory query functions hal_i2s_get_memory_size() and hal_i2s_set_memory() to provide sufficient memory for the I2S driver before performing the actual data transfers.
The hal_i2s_get_memory_size() function determines the memory size required for the internal use.
Allocate memory for the I2S operation with a size that is greater than or equal to the size queried by hal_i2s_get_memory_size(), and then call hal_i2s_set_memory() function.
Call hal_i2s_get_memory_pointer() function to return the pointer to the memory provided previously by the user. 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. The functions are:
- Data transfer functions
This function queries the available data for an input.
- Parameters
-
| [out] | sample_count | is the number of received samples. (in bytes) |
- 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 buffer to perform read operation.
- See also
- hal_i2s_rx_read()
This function queries the available free space for an output.
- Parameters
-
| [out] | sample_count | is the number of free samples available for an output. (in bytes) |
- Returns
- HAL_I2S_STATUS_INVALID_PARAMETER, if a NULL pointer is given by user.
HAL_I2S_STATUS_OK, if the operation is successful.
- Note
- Call thin function before hal_i2s_tx_write() function to ensure there is enough free space in the TX 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 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()
This function submits the allocated memory to the I2S driver.
- Parameters
-
| [in] | memory | is the pointer to a memory. |
- Returns
- HAL_I2S_STATUS_ERROR, if an error occurred during the memory allocation in this function. An error might occur if the given input size of memory is not enough or the internal memory of the I2S is already occupied.
HAL_I2S_STATUS_OK, if the operation is successful.
- Note
- Call this function after user allocates enough memory greater than or equal to the size queried by hal_i2s_get_memory_size() function.
- See also
- hal_i2s_get_memory_pointer() and hal_i2s_get_memory_size()
| hal_i2s_status_t hal_i2s_tx_write |
( |
const void * |
buffer, |
|
|
uint32_t |
sample_count |
|
) |
| |
1.8.11 
