Diff: targets/cmsis/TARGET_STM/TARGET_DISCO_F407VG/stm32f4xx_hal_i2s.c

Revision:

242:7074e42da0b2

Parent:

133:d4dda5c437f0

--- a/targets/cmsis/TARGET_STM/TARGET_DISCO_F407VG/stm32f4xx_hal_i2s.c	Thu Jun 26 10:30:09 2014 +0100
+++ b/targets/cmsis/TARGET_STM/TARGET_DISCO_F407VG/stm32f4xx_hal_i2s.c	Fri Jun 27 07:30:09 2014 +0100
@@ -2,8 +2,8 @@
   ******************************************************************************
   * @file    stm32f4xx_hal_i2s.c
   * @author  MCD Application Team
-  * @version V1.0.0
-  * @date    18-February-2014
+  * @version V1.1.0RC2
+  * @date    14-May-2014
   * @brief   I2S HAL module driver.
   *          This file provides firmware functions to manage the following 
   *          functionalities of the Integrated Interchip Sound (I2S) peripheral:
@@ -31,7 +31,7 @@
              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 declared DMA handle structure with the required Tx/Rx parameters.
             (+++) Configure the DMA Tx/Rx Stream.
             (+++) Associate the initilalized DMA handle to the I2S DMA Tx/Rx handle.
             (+++) Configure the priority and enable the NVIC for the transfer complete interrupt on the 
@@ -48,7 +48,7 @@
         (+@) External clock source is configured after setting correctly 
              the define constant EXTERNAL_CLOCK_VALUE in the stm32f4xx_hal_conf.h file. 
              
