MT2523 API Reference  LinkIt SDK v4
I2S

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

Overview

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

Clock mode Master Slave
Type HAL_I2S_TYPE_EXTERNAL_MODE,
HAL_I2S_TYPE_INTERNAL_LOOPBACK_MODE
HAL_I2S_TYPE_EXTERNAL_MODE
Channel Mono, Stereo Mono
Sample rate 8k/ 11.025k/ 12k/ 16k/ 22.05k/ 24k/ 32k/ 44.1k/ 48k Hz 8k/ 16k Hz
Speech Enhancement support No Yes

How to use this driver

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.

Functions

hal_i2s_status_t hal_i2s_init (hal_i2s_initial_type_t i2s_initial_type)
 This function initializes the I2S hardware type. More...
 
hal_i2s_status_t hal_i2s_deinit (void)
 This function deinitializes the I2S hardware. More...
 
hal_i2s_status_t hal_i2s_set_config (const hal_i2s_config_t *config)
 This function sets the I2S configuration details. More...
 
hal_i2s_status_t hal_i2s_get_config (hal_i2s_config_t *config)
 This function queries the I2S configuration details. More...
 
hal_i2s_status_t hal_i2s_get_memory_size (uint32_t *memory_size)
 This function queries the size of the required memory to be allocated for an internal use in the I2S driver. More...
 
hal_i2s_status_t hal_i2s_set_memory (uint8_t *memory)
 This function submits the allocated memory to the I2S driver. More...
 
hal_i2s_status_t hal_i2s_get_memory_pointer (uint8_t **memory_pointer)
 This function receives the pointer to the memory buffer. More...
 
hal_i2s_status_t hal_i2s_register_rx_callback (hal_i2s_rx_callback_t rx_callback, void *user_data)
 This function registers the callback function for input data. More...
 
hal_i2s_status_t hal_i2s_register_tx_callback (hal_i2s_tx_callback_t tx_callback, void *user_data)
 This function registers the callback function for output data. More...
 
hal_i2s_status_t hal_i2s_enable_tx (void)
 This function enables the I2S output link. More...
 
hal_i2s_status_t hal_i2s_disable_tx (void)
 This function disables the I2S output link. More...
 
hal_i2s_status_t hal_i2s_tx_write (const void *buffer, uint32_t sample_count)
 This function transmits data to the I2S output link. More...
 
hal_i2s_status_t hal_i2s_get_tx_sample_count (uint32_t *sample_count)
 This function queries the available free space for an output. More...
 
hal_i2s_status_t hal_i2s_enable_rx (void)
 This function enables the I2S input link. More...
 
hal_i2s_status_t hal_i2s_disable_rx (void)
 This function disables the I2S input link. More...
 
hal_i2s_status_t hal_i2s_rx_read (void *buffer, uint32_t sample_count)
 This function receives data from the I2S input link. More...
 
hal_i2s_status_t hal_i2s_get_rx_sample_count (uint32_t *sample_count)
 This function queries the available data for an input. More...
 

Modules

 Enum
 
 Struct
 
 Typedef
 

Function Documentation

hal_i2s_status_t hal_i2s_deinit ( void  )

This function deinitializes the I2S hardware.

Returns
HAL_I2S_STATUS_ERROR, if one of 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.
See also
hal_i2s_init()
hal_i2s_status_t hal_i2s_disable_rx ( void  )

This function disables the I2S input link.

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_enable_rx()
hal_i2s_status_t hal_i2s_disable_tx ( void  )

This function disables the I2S output link.

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_enable_tx()
hal_i2s_status_t hal_i2s_enable_rx ( void  )

This function enables the I2S input link.

Returns
HAL_I2S_STATUS_ERROR, if RX callback function is not registered. Call hal_i2s_register_rx_callback() to register RX link callback function before calling this function.
HAL_I2S_STATUS_OK, if the operation is successful.
Note
Register RX link callback function by hal_i2s_register_rx_callback() before enabling the RX link to avoid unpredictable situation occurred during the system execution.
See also
hal_i2s_disable_rx()
hal_i2s_status_t hal_i2s_enable_tx ( void  )

This function enables the I2S output link.

Returns
HAL_I2S_STATUS_ERROR, if TX callback function is not registered. Call hal_i2s_register_tx_callback() to register TX callback function before calling this function.
HAL_I2S_STATUS_OK, if the operation is successful.
Note
Call hal_i2s_register_tx_callback() to register a callback function before enabling the TX link to avoid unpredictable malfunctioning during the system execution.
hal_i2s_status_t hal_i2s_get_config ( hal_i2s_config_t config)

