HAL I2S Generic Driver

UM1725

uint16_t * pTxBuffPtr

__IO uint16_t TxXferSize

__IO uint16_t TxXferCount

uint16_t * pRxBuffPtr

__IO uint16_t RxXferSize

__IO uint16_t RxXferCount

DMA_HandleTypeDef * hdmatx

DMA_HandleTypeDef * hdmarx

__IO HAL_LockTypeDef Lock

__IO HAL_I2S_StateTypeDef State

__IO uint32_t ErrorCode

Field Documentation

SPI_TypeDef* I2S_HandleTypeDef::Instance

I2S_InitTypeDef I2S_HandleTypeDef::Init

uint16_t* I2S_HandleTypeDef::pTxBuffPtr

__IO uint16_t I2S_HandleTypeDef::TxXferSize

__IO uint16_t I2S_HandleTypeDef::TxXferCount

uint16_t* I2S_HandleTypeDef::pRxBuffPtr

__IO uint16_t I2S_HandleTypeDef::RxXferSize

__IO uint16_t I2S_HandleTypeDef::RxXferCount

DMA_HandleTypeDef* I2S_HandleTypeDef::hdmatx

DMA_HandleTypeDef* I2S_HandleTypeDef::hdmarx

__IO HAL_LockTypeDef I2S_HandleTypeDef::Lock

__IO HAL_I2S_StateTypeDef I2S_HandleTypeDef::State

__IO uint32_t I2S_HandleTypeDef::ErrorCode

32.2I2S Firmware driver API description

32.2.1How to use this driver

The I2S HAL driver can be used as follow:

1.Declare a I2S_HandleTypeDef handle structure.

2.Initialize the I2S low level resources by implement the HAL_I2S_MspInit() API:

a.Enable the SPIx interface clock.

b.I2S pins configuration:

Enable the clock for the I2S GPIOs.

Configure these I2S pins as alternate function pull-up.

c.NVIC configuration if you need to use interrupt process (HAL_I2S_Transmit_IT() and HAL_I2S_Receive_IT() APIs).

Configure the I2Sx interrupt priority.

Enable the NVIC I2S IRQ handle.