-   (#) Three mode of operations are available within this driver :     
+   (#) Three operation modes are available within this driver :
   
    *** Polling mode IO operation ***
    =================================
@@ -56,7 +56,7 @@
      (+) 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 ***    
+   *** Interrupt mode IO operation ***
    ===================================
    [..]    
      (+) Send an amount of data in non blocking mode using HAL_I2S_Transmit_IT() 
@@ -68,11 +68,11 @@
      (+) 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                                      
+         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 ***    
+   *** DMA mode IO operation ***
    ==============================
    [..] 
      (+) Send an amount of data in non blocking mode (DMA) using HAL_I2S_Transmit_DMA() 
@@ -84,25 +84,25 @@
      (+) 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                                     
+         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()      
-   
+     (+) 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_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
 
   @endverbatim
@@ -195,7 +195,8 @@
 /**
   * @brief Initializes the I2S according to the specified parameters 
   *         in the I2S_InitTypeDef and create the associated handle.
-  * @param hi2s: I2S handle
+  * @param  hi2s: pointer to a I2S_HandleTypeDef structure that contains
+  *         the configuration information for I2S module
   * @retval HAL status
   */
 HAL_StatusTypeDef HAL_I2S_Init(I2S_HandleTypeDef *hi2s)
@@ -375,7 +376,8 @@
            
 /**
   * @brief DeInitializes the I2S peripheral 
-  * @param hi2s: I2S handle
+  * @param  hi2s: pointer to a I2S_HandleTypeDef structure that contains
+  *         the configuration information for I2S module
   * @retval HAL status
   */
 HAL_StatusTypeDef HAL_I2S_DeInit(I2S_HandleTypeDef *hi2s)
@@ -390,7 +392,8 @@
   
   /* DeInit the low level hardware: GPIO, CLOCK, NVIC... */
   HAL_I2S_MspDeInit(hi2s);
-  
+
+  hi2s->ErrorCode = HAL_I2S_ERROR_NONE;
   hi2s->State = HAL_I2S_STATE_RESET;
 
   /* Release Lock */
@@ -401,7 +404,8 @@
 
 /**
   * @brief I2S MSP Init
-  * @param hi2s: I2S handle
+  * @param  hi2s: pointer to a I2S_HandleTypeDef structure that contains
+  *         the configuration information for I2S module
   * @retval None
   */
  __weak void HAL_I2S_MspInit(I2S_HandleTypeDef *hi2s)
@@ -413,7 +417,8 @@
 
 /**
   * @brief I2S MSP DeInit
-  * @param hi2s: I2S handle
+  * @param  hi2s: pointer to a I2S_HandleTypeDef structure that contains
+  *         the configuration information for I2S module
   * @retval None
   */
  __weak void HAL_I2S_MspDeInit(I2S_HandleTypeDef *hi2s)
@@ -438,7 +443,7 @@
     This subsection provides a set of functions allowing to manage the I2S data 
     transfers.
 
-    (#) There is two mode of transfer:
+    (#) 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.  
@@ -460,7 +465,7 @@
         (++) HAL_I2S_Transmit_DMA()
         (++) HAL_I2S_Receive_DMA()
 
-    (#) A set of Transfer Complete Callbacks are provided in No_Blocking mode:
+    (#) A set of Transfer Complete Callbacks are provided in non Blocking mode:
         (++) HAL_I2S_TxCpltCallback()
         (++) HAL_I2S_RxCpltCallback()
         (++) HAL_I2S_ErrorCallback()
@@ -471,7 +476,8 @@
 
 /**
   * @brief Transmit an amount of data in blocking mode
-  * @param hi2s: I2S handle
+  * @param  hi2s: pointer to a I2S_HandleTypeDef structure that contains
+  *         the configuration information for I2S module
   * @param pData: a 16-bit pointer to data buffer.
   * @param Size: number of data sample to be sent:
   * @note When a 16-bit data frame or a 16-bit data frame extended is selected during the I2S
@@ -550,7 +556,8 @@
 
 /**
   * @brief Receive an amount of data in blocking mode 
-  * @param hi2s: I2S handle
+  * @param  hi2s: pointer to a I2S_HandleTypeDef structure that contains
+  *         the configuration information for I2S module
   * @param pData: a 16-bit pointer to data buffer.
   * @param Size: number of data sample to be sent:
   * @note When a 16-bit data frame or a 16-bit data frame extended is selected during the I2S
@@ -635,7 +642,8 @@
 
 /**
   * @brief Transmit an amount of data in non-blocking mode with Interrupt
-  * @param hi2s: I2S handle
+  * @param  hi2s: pointer to a I2S_HandleTypeDef structure that contains
+  *         the configuration information for I2S module
   * @param pData: a 16-bit pointer to data buffer.
   * @param Size: number of data sample to be sent:
   * @note When a 16-bit data frame or a 16-bit data frame extended is selected during the I2S
@@ -700,7 +708,8 @@
 
 /**
   * @brief Receive an amount of data in non-blocking mode with Interrupt
-  * @param hi2s: I2S handle
+  * @param  hi2s: pointer to a I2S_HandleTypeDef structure that contains
+  *         the configuration information for I2S module
   * @param pData: a 16-bit pointer to the Receive data buffer.
   * @param Size: number of data sample to be sent:
   * @note When a 16-bit data frame or a 16-bit data frame extended is selected during the I2S
@@ -767,7 +776,8 @@
 
 /**
   * @brief Transmit an amount of data in non-blocking mode with DMA
-  * @param hi2s: I2S handle
+  * @param  hi2s: pointer to a I2S_HandleTypeDef structure that contains
+  *         the configuration information for I2S module
   * @param pData: a 16-bit pointer to the Transmit data buffer.
   * @param Size: number of data sample to be sent:
   * @note When a 16-bit data frame or a 16-bit data frame extended is selected during the I2S
@@ -851,7 +861,8 @@
 
 /**
   * @brief Receive an amount of data in non-blocking mode with DMA 
-  * @param hi2s: I2S handle
+  * @param  hi2s: pointer to a I2S_HandleTypeDef structure that contains
+  *         the configuration information for I2S module
   * @param pData: a 16-bit pointer to the Receive data buffer.
   * @param Size: number of data sample to be sent:
   * @note When a 16-bit data frame or a 16-bit data frame extended is selected during the I2S
@@ -942,8 +953,9 @@
 
 /**
   * @brief Pauses the audio stream playing from the Media.
-  * @param hi2s: I2S handle
-  * @retval None
+  * @param  hi2s: pointer to a I2S_HandleTypeDef structure that contains
+  *         the configuration information for I2S module
+  * @retval HAL status
   */
 HAL_StatusTypeDef HAL_I2S_DMAPause(I2S_HandleTypeDef *hi2s)
 {
@@ -986,8 +998,9 @@
 
 /**
   * @brief Resumes the audio stream playing from the Media.
-  * @param hi2s: I2S handle
-  * @retval None
+  * @param  hi2s: pointer to a I2S_HandleTypeDef structure that contains
+  *         the configuration information for I2S module
+  * @retval HAL status
   */
 HAL_StatusTypeDef HAL_I2S_DMAResume(I2S_HandleTypeDef *hi2s)
 {
@@ -1037,8 +1050,9 @@
 
 /**
   * @brief Resumes the audio stream playing from the Media.
-  * @param hi2s: I2S handle
-  * @retval None
+  * @param  hi2s: pointer to a I2S_HandleTypeDef structure that contains
+  *         the configuration information for I2S module
+  * @retval HAL status
   */
 HAL_StatusTypeDef HAL_I2S_DMAStop(I2S_HandleTypeDef *hi2s)
 {
@@ -1086,8 +1100,9 @@
 
 /**
   * @brief  This function handles I2S interrupt request.
-  * @param  hi2s: I2S handle
-  * @retval HAL status
+  * @param  hi2s: pointer to a I2S_HandleTypeDef structure that contains
+  *         the configuration information for I2S module
+  * @retval None
   */
 void HAL_I2S_IRQHandler(I2S_HandleTypeDef *hi2s)
 {  
@@ -1106,7 +1121,7 @@
 
       tmp1 = __HAL_I2S_GET_FLAG(hi2s, I2S_FLAG_OVR);
       tmp2 = __HAL_I2S_GET_IT_SOURCE(hi2s, I2S_IT_ERR);
-      /* I2S Overrun error interrupt occured ---------------------------------*/
+      /* I2S Overrun error interrupt occurred ---------------------------------*/
       if((tmp1 != RESET) && (tmp2 != RESET))
       {
         __HAL_I2S_CLEAR_OVRFLAG(hi2s);
@@ -1126,7 +1141,7 @@
 
       tmp1 = __HAL_I2S_GET_FLAG(hi2s, I2S_FLAG_UDR);
       tmp2 = __HAL_I2S_GET_IT_SOURCE(hi2s, I2S_IT_ERR);
-      /* I2S Underrun error interrupt occured --------------------------------*/
+      /* I2S Underrun error interrupt occurred --------------------------------*/
       if((tmp1 != RESET) && (tmp2 != RESET))
       {
         __HAL_I2S_CLEAR_UDRFLAG(hi2s);
@@ -1158,7 +1173,7 @@
 
       tmp1 = I2SxEXT(hi2s->Instance)->SR & SPI_SR_OVR;
       tmp2 = I2SxEXT(hi2s->Instance)->CR2 & I2S_IT_ERR;
-      /* I2Sext Overrun error interrupt occured ------------------------------*/
+      /* I2Sext Overrun error interrupt occurred ------------------------------*/
       if((tmp1 == SPI_SR_OVR) && (tmp2 == I2S_IT_ERR))
       {
         /* Clear I2Sext OVR Flag */ 
@@ -1184,7 +1199,7 @@
 
       tmp1 = __HAL_I2S_GET_FLAG(hi2s, I2S_FLAG_UDR);
       tmp2 = __HAL_I2S_GET_IT_SOURCE(hi2s, I2S_IT_ERR);
-      /* I2S Underrun error interrupt occured --------------------------------*/
+      /* I2S Underrun error interrupt occurred --------------------------------*/
       if((tmp1 != RESET) && (tmp2 != RESET))
       {
         __HAL_I2S_CLEAR_UDRFLAG(hi2s);
@@ -1211,7 +1226,7 @@
 
       tmp1 = __HAL_I2S_GET_FLAG(hi2s, I2S_FLAG_OVR);
       tmp2 = __HAL_I2S_GET_IT_SOURCE(hi2s, I2S_IT_ERR);
-      /* I2S Overrun error interrupt occured ---------------------------------*/
+      /* I2S Overrun error interrupt occurred ---------------------------------*/
       if((tmp1 != RESET) && (tmp2 != RESET))
       {
         __HAL_I2S_CLEAR_OVRFLAG(hi2s);
@@ -1235,7 +1250,7 @@
 
       tmp1 = I2SxEXT(hi2s->Instance)->SR & SPI_SR_UDR;
       tmp2 = I2SxEXT(hi2s->Instance)->CR2 & I2S_IT_ERR;
-      /* I2Sext Underrun error interrupt occured -----------------------------*/
+      /* I2Sext Underrun error interrupt occurred -----------------------------*/
       if((tmp1 == SPI_SR_UDR) && (tmp2 == I2S_IT_ERR))
       {
         /* Clear I2Sext UDR Flag */ 
@@ -1256,7 +1271,8 @@
 
 /**
   * @brief Tx Transfer Half completed callbacks
-  * @param hi2s: I2S handle
+  * @param  hi2s: pointer to a I2S_HandleTypeDef structure that contains
+  *         the configuration information for I2S module
   * @retval None
   */
  __weak void HAL_I2S_TxHalfCpltCallback(I2S_HandleTypeDef *hi2s)
@@ -1268,7 +1284,8 @@
 
 /**
   * @brief Tx Transfer completed callbacks
-  * @param hi2s: I2S handle
+  * @param  hi2s: pointer to a I2S_HandleTypeDef structure that contains
+  *         the configuration information for I2S module
   * @retval None
   */
  __weak void HAL_I2S_TxCpltCallback(I2S_HandleTypeDef *hi2s)
@@ -1280,7 +1297,8 @@
 
 /**
   * @brief Rx Transfer half completed callbacks
-  * @param hi2s: I2S handle
+  * @param  hi2s: pointer to a I2S_HandleTypeDef structure that contains
+  *         the configuration information for I2S module
   * @retval None
   */
 __weak void HAL_I2S_RxHalfCpltCallback(I2S_HandleTypeDef *hi2s)
@@ -1292,7 +1310,8 @@
 
 /**
   * @brief Rx Transfer completed callbacks
-  * @param hi2s: I2S handle
+  * @param  hi2s: pointer to a I2S_HandleTypeDef structure that contains
+  *         the configuration information for I2S module
   * @retval None
   */
 __weak void HAL_I2S_RxCpltCallback(I2S_HandleTypeDef *hi2s)
@@ -1304,7 +1323,8 @@
 
 /**
   * @brief I2S error callbacks
-  * @param hi2s: I2S handle
+  * @param  hi2s: pointer to a I2S_HandleTypeDef structure that contains
+  *         the configuration information for I2S module
   * @retval None
   */
  __weak void HAL_I2S_ErrorCallback(I2S_HandleTypeDef *hi2s)
@@ -1326,7 +1346,7 @@
                       ##### Peripheral State and Errors functions #####
  ===============================================================================  
     [..]
-    This subsection permit to get in run-time the status of the peripheral 
+    This subsection permits to get in run-time the status of the peripheral 
     and the data flow.
 
 @endverbatim
@@ -1335,7 +1355,8 @@
 
 /**
   * @brief  Return the I2S state
-  * @param  hi2s : I2S handle
+  * @param  hi2s: pointer to a I2S_HandleTypeDef structure that contains
+  *         the configuration information for I2S module
   * @retval HAL state
   */
 HAL_I2S_StateTypeDef HAL_I2S_GetState(I2S_HandleTypeDef *hi2s)
@@ -1345,7 +1366,8 @@
 
 /**
   * @brief  Return the I2S error code
-  * @param  hi2s : I2S handle
+  * @param  hi2s: pointer to a I2S_HandleTypeDef structure that contains
+  *         the configuration information for I2S module
   * @retval I2S Error Code
   */
 HAL_I2S_ErrorTypeDef HAL_I2S_GetError(I2S_HandleTypeDef *hi2s)
@@ -1359,7 +1381,8 @@
 
 /**
   * @brief DMA I2S transmit process complete callback 
-  * @param hdma : DMA handle
+  * @param  hdma: pointer to a DMA_HandleTypeDef structure that contains
+  *                the configuration information for the specified DMA module.
   * @retval None
   */
 void I2S_DMATxCplt(DMA_HandleTypeDef *hdma)
@@ -1396,7 +1419,8 @@
 
 /**
   * @brief DMA I2S transmit process half complete callback 
-  * @param hdma : DMA handle
+  * @param  hdma: pointer to a DMA_HandleTypeDef structure that contains
+  *                the configuration information for the specified DMA module.
   * @retval None
   */
 void I2S_DMATxHalfCplt(DMA_HandleTypeDef *hdma)
@@ -1408,7 +1432,8 @@
 
 /**
   * @brief DMA I2S receive process complete callback 
-  * @param hdma : DMA handle
+  * @param  hdma: pointer to a DMA_HandleTypeDef structure that contains
+  *                the configuration information for the specified DMA module.
   * @retval None
   */
 void I2S_DMARxCplt(DMA_HandleTypeDef *hdma)
@@ -1444,7 +1469,8 @@
 
 /**
   * @brief DMA I2S receive process half complete callback 
-  * @param hdma : DMA handle
+  * @param  hdma: pointer to a DMA_HandleTypeDef structure that contains
+  *                the configuration information for the specified DMA module.
   * @retval None
   */
 void I2S_DMARxHalfCplt(DMA_HandleTypeDef *hdma)
@@ -1456,7 +1482,8 @@
 
 /**
   * @brief DMA I2S communication error callback 
-  * @param hdma : DMA handle
+  * @param  hdma: pointer to a DMA_HandleTypeDef structure that contains
+  *                the configuration information for the specified DMA module.
   * @retval None
   */
 void I2S_DMAError(DMA_HandleTypeDef *hdma)
@@ -1474,7 +1501,8 @@
 
 /**
   * @brief Transmit an amount of data in non-blocking mode with Interrupt
-  * @param hi2s: I2S handle
+  * @param  hi2s: pointer to a I2S_HandleTypeDef structure that contains
+  *         the configuration information for I2S module
   * @retval HAL status
   */
 static HAL_StatusTypeDef I2S_Transmit_IT(I2S_HandleTypeDef *hi2s)
@@ -1517,7 +1545,8 @@
 
 /**
   * @brief Receive an amount of data in non-blocking mode with Interrupt
-  * @param hi2s: I2S handle
+  * @param  hi2s: pointer to a I2S_HandleTypeDef structure that contains
+  *         the configuration information for I2S module
   * @retval HAL status
   */
 static HAL_StatusTypeDef I2S_Receive_IT(I2S_HandleTypeDef *hi2s)
@@ -1568,7 +1597,8 @@
 
 /**
   * @brief This function handles I2S Communication Timeout.
-  * @param hi2s: I2S handle
+  * @param  hi2s: pointer to a I2S_HandleTypeDef structure that contains
+  *         the configuration information for I2S module
   * @param Flag: Flag checked
   * @param State: Value of the flag expected
   * @param Timeout: Duration of the timeout