This function queries the I2S configuration details.

Parameters
[out]configis the link configuration of I2S module which is set in system. For more details about this parameter, please refer to hal_i2s_config_t.
Returns
HAL_I2S_STATUS_INVALID_PARAMETER, if the input parameter is invalid.
HAL_I2S_STATUS_OK, if the operation is successful.
See also
hal_i2s_set_config()
hal_i2s_status_t hal_i2s_get_memory_pointer ( uint8_t **  memory_pointer)

This function receives the pointer to the memory buffer.

Parameters
[out]memory_pointeris the pointer to an allocated memory previously provided by hal_i2s_set_memory() function.
Returns
HAL_I2S_STATUS_INVALID_PARAMETER, if the input parameter is invalid.
HAL_I2S_STATUS_OK, if the operation is successful.
See also
hal_i2s_set_memory()
hal_i2s_status_t hal_i2s_get_memory_size ( uint32_t *  memory_size)

This function queries the size of the required memory to be allocated for an internal use in the I2S driver.

Parameters
[out]memory_sizeis the amount of memory required for the I2S driver for an internal use. (in bytes)
Returns
HAL_I2S_STATUS_INVALID_PARAMETER, if the input parameter is invalid.
HAL_I2S_STATUS_OK, if the operation is successful.
Note
Call this function at least before hal_i2s_enable_tx() or hal_i2s_enable_rx() to ensure there is enough memory for an internal use.
See also
hal_i2s_set_memory()
hal_i2s_status_t hal_i2s_get_rx_sample_count ( uint32_t *  sample_count)

This function queries the available data for an input.

Parameters
[out]sample_countis 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()
hal_i2s_status_t hal_i2s_get_tx_sample_count ( uint32_t *  sample_count)

This function queries the available free space for an output.

Parameters
[out]sample_countis 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()
hal_i2s_status_t hal_i2s_init ( hal_i2s_initial_type_t  i2s_initial_type)

This function initializes the I2S hardware type.

Parameters
[in]i2s_initial_typeis the initial configuration parameter. Please refer to hal_i2s_initial_type_t.
Returns
HAL_I2S_STATUS_INVALID_PARAMETER, if input parameter is invalid.
HAL_I2S_STATUS_ERROR, if one of 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
Set i2s_initial_type as HAL_I2S_TYPE_EXTERNAL_MODE when using external codec component in the application.
See also
hal_i2s_deinit()
hal_i2s_status_t hal_i2s_register_rx_callback ( hal_i2s_rx_callback_t  rx_callback,
void *  user_data 
)

This function registers the callback function for input data.

Parameters
[in]rx_callbackis a callback function for the received data control.
[in]user_datais 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.
hal_i2s_status_t hal_i2s_register_tx_callback ( hal_i2s_tx_callback_t  tx_callback,
void *  user_data 
)

This function registers the callback function for output data.

Parameters
[in]tx_callbackis a pointer to the callback function to control data transmission.
[in]user_datais 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.
hal_i2s_status_t hal_i2s_rx_read ( void *  buffer,
uint32_t  sample_count 
)

This function receives data from the I2S input link.

Parameters
[in]bufferis a pointer to the user's data buffer.
[in]sample_countis the number of received samples. (in bytes)
Returns
HAL_I2S_STATUS_INVALID_PARAMETER, if input parameter sample_count is zero or greater than the size of the data available in the RX buffer. For more details about the parameter sample_count, please refer to hal_i2s_get_rx_sample_count().
HAL_I2S_STATUS_ERROR, when any error occurred during data read operation.
HAL_I2S_STATUS_OK, if data read operation is complete.
See also
hal_i2s_get_rx_sample_count()
hal_i2s_status_t hal_i2s_set_config ( const hal_i2s_config_t config)

This function sets the I2S configuration details.

Parameters
[in]configis 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_set_memory ( uint8_t *  memory)

This function submits the allocated memory to the I2S driver.

Parameters
[in]memoryis 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 
)

This function transmits data to the I2S output link.

Parameters
[in]bufferis a pointer to the output data.
[in]sample_countis the available free space in the output buffer. (in bytes)
Returns
HAL_I2S_STATUS_INVALID_PARAMETER, if input parameter sample_count is zero or greater than the size of the free space in the TX buffer. For more details about the parameter sample_count, please refer to hal_i2s_get_tx_sample_count().
HAL_I2S_STATUS_ERROR, if an error occurred during data transmission.
HAL_I2S_STATUS_OK, if the data transmission is complete.
See also
hal_i2s_get_tx_sample_count()