picovoice_driver: stm32f7xx_hal_i2s.c File Reference

I2S HAL module driver. This file provides firmware functions to manage the following functionalities of the Integrated Interchip Sound (I2S) peripheral: More...

#include "stm32f7xx_hal.h"

Include dependency graph for stm32f7xx_hal_i2s.c:

Go to the source code of this file.

Detailed Description

I2S HAL module driver. This file provides firmware functions to manage the following functionalities of the Integrated Interchip Sound (I2S) peripheral:

Author

MCD Application Team

Initialization and de-initialization functions
IO operation functions

Peripheral State and Errors functions

===============================================================================
                 ##### How to use this driver #####
===============================================================================
[..]
   The I2S HAL driver can be used as follow:

   (#) Declare a I2S_HandleTypeDef handle structure.
   (#) Initialize the I2S low level resources by implement the HAL_I2S_MspInit() API:
       (##) Enable the SPIx interface clock.
       (##) I2S pins configuration:
           (+++) Enable the clock for the I2S GPIOs.
           (+++) Configure these I2S pins as alternate function pull-up.
       (##) 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.
       (##) 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/Channel.
           (+++) Enable the DMAx interface clock.
           (+++) Configure the declared DMA handle structure with the required Tx/Rx parameters.
           (+++) Configure the DMA Tx/Rx Stream/Channel.
           (+++) Associate the initialized DMA handle to the I2S DMA Tx/Rx handle.
           (+++) Configure the priority and enable the NVIC for the transfer complete interrupt on the
                 DMA Tx/Rx Stream/Channel.

  (#) 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
      __HAL_I2S_ENABLE_IT() and __HAL_I2S_DISABLE_IT() inside the transmit and receive process.
  -@- Make sure that either:
       (+@) I2S clock is configured based on SYSCLK or
       (+@) External clock source is configured after setting correctly
            the define constant EXTERNAL_CLOCK_VALUE in the stm32f7xx_hal_conf.h file.

   (#) Three mode of operations 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
    (+) 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 I2S 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

  *** I2S HAL driver macros list ***
  ===================================
  [..]
      Callback registration:

     (#) The compilation flag USE_HAL_I2S_REGISTER_CALLBACKS when set to 1U
         allows the user to configure dynamically the driver callbacks.
         Use Functions HAL_I2S_RegisterCallback() to register an interrupt callback.

         Function HAL_I2S_RegisterCallback() allows to register following callbacks:
           (+) TxCpltCallback        : I2S Tx Completed callback
           (+) RxCpltCallback        : I2S Rx Completed callback
           (+) TxHalfCpltCallback    : I2S Tx Half Completed callback
           (+) RxHalfCpltCallback    : I2S Rx Half Completed callback
           (+) ErrorCallback         : I2S Error callback
           (+) MspInitCallback       : I2S Msp Init callback
           (+) MspDeInitCallback     : I2S Msp DeInit callback
         This function takes as parameters the HAL peripheral handle, the Callback ID
         and a pointer to the user callback function.


     (#) Use function HAL_I2S_UnRegisterCallback to reset a callback to the default
         weak function.
         HAL_I2S_UnRegisterCallback takes as parameters the HAL peripheral handle,
         and the Callback ID.
         This function allows to reset following callbacks:
           (+) TxCpltCallback        : I2S Tx Completed callback
           (+) RxCpltCallback        : I2S Rx Completed callback
           (+) TxHalfCpltCallback    : I2S Tx Half Completed callback
           (+) RxHalfCpltCallback    : I2S Rx Half Completed callback
           (+) ErrorCallback         : I2S Error callback
           (+) MspInitCallback       : I2S Msp Init callback
           (+) MspDeInitCallback     : I2S Msp DeInit callback

      By default, after the HAL_I2S_Init() and when the state is HAL_I2S_STATE_RESET
      all callbacks are set to the corresponding weak functions:
      examples HAL_I2S_MasterTxCpltCallback(), HAL_I2S_MasterRxCpltCallback().
      Exception done for MspInit and MspDeInit functions that are
      reset to the legacy weak functions in the HAL_I2S_Init()/ HAL_I2S_DeInit() only when
      these callbacks are null (not registered beforehand).
      If MspInit or MspDeInit are not null, the HAL_I2S_Init()/ HAL_I2S_DeInit()
      keep and use the user MspInit/MspDeInit callbacks (registered beforehand) whatever the state.

      Callbacks can be registered/unregistered in HAL_I2S_STATE_READY state only.
      Exception done MspInit/MspDeInit functions that can be registered/unregistered
      in HAL_I2S_STATE_READY or HAL_I2S_STATE_RESET state,
      thus registered (user) MspInit/DeInit callbacks can be used during the Init/DeInit.
      Then, the user first registers the MspInit/MspDeInit user callbacks
      using HAL_I2S_RegisterCallback() before calling HAL_I2S_DeInit()
      or HAL_I2S_Init() function.

      When The compilation define USE_HAL_I2S_REGISTER_CALLBACKS is set to 0 or
      not defined, the callback registering feature is not available
      and weak (surcharged) callbacks are used.

Attention

This software component is licensed by ST under BSD 3-Clause license, the "License"; You may not use this file except in compliance with the License. You may obtain a copy of the License at: opensource.org/licenses/BSD-3-Clause

Definition in file stm32f7xx_hal_i2s.c.

Detailed Description

© Copyright (c) 2017 STMicroelectronics. All rights reserved.