d.DMA Configuration if you need to use DMA process (HAL_I2S_Transmit_DMA() and HAL_I2S_Receive_DMA() APIs:

Declare a DMA handle structure for the Tx/Rx stream.

Enable the DMAx interface clock.

Configure the declared DMA handle structure with the required Tx/Rx parameters.

Configure the DMA Tx/Rx Stream.

Associate the initialized DMA handle to the I2S DMA Tx/Rx handle.

420/900

DOCID025834 Rev 2

UM1725

HAL I2S Generic Driver

Configure the priority and enable the NVIC for the transfer complete interrupt on the DMA Tx/Rx Stream.

3.Program the Mode, Standard, Data Format, MCLK Output, Audio frequency and Polarity using HAL_I2S_Init() function. The specific I2S interrupts (Transmission complete interrupt, RXNE interrupt and Error Interrupts) will be managed using the macros __I2S_ENABLE_IT() and __I2S_DISABLE_IT() inside the transmit and receive process. Make sure that either: I2S PLL is configured or External clock source is configured after setting correctly the define constant EXTERNAL_CLOCK_VALUE in the stm32f4xx_hal_conf.h file.

4.Three operation modes are available within this driver :

Polling mode IO operation

Send an amount of data in blocking mode using HAL_I2S_Transmit()

Receive an amount of data in blocking mode using HAL_I2S_Receive()

Interrupt mode IO operation

Send an amount of data in non blocking mode using HAL_I2S_Transmit_IT()

At transmission end of half transfer HAL_I2S_TxHalfCpltCallback is executed and user can add his own code by customization of function pointer HAL_I2S_TxHalfCpltCallback

At transmission end of transfer HAL_I2S_TxCpltCallback is executed and user can add his own code by customization of function pointer HAL_I2S_TxCpltCallback

Receive an amount of data in non blocking mode using HAL_I2S_Receive_IT()

At reception end of half transfer HAL_I2S_RxHalfCpltCallback is executed and user can add his own code by customization of function pointer HAL_I2S_RxHalfCpltCallback

At reception end of transfer HAL_I2S_RxCpltCallback is executed and user can add his own code by customization of function pointer HAL_I2S_RxCpltCallback

In case of transfer Error, HAL_I2S_ErrorCallback() function is executed and user can add his own code by customization of function pointer HAL_I2S_ErrorCallback

DMA mode IO operation

Send an amount of data in non blocking mode (DMA) using HAL_I2S_Transmit_DMA()

At transmission end of half transfer HAL_I2S_TxHalfCpltCallback is executed and user can add his own code by customization of function pointer HAL_I2S_TxHalfCpltCallback

At transmission end of transfer HAL_I2S_TxCpltCallback is executed and user can add his own code by customization of function pointer HAL_I2S_TxCpltCallback

Receive an amount of data in non blocking mode (DMA) using

HAL_I2S_Receive_DMA()

At reception end of half transfer HAL_I2S_RxHalfCpltCallback is executed and user can add his own code by customization of function pointer HAL_I2S_RxHalfCpltCallback

At reception end of transfer HAL_I2S_RxCpltCallback is executed and user can add his own code by customization of function pointer HAL_I2S_RxCpltCallback

In case of transfer Error, HAL_I2S_ErrorCallback() function is executed and user can add his own code by customization of function pointer HAL_I2S_ErrorCallback

DOCID025834 Rev 2

421/900

HAL I2S Generic Driver		UM1725
	Pause the DMA Transfer using HAL_I2S_DMAPause()
	Resume the DMA Transfer using HAL_I2S_DMAResume()
	Stop the DMA Transfer using HAL_I2S_DMAStop()

I2S HAL driver macros list

Below the list of most used macros in USART HAL driver.

__HAL_I2S_ENABLE: Enable the specified SPI peripheral (in I2S mode)

__HAL_I2S_DISABLE: Disable the specified SPI peripheral (in I2S mode)

__HAL_I2S_ENABLE_IT : Enable the specified I2S interrupts

__HAL_I2S_DISABLE_IT : Disable the specified I2S interrupts

__HAL_I2S_GET_FLAG: Check whether the specified I2S flag is set or not

You can refer to the I2S HAL driver header file for more useful macros

32.2.2Initialization and de-initialization functions

This subsection provides a set of functions allowing to initialize and de-initialize the I2Sx peripheral in simplex mode:

User must Implement HAL_I2S_MspInit() function in which he configures all related peripherals resources (CLOCK, GPIO, DMA, IT and NVIC ).

Call the function HAL_I2S_Init() to configure the selected device with the selected configuration:

Mode

Standard

Data Format

MCLK Output

Audio frequency

Polarity

Call the function HAL_I2S_DeInit() to restore the default configuration of the selected I2Sx peripheral.

This section contains the following APIs:

HAL_I2S_Init()

HAL_I2S_DeInit()

HAL_I2S_MspInit()

HAL_I2S_MspDeInit()

32.2.3IO operation functions

This subsection provides a set of functions allowing to manage the I2S data transfers.

1.There are two modes of transfer:

Blocking mode : The communication is performed in the polling mode. The status of all data processing is returned by the same function after finishing transfer.

No-Blocking mode : The communication is performed using Interrupts or DMA. These functions return the status of the transfer startup. The end of the data processing will be indicated through the dedicated I2S IRQ when using Interrupt mode or the DMA IRQ when using DMA mode.

2.Blocking mode functions are :

422/900

DOCID025834 Rev 2

UM1725

HAL I2S Generic Driver

HAL_I2S_Transmit()

HAL_I2S_Receive()

3.No-Blocking mode functions with Interrupt are :

HAL_I2S_Transmit_IT()

HAL_I2S_Receive_IT()

4.No-Blocking mode functions with DMA are :

HAL_I2S_Transmit_DMA()

HAL_I2S_Receive_DMA()

5.A set of Transfer Complete Callbacks are provided in non Blocking mode:

HAL_I2S_TxCpltCallback()

HAL_I2S_RxCpltCallback()

HAL_I2S_ErrorCallback()

This section contains the following APIs:

HAL_I2S_Transmit()

HAL_I2S_Receive()

HAL_I2S_Transmit_IT()

HAL_I2S_Receive_IT()

HAL_I2S_Transmit_DMA()

HAL_I2S_Receive_DMA()

HAL_I2S_DMAPause()

HAL_I2S_DMAResume()

HAL_I2S_DMAStop()

HAL_I2S_IRQHandler()

HAL_I2S_TxHalfCpltCallback()

HAL_I2S_TxCpltCallback()

HAL_I2S_RxHalfCpltCallback()

HAL_I2S_RxCpltCallback()

HAL_I2S_ErrorCallback()

HAL_I2S_GetState()

HAL_I2S_GetError()

32.2.4Peripheral State and Errors functions

This subsection permits to get in run-time the status of the peripheral and the data flow. This section contains the following APIs:

HAL_I2S_GetState()

HAL_I2S_GetError()

32.2.5HAL_I2S_Init

Function Name	HAL_StatusTypeDef HAL_I2S_Init (I2S_HandleTypeDef * hi2s)
Function Description	Initializes the I2S according to the specified parameters in the
	I2S_InitTypeDef and create the associated handle.
Parameters		hi2s: pointer to a I2S_HandleTypeDef structure that contains
		the configuration information for I2S module
Return values		HAL status

32.2.6HAL_I2S_DeInit

Function Name	HAL_StatusTypeDef HAL_I2S_DeInit (I2S_HandleTypeDef *
	DOCID025834 Rev 2	423/900