Functions
IO operation functions
Peripheral Driver » HAL Driver » I2S » Functions

Data transfers functions. More...

Collaboration diagram for IO operation functions:

## Functions
hal_status_t | hal_i2s_transmit (i2s_handle_t *p_i2s, uint16_t *p_data, uint32_t length, uint32_t timeout)
| Transmit an amount of data in blocking mode. More...
hal_status_t | hal_i2s_receive (i2s_handle_t *p_i2s, uint16_t *p_data, uint32_t length, uint32_t timeout)
| Receive an amount of data in blocking mode. More...
hal_status_t | hal_i2s_transmit_receive (i2s_handle_t *p_i2s, uint16_t *p_tx_data, uint16_t *p_rx_data, uint32_t length, uint32_t timeout)
| Transmit and Receive an amount of data in blocking mode. More...
hal_status_t | hal_i2s_transmit_it (i2s_handle_t *p_i2s, uint16_t *p_data, uint32_t length)
| Transmit an amount of data in non-blocking mode with Interrupt. More...
hal_status_t | hal_i2s_receive_it (i2s_handle_t *p_i2s, uint16_t *p_data, uint32_t length)
| Receive an amount of data in non-blocking mode with Interrupt. More...
hal_status_t | hal_i2s_transmit_receive_it (i2s_handle_t *p_i2s, uint16_t *p_tx_data, uint16_t *p_rx_data, uint32_t length)
| Transmit and Receive an amount of data in non-blocking mode with Interrupt. More...
hal_status_t | hal_i2s_transmit_dma (i2s_handle_t *p_i2s, uint16_t *p_data, uint32_t length)
| Transmit an amount of data in non-blocking mode with DMA. More...
hal_status_t | hal_i2s_receive_dma (i2s_handle_t *p_i2s, uint16_t *p_data, uint32_t length)
| Receive an amount of data in non-blocking mode with DMA. More...
hal_status_t | hal_i2s_transmit_receive_dma (i2s_handle_t *p_i2s, uint16_t *p_tx_data, uint16_t *p_rx_data, uint32_t length)
| Transmit and Receive an amount of data in non-blocking mode with DMA. More...
hal_status_t | hal_i2s_transmit_dma_sg_llp (i2s_handle_t *p_i2s, uint16_t *p_data, uint32_t length, dma_sg_llp_config_t *p_sg_llp_config)
| Transmit an amount of data in non-blocking mode with DMA. More...
hal_status_t | hal_i2s_receive_dma_sg_llp (i2s_handle_t *p_i2s, uint16_t *p_data, uint32_t length, dma_sg_llp_config_t *p_sg_llp_config)
| Receive an amount of data in non-blocking mode with DMA. More...
hal_status_t | hal_i2s_transmit_receive_dma_sg_llp (i2s_handle_t *p_i2s, uint16_t *p_tx_data, uint16_t *p_rx_data, uint32_t length, dma_sg_llp_config_t *p_sg_llp_config)
| Transmit and Receive an amount of data in non-blocking mode with DMA. More...
hal_status_t | hal_i2s_start_clock (i2s_handle_t *p_i2s)
| Start the I2S master clock. More...
hal_status_t | hal_i2s_stop_clock (i2s_handle_t *p_i2s)
| Stop the I2S master clock. More...
hal_status_t | hal_i2s_abort (i2s_handle_t *p_i2s)
| Abort ongoing transfer (blocking mode). More...

## Detailed Description

