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

Software architecture of I2S

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_enable_audio_top (void)
 This function enables uplink and downlink FIFOs of the I2S link. More...
 
hal_i2s_status_t hal_i2s_disable_audio_top (void)
 This function disables uplink and downlink FIFOs of the I2S link. More...
 
hal_i2s_status_t hal_i2s_enable_tx_dma_interrupt (void)
 This function enables the TX VFIFO DMA interrupt. More...
 
hal_i2s_status_t hal_i2s_disable_tx_dma_interrupt (void)
 This function disables the TX VFIFO DMA interrupt. More...
 
hal_i2s_status_t hal_i2s_enable_rx_dma_interrupt (void)
 This function enables the RX VFIFO DMA interrupt. More...
 
hal_i2s_status_t hal_i2s_disable_rx_dma_interrupt (void)
 This function disables the RX VFIFO DMA interrupt. More...
 
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. More...
 
hal_i2s_status_t hal_i2s_stop_tx_vfifo (void)
 This function stops the transmit operation. More...
 
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. More...
 
hal_i2s_status_t hal_i2s_stop_rx_vfifo (void)
 This function stops the receive operation. More...
 
hal_i2s_status_t hal_i2s_register_rx_vfifo_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_vfifo_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 (uint32_t data)
 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 available free space in the TX VFIFO. 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 (uint32_t *data)
 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 length of the received data available in the RX VFIFO. 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_audio_top ( void  )

This function disables uplink and downlink FIFOs of the I2S 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_audio_top()
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_rx_dma_interrupt ( void  )

This function disables the RX VFIFO DMA interrupt.

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_dma_interrupt()
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_disable_tx_dma_interrupt ( void  )

This function disables the TX VFIFO DMA interrupt.

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_dma_interrupt()
hal_i2s_status_t hal_i2s_enable_audio_top ( void  )

This function enables uplink and downlink FIFOs of the I2S 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.
Note
Call this function after hal_i2s_enable_tx() or hal_i2s_enable_rx().
See also
hal_i2s_disable_audio_top()
hal_i2s_status_t hal_i2s_enable_rx ( void  )

This function enables 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_disable_rx()
hal_i2s_status_t hal_i2s_enable_rx_dma_interrupt ( void  )

This function enables the RX VFIFO DMA interrupt.

Returns
HAL_I2S_STATUS_ERROR, if RX callback function is not registered. Call hal_i2s_register_rx_vfifo_callback() to register RX callback function before calling this function.
HAL_I2S_STATUS_OK, if the operation is successful.
See also
hal_i2s_disable_rx_dma_interrupt()
Note
To avoid unpredictable system operation, calling this function is not allowed if RX callback function is not registered.
hal_i2s_status_t hal_i2s_enable_tx ( void  )

This function enables 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_disable_tx()
hal_i2s_status_t hal_i2s_enable_tx_dma_interrupt ( void  )

This function enables the TX VFIFO DMA interrupt.

Returns
HAL_I2S_STATUS_ERROR, if TX callback function is not registered. Call hal_i2s_register_tx_vfifo_callback() to register TX callback function before calling this function.
HAL_I2S_STATUS_OK, if the operation is successful.
See also
hal_i2s_disable_tx_dma_interrupt()
Note
To avoid unpredictable system operation, calling this function is not allowed if TX callback function is not registered.
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_rx_sample_count ( uint32_t *  sample_count)

This function queries length of the received data available in the RX VFIFO.

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

This function queries available free space in the TX VFIFO.

Parameters
[out]sample_countis 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()
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_vfifo_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_vfifo_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 ( uint32_t *  data)

This function receives data from the I2S input link.

Parameters
[out]datais 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()
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_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]bufferis the pointer to memory buffer for the RX VFIFO.
[in]thresholdis the value of the RX VFIFO threshold.
[in]buffer_lengthis 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]bufferis the pointer to memory buffer for the TX VFIFO.
[in]thresholdis the value of the TX VFIFO threshold.
[in]buffer_lengthis 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.
hal_i2s_status_t hal_i2s_stop_rx_vfifo ( void  )

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

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()
hal_i2s_status_t hal_i2s_tx_write ( uint32_t  data)

This function transmits data to the I2S output link.

Parameters
[in]datais the 32-bit output data to send, 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_tx_sample_count() function to ensure there is enough free space in the TX VFIFO buffer for the write operation.
One sample count queried by hal_i2s_get_tx_sample_count() will be consumed as hal_i2s_tx_write() called once.
See also
hal_i2s_get_tx_sample_count()