HAL I2S How to Use

group I2S_How_To_Use

How to use the I2S HAL module driver

1. Declare a hal_i2s_handle_t handle structure and initialize the I2Sx driver with a SPI HW instance by calling HAL_I2S_Init().

2. Enable the I2Sx clock by calling HAL_I2S_Init() when USE_HAL_I2S_CLK_ENABLE_MODEL > HAL_CLK_ENABLE_NO.

3. Configure the low-level hardware (GPIO, CLOCK, NVIC, etc.):

   • Enable the I2Sx interface clock.

   • I2Sx pins configuration:

     • Enable the clock for the I2Sx GPIOs.

     • Configure these I2S pins as alternate function pull-up.

   • NVIC configuration for interrupt mode:

     • Configure the I2Sx interrupt priority.

     • Enable the I2Sx IRQ in NVIC.

   • DMA configuration for DMA mode:

     • Declare a hal_dma_handle_t handle structure for the transmit or receive Stream/Channel.

     • Enable the DMAx clock.

     • Configure the DMA handle parameters.

     • Configure the DMA Tx or Rx Stream/Channel.

     • Associate the initialized hi2s handle with the DMA Tx or Rx handle.

     • For each DMA channel (Tx and Rx), configure the corresponding NVIC line priority and enable the Tx or Rx Stream/Channel.

4. Set the generic configuration of the I2S: In Master mode with HAL_I2S_MASTER_SetConfig():

   • The mode

   • The standard

   • The data format

   • The audio frequency

   • The clock polarity

   • The bit order In Slave mode with HAL_I2S_SLAVE_SetConfig():

   • The mode

   • The standard

   • The data format

   • The clock polarity

   • The bit order

5. For advanced configuration, use the following functions:

   • HAL_I2S_MASTER_EnableClockOutput() to enable the Master Clock Output feature. When master clock output is enabled, a master clock is generated on the MCK pin at a frequency 256 times higher than the frame synchronization. This master clock often provides a reference clock to an external audio codec.

   • HAL_I2S_EnableWSInversion() to enable the Word Select Inversion feature. When word select inversion is enabled, the default polarity of the WS signal is inverted. In I2S PHILIPS standard, the left channel is transferred when WS is high and the right channel when WS is low. In MSB or LSB justified mode, the left channel is transferred when WS is low and the right channel when WS is high. In PCM mode, the start of frame is indicated by a falling edge.

   • HAL_I2S_MASTER_EnableKeepIOState() to enable the Master Keep IO State feature. When the Master Keep IO State feature is enabled, the peripheral always keeps control of all associated GPIOs to prevent any glitches on the line.

   • HAL_I2S_EnableIOSwap() to enable the IO Swap feature. When the IO Swap is enabled, SDI and SDO lines are swapped. This functionality eases PCB routing or errors.

   • HAL_I2S_SLAVE_EnableLengthDetectionError() to enable the Channel Length Detection error feature. When Channel Length Detection Error is enabled, the frame error coverage is extended, then the I2S expects fixed channel lengths in slave mode.

   • HAL_I2S_LockIOConfig() to enable the Lock of IO configuration feature. When IO lock is enabled, the SPI_CFG2 register content cannot be modified. Configuration functions HAL_I2S_MASTER_SetConfig, HAL_I2S_SLAVE_SetConfig, HAL_I2S_Enable/DisableKeepIOState, HAL_I2S_Enable/DisableIOSwap, and HAL_I2S_SetBitOrder are no longer usable and return HAL_I2S_ERROR_IO_LOCKED.

   • HAL_I2S_SetFifoThreshold() to set the FIFO threshold. FIFO threshold configuration allows an optimization of the FIFO locations. The basic element of the FIFO is the byte. When the data size is fixed to 24 bits, each audio sample takes 3 basic FIFO elements. To reach the FIFO threshold, call the transfer API with a size_sample modulo the FIFO threshold.

   • HAL_I2S_SetData24BitsAlignedRight() to set the data alignment to the right for 24-bit data format.

   • HAL_I2S_SetData24BitsAlignedLeft() to set the data alignment to the left for 24-bit data format.

6. Callback registration: Use the compilation flag USE_HAL_I2S_REGISTER_CALLBACKS to configure driver callbacks dynamically.

Callback name	Default value	Callback registration function
ErrorCallback	HAL_I2S_ErrorCallback()	HAL_I2S_RegisterErrorCallback()
TxCpltCallback	HAL_I2S_TxCpltCallback()	HAL_I2S_RegisterTxCpltCallback()
TxHalfCpltCallback	HAL_I2S_TxHalfCpltCallback()	HAL_I2S_RegisterTxHalfCpltCallback()
RxCpltCallback	HAL_I2S_RxCpltCallback()	HAL_I2S_RegisterRxCpltCallback()
RxHalfCpltCallback	HAL_I2S_RxHalfCpltCallback()	HAL_I2S_RegisterRxHalfCpltCallback()
TxRxCpltCallback	HAL_I2S_TxRxCpltCallback()	HAL_I2S_RegisterTxRxCpltCallback()
TxRxHalfCpltCallback	HAL_I2S_TxRxHalfCpltCallback()	HAL_I2S_RegisterTxRxHalfCpltCallback()
AbortCpltCallback	HAL_I2S_AbortCpltCallback()	HAL_I2S_RegisterAbortCpltCallback()

To unregister a callback, register the default callback via the registration function.

By default, after HAL_I2S_Init() and when the state is HAL_I2S_STATE_INIT, all callbacks are set to the corresponding default weak functions.

Register callbacks when handle global_state is HAL_I2S_STATE_INIT or HAL_I2S_STATE_IDLE.

When the compilation definition USE_HAL_I2S_REGISTER_CALLBACKS is set to 0 or is not defined, the callback registration feature is not available, and weak callbacks are used as shown in the table above.

Note: HAL_I2S_RegisterTxHalfCpltCallback(), HAL_I2S_RegisterRxHalfCpltCallback(), and HAL_I2S_RegisterTxRxHalfCpltCallback() apply only in DMA mode.

1. Acquire/Release the HAL I2S handle:

   • When the compilation flag USE_HAL_MUTEX is set to 1, a multi-thread application can acquire the I2S HAL handle to execute a transmit or receive process or a transmit/receive sequence. Release the I2S HAL handle when the process or sequence ends.

   • HAL Acquire/Release operations are based on the HAL OS abstraction layer (stm32_hal_os.c/.h osal):

     • HAL_I2S_AcquireBus() Acquire the HAL I2S handle.

     • HAL_I2S_ReleaseBus() Release the HAL I2S handle.