Data transfers functions.

      ==============================================================================
                          ##### IO operation functions #####
     ===============================================================================
     [..]
        This subsection provides a set of functions allowing to manage the I2S
        data transfers.

        [..] The I2S supports master and slave mode:

        (#) There are two modes of transfer:
           (++) Blocking mode: The communication is performed in polling mode.
                The HAL 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 APIs return the HAL status.
                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.
                The hal_i2s_tx_cplt_callback(), hal_i2s_rx_cplt_callback() and hal_i2s_tx_rx_cplt_callback() user callbacks
                will be executed respectively at the end of the transmit or Receive process
                The hal_i2s_error_callback() user callback will be executed when a communication error is detected.

        (#) APIs provided for these 2 transfer modes (Blocking mode or Non blocking mode using either Interrupt or DMA)
            exist for 1-Line (simplex) and 2-Line (full duplex) modes.

## Function Documentation

## ◆ hal_i2s_abort()

hal_status_t hal_i2s_abort | ( | i2s_handle_t * | p_i2s | ) |

Abort ongoing transfer (blocking mode).

Parameters

  [in] | p_i2s | I2S handle.

Note
  This procedure could be used for aborting any ongoing transfer (TX and RX), started in Interrupt or DMA mode. This procedure performs following operations :
  - Disable I2S Interrupts (depending of transfer direction)
  - Disable the DMA transfer in the peripheral register (if enabled)
  - Abort DMA transfer by calling hal_dma_abort (in case of transfer in DMA mode)
  - Set handle State to READY
  This procedure is executed in blocking mode: When exiting function, Abort is considered as completed.

Return values

  HAL_OK | Operation is OK.
  HAL_ERROR | Parameter error or operation not supported.
  HAL_BUSY | Driver is busy.
  HAL_TIMEOUT | Timeout occurred.

## ◆ hal_i2s_receive()

hal_status_t hal_i2s_receive | ( | i2s_handle_t * | p_i2s,
|  | uint16_t * | p_data,
|  | uint32_t | length,
|  | uint32_t | timeout
| ) |  |

Receive an amount of data in blocking mode.

Parameters

  [in] | p_i2s | Pointer to an I2S handle which contains the configuration information for the specified I2S module.
  [out] | p_data | Pointer to data buffer
  [in] | length | Amount of data to be received in halfword, data of a channel. For example, when 32 bytes of data need to be sent in each of the left and right channels, length = 16.
  [in] | timeout | Timeout duration

Return values

  HAL_OK | Operation is OK.
  HAL_ERROR | Parameter error or operation not supported.
  HAL_BUSY | Driver is busy.
  HAL_TIMEOUT | Timeout occurred.

## ◆ hal_i2s_receive_dma()

hal_status_t hal_i2s_receive_dma | ( | i2s_handle_t * | p_i2s,
|  | uint16_t * | p_data,
|  | uint32_t | length
| ) |  |

Receive an amount of data in non-blocking mode with DMA.

Parameters

  [in] | p_i2s | Pointer to an I2S handle which contains the configuration information for the specified I2S module.
  [out] | p_data | Pointer to data buffer
  [in] | length | Amount of data to be sent in halfword, data of a channel, ranging between 1 and 4095. For example, when 32 bytes of data need to be sent in each of the left and right channels, length = 16.

Return values

  HAL_OK | Operation is OK.
  HAL_ERROR | Parameter error or operation not supported.
  HAL_BUSY | Driver is busy.
  HAL_TIMEOUT | Timeout occurred.

## ◆ hal_i2s_receive_dma_sg_llp()

hal_status_t hal_i2s_receive_dma_sg_llp | ( | i2s_handle_t * | p_i2s,
|  | uint16_t * | p_data,
|  | uint32_t | length,
|  | dma_sg_llp_config_t * | p_sg_llp_config
| ) |  |

Receive an amount of data in non-blocking mode with DMA.

Parameters

  [in] | p_i2s | Pointer to an I2S handle which contains the configuration information for the specified I2S module.
  [out] | p_data | Pointer to data buffer
  [in] | length | Amount of data to be sent in halfword, data of a channel, ranging between 1 and 4095. For example, when 32 bytes of data need to be sent in each of the left and right channels, length = 16.
  [in] | p_sg_llp_config | Pointer to the config of source and destination's SG and LLP.

Return values

  HAL_OK | Operation is OK.
  HAL_ERROR | Parameter error or operation not supported.
  HAL_BUSY | Driver is busy.
  HAL_TIMEOUT | Timeout occurred.

## ◆ hal_i2s_receive_it()

hal_status_t hal_i2s_receive_it | ( | i2s_handle_t * | p_i2s,
|  | uint16_t * | p_data,
|  | uint32_t | length
| ) |  |

Receive an amount of data in non-blocking mode with Interrupt.

Parameters

  [in] | p_i2s | Pointer to an I2S handle which contains the configuration information for the specified I2S module.
  [out] | p_data | Pointer to data buffer
  [in] | length | Amount of data to be sent in halfword, data of a channel. For example, when 32 bytes of data need to be sent in each of the left and right channels, length = 16.

Return values

  HAL_OK | Operation is OK.
  HAL_ERROR | Parameter error or operation not supported.
  HAL_BUSY | Driver is busy.
  HAL_TIMEOUT | Timeout occurred.

## ◆ hal_i2s_start_clock()

hal_status_t hal_i2s_start_clock | ( | i2s_handle_t * | p_i2s | ) |

Start the I2S master clock.

Note
  In case of SLAVE mode, this function will not take effect.

Parameters

  [in] | p_i2s | Pointer to an I2S handle which contains the configuration information for the specified I2S module.

Return values

  HAL_OK | Operation is OK.
  HAL_ERROR | Parameter error or operation not supported.
  HAL_BUSY | Driver is busy.
  HAL_TIMEOUT | Timeout occurred.

## ◆ hal_i2s_stop_clock()

hal_status_t hal_i2s_stop_clock | ( | i2s_handle_t * | p_i2s | ) |

Stop the I2S master clock.

Note
  In case of SLAVE mode, this function will not take effect.

Parameters

  [in] | p_i2s | Pointer to an I2S handle which contains the configuration information for the specified I2S module.

Return values

  HAL_OK | Operation is OK.
  HAL_ERROR | Parameter error or operation not supported.
  HAL_BUSY | Driver is busy.
  HAL_TIMEOUT | Timeout occurred.

## ◆ hal_i2s_transmit()

hal_status_t hal_i2s_transmit | ( | i2s_handle_t * | p_i2s,
|  | uint16_t * | p_data,
|  | uint32_t | length,
|  | uint32_t | timeout
| ) |  |

Transmit an amount of data in blocking mode.

Parameters

  [in] | p_i2s | Pointer to an I2S handle which contains the configuration information for the specified I2S module.
  [in] | p_data | Pointer to data buffer
  [in] | length | Amount of data to be sent in halfword, data of a channel. For example, when 32 bytes of data need to be sent in each of the left and right channels, length = 16.
  [in] | timeout | Timeout duration

Return values

  HAL_OK | Operation is OK.
  HAL_ERROR | Parameter error or operation not supported.
  HAL_BUSY | Driver is busy.
  HAL_TIMEOUT | Timeout occurred.

## ◆ hal_i2s_transmit_dma()

hal_status_t hal_i2s_transmit_dma | ( | i2s_handle_t * | p_i2s,
|  | uint16_t * | p_data,
|  | uint32_t | length
| ) |  |

Transmit an amount of data in non-blocking mode with DMA.

Parameters

  [in] | p_i2s | Pointer to an I2S handle which contains the configuration information for the specified I2S module.
  [in] | p_data | Pointer to data buffer
  [in] | length | Amount of data to be sent in halfword, data of a channel, ranging between 1 and 4095. For example, when 32 bytes of data need to be sent in each of the left and right channels, length = 16.

Return values

  HAL_OK | Operation is OK.
  HAL_ERROR | Parameter error or operation not supported.
  HAL_BUSY | Driver is busy.
  HAL_TIMEOUT | Timeout occurred.

## ◆ hal_i2s_transmit_dma_sg_llp()

hal_status_t hal_i2s_transmit_dma_sg_llp | ( | i2s_handle_t * | p_i2s,
|  | uint16_t * | p_data,
|  | uint32_t | length,
|  | dma_sg_llp_config_t * | p_sg_llp_config
| ) |  |

Transmit an amount of data in non-blocking mode with DMA.

Parameters

  [in] | p_i2s | Pointer to an I2S handle which contains the configuration information for the specified I2S module.
  [in] | p_data | Pointer to data buffer
  [in] | length | Amount of data to be sent in halfword, data of a channel, ranging between 1 and 4095. For example, when 32 bytes of data need to be sent in each of the left and right channels, length = 16.
  [in] | p_sg_llp_config | Pointer to the config of source and destination's SG and LLP.

Return values

  HAL_OK | Operation is OK.
  HAL_ERROR | Parameter error or operation not supported.
  HAL_BUSY | Driver is busy.
  HAL_TIMEOUT | Timeout occurred.

## ◆ hal_i2s_transmit_it()

hal_status_t hal_i2s_transmit_it | ( | i2s_handle_t * | p_i2s,
|  | uint16_t * | p_data,
|  | uint32_t | length
| ) |  |

Transmit an amount of data in non-blocking mode with Interrupt.

Parameters

  [in] | p_i2s | Pointer to an I2S handle which contains the configuration information for the specified I2S module.
  [in] | p_data | Pointer to data buffer
  [in] | length | Amount of data to be sent in halfword, data of a channel. For example, when 32 bytes of data need to be sent in each of the left and right channels, length = 16.

Return values

  HAL_OK | Operation is OK.
  HAL_ERROR | Parameter error or operation not supported.
  HAL_BUSY | Driver is busy.
  HAL_TIMEOUT | Timeout occurred.

## ◆ hal_i2s_transmit_receive()

hal_status_t hal_i2s_transmit_receive | ( | i2s_handle_t * | p_i2s,
|  | uint16_t * | p_tx_data,
|  | uint16_t * | p_rx_data,
|  | uint32_t | length,
|  | uint32_t | timeout
| ) |  |

Transmit and Receive an amount of data in blocking mode.

Parameters

  [in] | p_i2s | Pointer to a I2S handle which contains the configuration information for the specified I2S module.
  [in] | p_tx_data | Pointer to transmission data buffer
  [out] | p_rx_data | Pointer to reception data buffer
  [in] | length | Amount of data to be sent and received in bytes
  [in] | timeout | Timeout duration

Return values

  HAL_OK | Operation is OK.
  HAL_ERROR | Parameter error or operation not supported.
  HAL_BUSY | Driver is busy.
  HAL_TIMEOUT | Timeout occurred.

## ◆ hal_i2s_transmit_receive_dma()

hal_status_t hal_i2s_transmit_receive_dma | ( | i2s_handle_t * | p_i2s,
|  | uint16_t * | p_tx_data,
|  | uint16_t * | p_rx_data,
|  | uint32_t | length
| ) |  |

Transmit and Receive an amount of data in non-blocking mode with DMA.

Parameters

  [in] | p_i2s | Pointer to a I2S handle which contains the configuration information for the specified I2S module.
  [in] | p_tx_data | Pointer to transmission data buffer
  [out] | p_rx_data | Pointer to reception data buffer
  [in] | length | Amount of data to be sent in bytes, ranging between 1 and 4095.

Return values

  HAL_OK | Operation is OK.
  HAL_ERROR | Parameter error or operation not supported.
  HAL_BUSY | Driver is busy.
  HAL_TIMEOUT | Timeout occurred.

## ◆ hal_i2s_transmit_receive_dma_sg_llp()

hal_status_t hal_i2s_transmit_receive_dma_sg_llp | ( | i2s_handle_t * | p_i2s,
|  | uint16_t * | p_tx_data,
|  | uint16_t * | p_rx_data,
|  | uint32_t | length,
|  | dma_sg_llp_config_t * | p_sg_llp_config
| ) |  |

Transmit and Receive an amount of data in non-blocking mode with DMA.

Parameters

  [in] | p_i2s | Pointer to a I2S handle which contains the configuration information for the specified I2S module.
  [in] | p_tx_data | Pointer to transmission data buffer
  [out] | p_rx_data | Pointer to reception data buffer
  [in] | length | Amount of data to be sent in bytes, ranging between 1 and 4095.
  [in] | p_sg_llp_config | Pointer to the config of source and destination's SG and LLP.

Return values

  HAL_OK | Operation is OK.
  HAL_ERROR | Parameter error or operation not supported.
  HAL_BUSY | Driver is busy.
  HAL_TIMEOUT | Timeout occurred.

## ◆ hal_i2s_transmit_receive_it()

hal_status_t hal_i2s_transmit_receive_it | ( | i2s_handle_t * | p_i2s,
|  | uint16_t * | p_tx_data,
|  | uint16_t * | p_rx_data,
|  | uint32_t | length
| ) |  |

Transmit and Receive an amount of data in non-blocking mode with Interrupt.

Parameters

  [in] | p_i2s | Pointer to a I2S handle which contains the configuration information for the specified SPI module.
  [in] | p_tx_data | Pointer to transmission data buffer
  [out] | p_rx_data | Pointer to reception data buffer
  [in] | length | Amount of data to be sent and received in bytes

Return values

  HAL_OK | Operation is OK.
  HAL_ERROR | Parameter error or operation not supported.
  HAL_BUSY | Driver is busy.
  HAL_TIMEOUT | Timeout occurred.