tool/mbed/mbed-sdk/libraries/mbed/targets/cmsis/TARGET_STM/TARGET_STM32F0/stm32f0xx_hal_i2s.h

   1 /**
   2   ******************************************************************************
   3   * @file    stm32f0xx_hal_i2s.h
   4   * @author  MCD Application Team
   5   * @version V1.2.0
   6   * @date    11-December-2014
   7   * @brief   Header file of I2S HAL module.
   8   ******************************************************************************
   9   * @attention
  10   *
  11   * <h2><center>&copy; COPYRIGHT(c) 2014 STMicroelectronics</center></h2>
  12   *
  13   * Redistribution and use in source and binary forms, with or without modification,
  14   * are permitted provided that the following conditions are met:
  15   *   1. Redistributions of source code must retain the above copyright notice,
  16   *      this list of conditions and the following disclaimer.
  17   *   2. Redistributions in binary form must reproduce the above copyright notice,
  18   *      this list of conditions and the following disclaimer in the documentation
  19   *      and/or other materials provided with the distribution.
  20   *   3. Neither the name of STMicroelectronics nor the names of its contributors
  21   *      may be used to endorse or promote products derived from this software
  22   *      without specific prior written permission.
  23   *
  24   * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
  25   * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  26   * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  27   * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
  28   * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  29   * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
  30   * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
  31   * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  32   * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  33   * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  34   *
  35   ******************************************************************************
  36   */
  37
  38 /* Define to prevent recursive inclusion -------------------------------------*/
  39 #ifndef __STM32F0xx_HAL_I2S_H
  40 #define __STM32F0xx_HAL_I2S_H
  41
  42 #ifdef __cplusplus
  43  extern "C" {
  44 #endif
  45
  46 #if defined(STM32F031x6) || defined(STM32F038xx) || \
  47     defined(STM32F051x8) || defined(STM32F058xx) || \
  48     defined(STM32F071xB) || defined(STM32F072xB) || defined(STM32F078xx) || \
  49     defined(STM32F042x6) || defined(STM32F048xx) || \
  50     defined(STM32F091xC) || defined(STM32F098xx)
  51
  52 /* Includes ------------------------------------------------------------------*/
  53 #include "stm32f0xx_hal_def.h"
  54
  55 /** @addtogroup STM32F0xx_HAL_Driver
  56   * @{
  57   */
  58
  59 /** @addtogroup I2S
  60   * @{
  61   */
  62
  63 /* Exported types ------------------------------------------------------------*/
  64 /** @defgroup I2S_Exported_Types I2S Exported Types
  65   * @{
  66   */
  67
  68 /**
  69   * @brief I2S Init structure definition
  70   */
  71 typedef struct
  72 {
  73   uint32_t Mode;                /*!< Specifies the I2S operating mode.
  74                                      This parameter can be a value of @ref I2S_Mode */
  75
  76   uint32_t Standard;            /*!< Specifies the standard used for the I2S communication.
  77                                      This parameter can be a value of @ref I2S_Standard */
  78
  79   uint32_t DataFormat;          /*!< Specifies the data format for the I2S communication.
  80                                      This parameter can be a value of @ref I2S_Data_Format */
  81
  82   uint32_t MCLKOutput;          /*!< Specifies whether the I2S MCLK output is enabled or not.
  83                                      This parameter can be a value of @ref I2S_MCLK_Output */
  84
  85   uint32_t AudioFreq;           /*!< Specifies the frequency selected for the I2S communication.
  86                                      This parameter can be a value of @ref I2S_Audio_Frequency */
  87
  88   uint32_t CPOL;                /*!< Specifies the idle state of the I2S clock.
  89                                      This parameter can be a value of @ref I2S_Clock_Polarity */
  90 }I2S_InitTypeDef;
  91
  92 /**
  93   * @brief  HAL State structures definition
  94   */
  95 typedef enum
  96 {
  97   HAL_I2S_STATE_RESET      = 0x00,  /*!< I2S not yet initialized or disabled                */
  98   HAL_I2S_STATE_READY      = 0x01,  /*!< I2S initialized and ready for use                  */
  99   HAL_I2S_STATE_BUSY       = 0x02,  /*!< I2S internal process is ongoing                    */
 100   HAL_I2S_STATE_BUSY_TX    = 0x03,  /*!< Data Transmission process is ongoing               */
 101   HAL_I2S_STATE_BUSY_RX    = 0x04,  /*!< Data Reception process is ongoing                  */
 102   HAL_I2S_STATE_PAUSE      = 0x06,  /*!< I2S pause state: used in case of DMA               */
 103   HAL_I2S_STATE_ERROR      = 0x07   /*!< I2S error state                                    */
 104 }HAL_I2S_StateTypeDef;
 105
 106 /**
 107   * @brief I2S handle Structure definition
 108   */
 109 typedef struct
 110 {
 111   SPI_TypeDef                *Instance;    /*!< I2S registers base address */
 112
 113   I2S_InitTypeDef            Init;         /*!< I2S communication parameters */
 114
 115   uint16_t                   *pTxBuffPtr;  /*!< Pointer to I2S Tx transfer buffer */
 116
 117   __IO uint16_t              TxXferSize;   /*!< I2S Tx transfer size */
 118
 119   __IO uint16_t              TxXferCount;  /*!< I2S Tx transfer Counter */
 120
 121   uint16_t                   *pRxBuffPtr;  /*!< Pointer to I2S Rx transfer buffer */
 122
 123   __IO uint16_t              RxXferSize;   /*!< I2S Rx transfer size */
 124
 125   __IO uint16_t              RxXferCount;  /*!< I2S Rx transfer counter
 126                                               (This field is initialized at the
 127                                                same value as transfer size at the
 128                                                beginning of the transfer and
 129                                                decremented when a sample is received.
 130                                                NbSamplesReceived = RxBufferSize-RxBufferCount) */
 131
 132   DMA_HandleTypeDef          *hdmatx;      /*!< I2S Tx DMA handle parameters */
 133
 134   DMA_HandleTypeDef          *hdmarx;      /*!< I2S Rx DMA handle parameters */
 135
 136   __IO HAL_LockTypeDef       Lock;         /*!< I2S locking object */
 137
 138   __IO HAL_I2S_StateTypeDef  State;        /*!< I2S communication state */
 139
 140   __IO uint32_t              ErrorCode;    /*!< I2S Error code
 141                                                 This parameter can be a value of @ref I2S_Error */
 142
 143 }I2S_HandleTypeDef;
 144 /**
 145   * @}
 146   */
 147
 148 /* Exported constants --------------------------------------------------------*/
 149 /** @defgroup I2S_Exported_Constants I2S Exported Constants
 150   * @{
 151   */
 152 /** @defgroup I2S_Error I2S Error
 153   * @{
 154   */
 155 #define HAL_I2S_ERROR_NONE      ((uint32_t)0x00000000)  /*!< No error           */
 156 #define HAL_I2S_ERROR_TIMEOUT   ((uint32_t)0x00000001)  /*!< Timeout error      */
 157 #define HAL_I2S_ERROR_OVR       ((uint32_t)0x00000002)  /*!< OVR error          */
 158 #define HAL_I2S_ERROR_UDR       ((uint32_t)0x00000004)  /*!< UDR error          */
 159 #define HAL_I2S_ERROR_DMA       ((uint32_t)0x00000008)  /*!< DMA transfer error */
 160 #define HAL_I2S_ERROR_UNKNOW    ((uint32_t)0x00000010)  /*!< Unknow Error error */
 161 /**
 162   * @}
 163   */
 164
 165 /** @defgroup I2S_Mode I2S Mode
 166   * @{
 167   */
 168 #define I2S_MODE_SLAVE_TX                ((uint32_t)0x00000000)
 169 #define I2S_MODE_SLAVE_RX                ((uint32_t)0x00000100)
 170 #define I2S_MODE_MASTER_TX               ((uint32_t)0x00000200)
 171 #define I2S_MODE_MASTER_RX               ((uint32_t)0x00000300)
 172
 173 #define IS_I2S_MODE(MODE) (((MODE) == I2S_MODE_SLAVE_TX) || \
 174                            ((MODE) == I2S_MODE_SLAVE_RX) || \
 175                            ((MODE) == I2S_MODE_MASTER_TX)|| \
 176                            ((MODE) == I2S_MODE_MASTER_RX))
 177 /**
 178   * @}
 179   */
 180
 181 /** @defgroup I2S_Standard I2S Standard
 182   * @{
 183   */
 184 #define I2S_STANDARD_PHILIPS             ((uint32_t)0x00000000)
 185 #define I2S_STANDARD_MSB                 ((uint32_t)0x00000010)
 186 #define I2S_STANDARD_LSB                 ((uint32_t)0x00000020)
 187 #define I2S_STANDARD_PCM_SHORT           ((uint32_t)0x00000030)
 188 #define I2S_STANDARD_PCM_LONG            ((uint32_t)0x000000B0)
 189
 190 #define IS_I2S_STANDARD(STANDARD) (((STANDARD) == I2S_STANDARD_PHILIPS) || \
 191                                    ((STANDARD) == I2S_STANDARD_MSB) || \
 192                                    ((STANDARD) == I2S_STANDARD_LSB) || \
 193                                    ((STANDARD) == I2S_STANDARD_PCM_SHORT) || \
 194                                    ((STANDARD) == I2S_STANDARD_PCM_LONG))
 195 /**
 196   * @}
 197   */
 198
 199 /** @defgroup I2S_Data_Format I2S Data Format
 200   * @{
 201   */
 202 #define I2S_DATAFORMAT_16B               ((uint32_t)0x00000000)
 203 #define I2S_DATAFORMAT_16B_EXTENDED      ((uint32_t)0x00000001)
 204 #define I2S_DATAFORMAT_24B               ((uint32_t)0x00000003)
 205 #define I2S_DATAFORMAT_32B               ((uint32_t)0x00000005)
 206
 207 #define IS_I2S_DATA_FORMAT(FORMAT) (((FORMAT) == I2S_DATAFORMAT_16B) || \
 208                                     ((FORMAT) == I2S_DATAFORMAT_16B_EXTENDED) || \
 209                                     ((FORMAT) == I2S_DATAFORMAT_24B) || \
 210                                     ((FORMAT) == I2S_DATAFORMAT_32B))
 211 /**
 212   * @}
 213   */
 214
 215 /** @defgroup I2S_MCLK_Output I2S MCLK Output
 216   * @{
 217   */
 218 #define I2S_MCLKOUTPUT_ENABLE           ((uint32_t)SPI_I2SPR_MCKOE)
 219 #define I2S_MCLKOUTPUT_DISABLE          ((uint32_t)0x00000000)
 220
 221 #define IS_I2S_MCLK_OUTPUT(OUTPUT) (((OUTPUT) == I2S_MCLKOUTPUT_ENABLE) || \
 222                                     ((OUTPUT) == I2S_MCLKOUTPUT_DISABLE))
 223 /**
 224   * @}
 225   */
 226
 227 /** @defgroup I2S_Audio_Frequency I2S Audio Frequency
 228   * @{
 229   */
 230 #define I2S_AUDIOFREQ_192K               ((uint32_t)192000)
 231 #define I2S_AUDIOFREQ_96K                ((uint32_t)96000)
 232 #define I2S_AUDIOFREQ_48K                ((uint32_t)48000)
 233 #define I2S_AUDIOFREQ_44K                ((uint32_t)44100)
 234 #define I2S_AUDIOFREQ_32K                ((uint32_t)32000)
 235 #define I2S_AUDIOFREQ_22K                ((uint32_t)22050)
 236 #define I2S_AUDIOFREQ_16K                ((uint32_t)16000)
 237 #define I2S_AUDIOFREQ_11K                ((uint32_t)11025)
 238 #define I2S_AUDIOFREQ_8K                 ((uint32_t)8000)
 239 #define I2S_AUDIOFREQ_DEFAULT            ((uint32_t)2)
 240
 241 #define IS_I2S_AUDIO_FREQ(FREQ) ((((FREQ) >= I2S_AUDIOFREQ_8K) && \
 242                                  ((FREQ) <= I2S_AUDIOFREQ_192K)) || \
 243                                  ((FREQ) == I2S_AUDIOFREQ_DEFAULT))
 244 /**
 245   * @}
 246   */
 247
 248 /** @defgroup I2S_Clock_Polarity I2S Clock Polarity
 249   * @{
 250   */
 251 #define I2S_CPOL_LOW                    ((uint32_t)0x00000000)
 252 #define I2S_CPOL_HIGH                   ((uint32_t)SPI_I2SCFGR_CKPOL)
 253
 254 #define IS_I2S_CPOL(CPOL) (((CPOL) == I2S_CPOL_LOW) || \
 255                            ((CPOL) == I2S_CPOL_HIGH))
 256 /**
 257   * @}
 258   */
 259
 260 /** @defgroup I2S_Interrupt_configuration_definition I2S Interrupt configuration definition
 261   * @{
 262   */
 263 #define I2S_IT_TXE                      SPI_CR2_TXEIE
 264 #define I2S_IT_RXNE                     SPI_CR2_RXNEIE
 265 #define I2S_IT_ERR                      SPI_CR2_ERRIE
 266 /**
 267   * @}
 268   */
 269
 270 /** @defgroup I2S_Flag_definition I2S Flag definition
 271   * @{
 272   */
 273 #define I2S_FLAG_TXE                    SPI_SR_TXE
 274 #define I2S_FLAG_RXNE                   SPI_SR_RXNE
 275
 276 #define I2S_FLAG_UDR                    SPI_SR_UDR
 277 #define I2S_FLAG_OVR                    SPI_SR_OVR
 278 #define I2S_FLAG_FRE                    SPI_SR_FRE
 279
 280 #define I2S_FLAG_CHSIDE                 SPI_SR_CHSIDE
 281 #define I2S_FLAG_BSY                    SPI_SR_BSY
 282 /**
 283   * @}
 284   */
 285
 286 /**
 287   * @}
 288   */
 289
 290 /* Exported macros -----------------------------------------------------------*/
 291 /** @defgroup I2S_Exported_macros I2S Exported Macros
 292   * @{
 293   */
 294
 295 /** @brief  Reset I2S handle state
 296   * @param  __HANDLE__: I2S handle.
 297   * @retval None
 298   */
 299 #define __HAL_I2S_RESET_HANDLE_STATE(__HANDLE__) ((__HANDLE__)->State = HAL_I2S_STATE_RESET)
 300
 301 /** @brief  Enable or disable the specified SPI peripheral (in I2S mode).
 302   * @param  __HANDLE__: specifies the I2S Handle.
 303   * @retval None
 304   */
 305 #define __HAL_I2S_ENABLE(__HANDLE__) ((__HANDLE__)->Instance->I2SCFGR |= SPI_I2SCFGR_I2SE)
 306 #define __HAL_I2S_DISABLE(__HANDLE__) ((__HANDLE__)->Instance->I2SCFGR &= (uint16_t)(~SPI_I2SCFGR_I2SE))
 307
 308 /** @brief  Enable or disable the specified I2S interrupts.
 309   * @param  __HANDLE__: specifies the I2S Handle.
 310   * @param  __INTERRUPT__: specifies the interrupt source to enable or disable.
 311   *        This parameter can be one of the following values:
 312   *            @arg I2S_IT_TXE: Tx buffer empty interrupt enable
 313   *            @arg I2S_IT_RXNE: RX buffer not empty interrupt enable
 314   *            @arg I2S_IT_ERR: Error interrupt enable
 315   * @retval None
 316   */
 317 #define __HAL_I2S_ENABLE_IT(__HANDLE__, __INTERRUPT__) ((__HANDLE__)->Instance->CR2 |= (__INTERRUPT__))
 318 #define __HAL_I2S_DISABLE_IT(__HANDLE__, __INTERRUPT__) ((__HANDLE__)->Instance->CR2 &= (uint16_t)(~(__INTERRUPT__)))
 319
 320 /** @brief  Checks if the specified I2S interrupt source is enabled or disabled.
 321   * @param  __HANDLE__: specifies the I2S Handle.
 322   *         This parameter can be I2S where x: 1, 2, or 3 to select the I2S peripheral.
 323   * @param  __INTERRUPT__: specifies the I2S interrupt source to check.
 324   *          This parameter can be one of the following values:
 325   *            @arg I2S_IT_TXE: Tx buffer empty interrupt enable
 326   *            @arg I2S_IT_RXNE: RX buffer not empty interrupt enable
 327   *            @arg I2S_IT_ERR: Error interrupt enable
 328   * @retval The new state of __IT__ (TRUE or FALSE).
 329   */
 330 #define __HAL_I2S_GET_IT_SOURCE(__HANDLE__, __INTERRUPT__) ((((__HANDLE__)->Instance->CR2 & (__INTERRUPT__)) == (__INTERRUPT__)) ? SET : RESET)
 331
 332 /** @brief  Checks whether the specified I2S flag is set or not.
 333   * @param  __HANDLE__: specifies the I2S Handle.
 334   * @param  __FLAG__: specifies the flag to check.
 335   *        This parameter can be one of the following values:
 336   *            @arg I2S_FLAG_RXNE: Receive buffer not empty flag
 337   *            @arg I2S_FLAG_TXE: Transmit buffer empty flag
 338   *            @arg I2S_FLAG_UDR: Underrun flag
 339   *            @arg I2S_FLAG_OVR: Overrun flag
 340   *            @arg I2S_FLAG_FRE: Frame error flag
 341   *            @arg I2S_FLAG_CHSIDE: Channel Side flag
 342   *            @arg I2S_FLAG_BSY: Busy flag
 343   * @retval The new state of __FLAG__ (TRUE or FALSE).
 344   */
 345 #define __HAL_I2S_GET_FLAG(__HANDLE__, __FLAG__) ((((__HANDLE__)->Instance->SR) & (__FLAG__)) == (__FLAG__))
 346
 347 /** @brief Clears the I2S OVR pending flag.
 348   * @param  __HANDLE__: specifies the I2S Handle.
 349   * @retval None
 350   */
 351 #define __HAL_I2S_CLEAR_OVRFLAG(__HANDLE__) do{ \
 352                                                __IO uint32_t tmpreg; \
 353                                                tmpreg = (__HANDLE__)->Instance->DR; \
 354                                                tmpreg = (__HANDLE__)->Instance->SR; \
 355                                                UNUSED(tmpreg); \
 356                                               }while(0)
 357 /** @brief Clears the I2S UDR pending flag.
 358   * @param  __HANDLE__: specifies the I2S Handle.
 359   * @retval None
 360   */
 361 #define __HAL_I2S_CLEAR_UDRFLAG(__HANDLE__) do{\
 362                                                __IO uint32_t tmpreg;\
 363                                                tmpreg = ((__HANDLE__)->Instance->SR);\
 364                                                UNUSED(tmpreg); \
 365                                               }while(0)
 366 /**
 367   * @}
 368   */
 369
 370 /* Exported functions --------------------------------------------------------*/
 371 /** @addtogroup I2S_Exported_Functions
 372   * @{
 373   */
 374
 375 /** @addtogroup I2S_Exported_Functions_Group1
 376   * @{
 377   */
 378 /* Initialization/de-initialization functions  **********************************/
 379 HAL_StatusTypeDef HAL_I2S_Init(I2S_HandleTypeDef *hi2s);
 380 HAL_StatusTypeDef HAL_I2S_DeInit (I2S_HandleTypeDef *hi2s);
 381 void HAL_I2S_MspInit(I2S_HandleTypeDef *hi2s);
 382 void HAL_I2S_MspDeInit(I2S_HandleTypeDef *hi2s);
 383 /**
 384   * @}
 385   */
 386
 387 /** @addtogroup I2S_Exported_Functions_Group2
 388   * @{
 389   */
 390 /* I/O operation functions  ***************************************************/
 391  /* Blocking mode: Polling */
 392 HAL_StatusTypeDef HAL_I2S_Transmit(I2S_HandleTypeDef *hi2s, uint16_t *pData, uint16_t Size, uint32_t Timeout);
 393 HAL_StatusTypeDef HAL_I2S_Receive(I2S_HandleTypeDef *hi2s, uint16_t *pData, uint16_t Size, uint32_t Timeout);
 394
 395  /* Non-Blocking mode: Interrupt */
 396 HAL_StatusTypeDef HAL_I2S_Transmit_IT(I2S_HandleTypeDef *hi2s, uint16_t *pData, uint16_t Size);
 397 HAL_StatusTypeDef HAL_I2S_Receive_IT(I2S_HandleTypeDef *hi2s, uint16_t *pData, uint16_t Size);
 398 void HAL_I2S_IRQHandler(I2S_HandleTypeDef *hi2s);
 399
 400 /* Non-Blocking mode: DMA */
 401 HAL_StatusTypeDef HAL_I2S_Transmit_DMA(I2S_HandleTypeDef *hi2s, uint16_t *pData, uint16_t Size);
 402 HAL_StatusTypeDef HAL_I2S_Receive_DMA(I2S_HandleTypeDef *hi2s, uint16_t *pData, uint16_t Size);
 403
 404 HAL_StatusTypeDef HAL_I2S_DMAPause(I2S_HandleTypeDef *hi2s);
 405 HAL_StatusTypeDef HAL_I2S_DMAResume(I2S_HandleTypeDef *hi2s);
 406 HAL_StatusTypeDef HAL_I2S_DMAStop(I2S_HandleTypeDef *hi2s);
 407
 408 /* Callbacks used in non blocking modes (Interrupt and DMA) *******************/
 409 void HAL_I2S_TxHalfCpltCallback(I2S_HandleTypeDef *hi2s);
 410 void HAL_I2S_TxCpltCallback(I2S_HandleTypeDef *hi2s);
 411 void HAL_I2S_RxHalfCpltCallback(I2S_HandleTypeDef *hi2s);
 412 void HAL_I2S_RxCpltCallback(I2S_HandleTypeDef *hi2s);
 413 void HAL_I2S_ErrorCallback(I2S_HandleTypeDef *hi2s);
 414 /**
 415   * @}
 416   */
 417
 418 /** @addtogroup I2S_Exported_Functions_Group3
 419   * @{
 420   */
 421 /* Peripheral Control and State functions  ************************************/
 422 HAL_I2S_StateTypeDef HAL_I2S_GetState(I2S_HandleTypeDef *hi2s);
 423 uint32_t HAL_I2S_GetError(I2S_HandleTypeDef *hi2s);
 424 /**
 425   * @}
 426   */
 427
 428 /**
 429   * @}
 430   */
 431
 432
 433 /**
 434   * @}
 435   */
 436
 437 /**
 438   * @}
 439   */
 440 #endif  /* defined(STM32F031x6) || defined(STM32F038xx) || */
 441         /* defined(STM32F051x8) || defined(STM32F058xx) || */
 442         /* defined(STM32F071xB) || defined(STM32F072xB) || defined(STM32F078xx) ||*/
 443         /* defined(STM32F042x6) || defined(STM32F048xx) || */
 444         /* defined(STM32F091xC) || defined(STM32F098xx) */
 445
 446 #ifdef __cplusplus
 447 }
 448 #endif
 449
 450
 451 #endif /* __STM32F0xx_HAL_I2S_H */
 452
 453 /************************ (C) COPYRIGHT STMicroelectronics *****END OF FILE****/