1 /** 2 **************************************************************************************** 3 * 4 * @file gr55xx_hal_i2s.h 5 * @author BLE Driver Team 6 * @brief Header file containing functions prototypes of I2S HAL library. 7 * 8 **************************************************************************************** 9 * @attention 10 #####Copyright (c) 2019 GOODIX 11 All rights reserved. 12 13 Redistribution and use in source and binary forms, with or without 14 modification, are permitted provided that the following conditions are met: 15 * Redistributions of source code must retain the above copyright 16 notice, this list of conditions and the following disclaimer. 17 * Redistributions in binary form must reproduce the above copyright 18 notice, this list of conditions and the following disclaimer in the 19 documentation and/or other materials provided with the distribution. 20 * Neither the name of GOODIX nor the names of its contributors may be used 21 to endorse or promote products derived from this software without 22 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 27 ARE DISCLAIMED. IN NO EVENT SHALL COPYRIGHT HOLDERS AND CONTRIBUTORS BE 28 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 29 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 30 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 31 INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 32 CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 33 ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 34 POSSIBILITY OF SUCH DAMAGE. 35 **************************************************************************************** 36 */ 37 38 /** @addtogroup PERIPHERAL Peripheral Driver 39 * @{ 40 */ 41 42 /** @addtogroup HAL_DRIVER HAL Driver 43 * @{ 44 */ 45 46 /** @defgroup HAL_I2S I2S 47 * @brief I2S HAL module driver. 48 * @{ 49 */ 50 51 /* Define to prevent recursive inclusion -------------------------------------*/ 52 #ifndef __GR55xx_HAL_I2S_H__ 53 #define __GR55xx_HAL_I2S_H__ 54 55 /* Includes ------------------------------------------------------------------*/ 56 #include "gr55xx_ll_i2s.h" 57 #include "gr55xx_hal_def.h" 58 59 #ifdef __cplusplus 60 extern "C" { 61 #endif 62 63 /* Exported types ------------------------------------------------------------*/ 64 /** @addtogroup HAL_I2S_ENUMERATIONS Enumerations 65 * @{ 66 */ 67 68 /** @defgroup HAL_I2S_state HAL I2S state 69 * @{ 70 */ 71 72 /** 73 * @brief HAL I2S State Enumerations definition 74 */ 75 typedef enum { 76 HAL_I2S_STATE_RESET = 0x00, /**< Peripheral not initialized */ 77 HAL_I2S_STATE_READY = 0x01, /**< Peripheral initialized and ready for use */ 78 HAL_I2S_STATE_BUSY = 0x02, /**< An internal process is ongoing */ 79 HAL_I2S_STATE_BUSY_TX = 0x12, /**< Data Transmission process is ongoing */ 80 HAL_I2S_STATE_BUSY_RX = 0x22, /**< Data Reception process is ongoing */ 81 HAL_I2S_STATE_BUSY_TX_RX = 0x32, /**< Data Transmission and Reception process is ongoing */ 82 HAL_I2S_STATE_ABORT = 0x08, /**< Peripheral with abort request ongoing */ 83 HAL_I2S_STATE_ERROR = 0x04 /**< Peripheral in error */ 84 } hal_i2s_state_t; 85 86 /** @} */ 87 88 /** @} */ 89 90 /** @addtogroup HAL_I2S_STRUCTURES Structures 91 * @{ 92 */ 93 94 /** @defgroup I2S_Configuration I2S Configuration 95 * @{ 96 */ 97 98 /** 99 * @brief I2S init Structure definition 100 */ 101 typedef struct _i2s_init { 102 uint32_t data_size; /**< Specifies the data size for I2S communication. 103 This parameter can be a value of @ref I2S_Data_Size */ 104 105 uint32_t clock_source; /**< Specifies the source of the I2S clock. 106 This parameter can be a value of @ref I2S_Clock_Source */ 107 108 uint32_t audio_freq; /**< Specifies the frequency selected for the I2S communication. 109 @note The communication clock is derived from the master 110 clock. The slave clock does not need to be set. */ 111 #if I2S_CHANNEL_NUM > 1 112 uint32_t channel_active; /**< Specifies the active channels for I2S communication. 113 This parameter can be one or more value of @ref I2S_Channel */ 114 #endif 115 } i2s_init_t; 116 /** @} */ 117 118 /** @defgroup I2S_handle I2S handle 119 * @{ 120 */ 121 122 /** 123 * @brief I2S handle Structure definition 124 */ 125 typedef struct _i2s_handle { 126 i2s_regs_t *p_instance; /**< I2S registers base address */ 127 128 i2s_init_t init; /**< I2S communication parameters */ 129 130 uint16_t *p_tx_buffer; /**< Pointer to I2S TX transfer Buffer */ 131 132 __IO uint32_t tx_xfer_size; /**< I2S TX Transfer size */ 133 134 __IO uint32_t tx_xfer_count; /**< I2S TX Transfer Counter */ 135 136 uint16_t *p_rx_buffer; /**< Pointer to I2S RX transfer Buffer */ 137 138 __IO uint32_t rx_xfer_size; /**< I2S RX Transfer size */ 139 140 __IO uint32_t rx_xfer_count; /**< I2S RX Transfer Counter */ 141 142 void (*write_fifo)(struct _i2s_handle *p_i2s); /**< Pointer to I2S Tx transfer FIFO write function */ 143 144 void (*read_fifo)(struct _i2s_handle *p_i2s); /**< Pointer to I2S Rx transfer FIFO read function */ 145 146 dma_handle_t *p_dmatx; /**< I2S TX DMA Handle parameters */ 147 148 dma_handle_t *p_dmarx; /**< I2S RX DMA Handle parameters */ 149 150 __IO hal_lock_t lock; /**< Locking object */ 151 152 __IO hal_i2s_state_t state; /**< I2S communication state */ 153 154 __IO uint32_t error_code; /**< I2S Error code */ 155 156 uint32_t timeout; /**< Timeout for the I2S memory access */ 157 158 uint32_t retention[7]; /**< I2S important register information. */ 159 } i2s_handle_t; 160 /** @} */ 161 162 /** @} */ 163 164 /** @addtogroup HAL_I2S_CALLBACK_STRUCTURES Callback Structures 165 * @{ 166 */ 167 168 /** @defgroup HAL_I2S_Callback Callback 169 * @{ 170 */ 171 172 /** 173 * @brief HAL_I2S Callback function definition 174 */ 175 176 typedef struct _hal_i2s_callback { 177 void (*i2s_msp_init)(i2s_handle_t *p_i2s); /**< I2S init MSP callback */ 178 void (*i2s_msp_deinit)(i2s_handle_t *p_i2s); /**< I2S de-init MSP callback */ 179 void (*i2s_error_callback)(i2s_handle_t *p_i2s); /**< I2S error callback */ 180 void (*i2s_rx_cplt_callback)(i2s_handle_t *p_i2s); /**< I2S rx transfer completed callback */ 181 void (*i2s_tx_cplt_callback)(i2s_handle_t *p_i2s); /**< I2S tx transfer completed callbac */ 182 void (*i2s_tx_rx_cplt_callback)(i2s_handle_t *p_i2s); /**< I2S tx/rx transfer completed callback */ 183 } hal_i2s_callback_t; 184 185 /** @} */ 186 187 /** @} */ 188 189 /** 190 * @defgroup HAL_I2S_MACRO Defines 191 * @{ 192 */ 193 194 /* Exported constants --------------------------------------------------------*/ 195 /** @defgroup I2S_Exported_Constants I2S Exported Constants 196 * @{ 197 */ 198 199 /** @defgroup I2S_Direction I2S Direction 200 * @{ 201 */ 202 #define I2S_DIRECTION_FULL_DUPLEX LL_I2S_FULL_DUPLEX /**< Full Duplex: Transmit & Receive */ 203 #define I2S_DIRECTION_SIMPLEX_TX LL_I2S_SIMPLEX_TX /**< Simplex TX: Transmit only */ 204 #define I2S_DIRECTION_SIMPLEX_RX LL_I2S_SIMPLEX_RX /**< Simplex RX: Receive only */ 205 /** @} */ 206 207 /** @defgroup I2S_Error_Code I2S Error Code 208 * @{ 209 */ 210 #define HAL_I2S_ERROR_NONE ((uint32_t)0x00000000) /**< No error */ 211 #define HAL_I2S_ERROR_TIMEOUT ((uint32_t)0x00000001) /**< Timeout error */ 212 #define HAL_I2S_ERROR_TRANSFER ((uint32_t)0x00000002) /**< Transfer error */ 213 #define HAL_I2S_ERROR_DMA ((uint32_t)0x00000004) /**< DMA transfer error */ 214 #define HAL_I2S_ERROR_INVALID_PARAM ((uint32_t)0x00000008) /**< Invalid parameters error */ 215 /** @} */ 216 217 /** @defgroup I2S_Data_Size I2S Data Size 218 * @{ 219 */ 220 #define I2S_DATASIZE_12BIT LL_I2S_DATASIZE_12BIT /**< 12-bit serial data transfer */ 221 #define I2S_DATASIZE_16BIT LL_I2S_DATASIZE_16BIT /**< 16-bit serial data transfer */ 222 #define I2S_DATASIZE_20BIT LL_I2S_DATASIZE_20BIT /**< 20-bit serial data transfer */ 223 #define I2S_DATASIZE_24BIT LL_I2S_DATASIZE_24BIT /**< 24-bit serial data transfer */ 224 #define I2S_DATASIZE_32BIT LL_I2S_DATASIZE_32BIT /**< 32-bit serial data transfer */ 225 /** @} */ 226 227 /** @defgroup I2S_Clock_Source I2S Clock Source 228 * @{ 229 */ 230 #define I2S_CLOCK_SRC_96M LL_I2S_CLOCK_SRC_96M /**< Inactive state of SCLK is low */ 231 #define I2S_CLOCK_SRC_32M LL_I2S_CLOCK_SRC_32M /**< Inactive state of SCLK is high */ 232 /** @} */ 233 234 /** @defgroup I2S_FIFO_LEVEL_MAX I2S FIFO Level Max 235 * @{ 236 */ 237 #define I2S_TX_FIFO_LEVEL_MAX 16 /**< I2S TX FIFO Level Max Value */ 238 #define I2S_RX_FIFO_LEVEL_MAX 16 /**< I2S RX FIFO Level Max Value */ 239 /** @} */ 240 241 /** @defgroup I2S_Flags_definition I2S Flags Definition 242 * @{ 243 */ 244 #define I2S_FLAG_TXFO LL_I2S_STATUS_TXFO /**< TX FIFO write overflow flag */ 245 #define I2S_FLAG_TXFE LL_I2S_STATUS_TXFE /**< TX FIFO empty trigger flag */ 246 #define I2S_FLAG_RXFO LL_I2S_STATUS_RXFO /**< RX FIFO receive overflow flag */ 247 #define I2S_FLAG_RXDA LL_I2S_STATUS_RXDA /**< RX FIFO data available flag */ 248 /** @} */ 249 250 /** @defgroup I2S_Interrupt_definition I2S Interrupt Definition 251 * @{ 252 */ 253 #define I2S_IT_TXFO LL_I2S_INT_TXFO /**< TX FIFO write overflow interrupt */ 254 #define I2S_IT_TXFE LL_I2S_INT_TXFE /**< TX FIFO empty trigger interrupt */ 255 #define I2S_IT_RXFO LL_I2S_INT_RXFO /**< RX FIFO receive overflow interrupt */ 256 #define I2S_IT_RXDA LL_I2S_INT_RXDA /**< RX FIFO data available interrupt */ 257 /** @} */ 258 259 /** @defgroup I2S_Timeout_definition I2S Timeout_definition 260 * @{ 261 */ 262 #define HAL_I2S_TIMEOUT_DEFAULT_VALUE ((uint32_t)5000) /**< 5s */ 263 /** @} */ 264 265 /** @} */ 266 267 /* Exported macro ------------------------------------------------------------*/ 268 /** @defgroup I2S_Exported_Macros I2S Exported Macros 269 * @{ 270 */ 271 272 /** @brief Reset I2S handle states. 273 * @param __HANDLE__ I2S handle. 274 * @retval None 275 */ 276 #define __HAL_I2S_RESET_HANDLE_STATE(__HANDLE__) ((__HANDLE__)->state = HAL_I2S_STATE_RESET) 277 278 /** @brief Enable the specified I2S peripheral. 279 * @param __HANDLE__ Specifies the I2S Handle. 280 * @retval None 281 */ 282 #define __HAL_I2S_ENABLE(__HANDLE__) SET_BITS((__HANDLE__)->p_instance->ENABLE, I2S_ENABLE_EN) 283 284 /** @brief Disable the specified I2S peripheral. 285 * @param __HANDLE__ Specifies the I2S Handle. 286 * @retval None 287 */ 288 #define __HAL_I2S_DISABLE(__HANDLE__) CLEAR_BITS((__HANDLE__)->p_instance->ENABLE, I2S_ENABLE_EN) 289 290 /** @brief Enable the specified I2S clock. 291 * @param __HANDLE__ Specifies the I2S Handle. 292 * @retval None 293 */ 294 #define __HAL_I2S_ENABLE_CLOCK(__HANDLE__) SET_BITS((__HANDLE__)->p_instance->CLKEN, I2S_CLKEN_EN) 295 296 /** @brief Disable the specified I2S clock. 297 * @param __HANDLE__ Specifies the I2S Handle. 298 * @retval None 299 */ 300 #define __HAL_I2S_DISABLE_CLOCK(__HANDLE__) CLEAR_BITS((__HANDLE__)->p_instance->CLKEN, I2S_CLKEN_EN) 301 302 /** @brief Enable the specified I2S transmitter block. 303 * @param __HANDLE__ Specifies the I2S Handle. 304 * @retval None 305 */ 306 #define __HAL_I2S_ENABLE_TX_BLOCK(__HANDLE__) ll_i2s_enable_txblock((__HANDLE__)->p_instance) 307 308 /** @brief Disable the specified I2S transmitter block. 309 * @param __HANDLE__ Specifies the I2S Handle. 310 * @retval None 311 */ 312 #define __HAL_I2S_DISABLE_TX_BLOCK(__HANDLE__) ll_i2s_disable_txblock((__HANDLE__)->p_instance) 313 314 /** @brief Enable the specified I2S receiver block. 315 * @param __HANDLE__ Specifies the I2S Handle. 316 * @retval None 317 */ 318 #define __HAL_I2S_ENABLE_RX_BLOCK(__HANDLE__) ll_i2s_enable_rxblock((__HANDLE__)->p_instance) 319 320 /** @brief Disable the specified I2S receiver block. 321 * @param __HANDLE__ Specifies the I2S Handle. 322 * @retval None 323 */ 324 #define __HAL_I2S_DISABLE_RX_BLOCK(__HANDLE__) ll_i2s_disable_rxblock((__HANDLE__)->p_instance) 325 326 /** @brief Enable the specified I2S transmitter channel. 327 * @param __HANDLE__ Specifies the I2S Handle. 328 * @param __CH__ Specifies the I2S channel. 329 * @retval None 330 */ 331 #define __HAL_I2S_ENABLE_TX_CHANNEL(__HANDLE__, __CH__) ll_i2s_enable_tx((__HANDLE__)->p_instance, (__CH__)) 332 333 /** @brief Disable the specified I2S transmitter channel. 334 * @param __HANDLE__ Specifies the I2S Handle. 335 * @param __CH__ Specifies the I2S channel. 336 * @retval None 337 */ 338 #define __HAL_I2S_DISABLE_TX_CHANNEL(__HANDLE__, __CH__) ll_i2s_disable_tx((__HANDLE__)->p_instance, (__CH__)) 339 340 /** @brief Enable the specified I2S receiver channel. 341 * @param __HANDLE__ Specifies the I2S Handle. 342 * @param __CH__ Specifies the I2S channel. 343 * @retval None 344 */ 345 #define __HAL_I2S_ENABLE_RX_CHANNEL(__HANDLE__, __CH__) ll_i2s_enable_rx((__HANDLE__)->p_instance, (__CH__)) 346 347 /** @brief Disable the specified I2S receiver channel. 348 * @param __HANDLE__ Specifies the I2S Handle. 349 * @param __CH__ Specifies the I2S channel. 350 * @retval None 351 */ 352 #define __HAL_I2S_DISABLE_RX_CHANNEL(__HANDLE__, __CH__) ll_i2s_disable_rx((__HANDLE__)->p_instance, (__CH__)) 353 354 /** @brief Flush the I2S transmitter FIFO. 355 * @param __HANDLE__ Specifies the I2S Handle. 356 * @retval None 357 */ 358 #define __HAL_I2S_FLUSH_TX_FIFO(__HANDLE__) ll_i2s_clr_txfifo_all((__HANDLE__)->p_instance) 359 360 /** @brief Flush the I2S receiver FIFO. 361 * @param __HANDLE__ Specifies the I2S Handle. 362 * @retval None 363 */ 364 #define __HAL_I2S_FLUSH_RX_FIFO(__HANDLE__) ll_i2s_clr_rxfifo_all((__HANDLE__)->p_instance) 365 366 /** @brief Enable the I2S DMA Request. 367 * @param __HANDLE__ Specifies the I2S Handle. 368 * @retval None 369 */ 370 #define __HAL_I2S_ENABLE_DMA(__HANDLE__) ll_i2s_enable_dma((__HANDLE__)->p_instance) 371 372 /** @brief Disable the I2S DMA Request. 373 * @param __HANDLE__ Specifies the I2S Handle. 374 * @retval None 375 */ 376 #define __HAL_I2S_DISABLE_DMA(__HANDLE__) ll_i2s_disable_dma((__HANDLE__)->p_instance) 377 378 /** @brief Reset the I2S TX DMA request to the lowest enabled channel. 379 * @param __HANDLE__ Specifies the I2S Handle. 380 * @retval None 381 */ 382 #define __HAL_I2S_RESET_TXDMA(__HANDLE__) WRITE_REG((__HANDLE__)->p_instance->TXDMA_RST, I2S_TXDMA_RST) 383 384 /** @brief Reset the I2S RX DMA request to the lowest enabled channel. 385 * @param __HANDLE__ Specifies the I2S Handle. 386 * @retval None 387 */ 388 #define __HAL_I2S_RESET_RXDMA(__HANDLE__) WRITE_REG((__HANDLE__)->p_instance->RXDMA_RST, I2S_RXDMA_RST) 389 390 /** @brief Enable the specified I2S interrupts. 391 * @param __HANDLE__ Specifies the I2S Handle. 392 * @param __INTERRUPT__ Specifies the interrupt source to enable. 393 * This parameter can be one of the following values: 394 * @arg @ref I2S_IT_TXFO TX FIFO write overflow interrupt 395 * @arg @ref I2S_IT_TXFE TX FIFO empty trigger interrupt 396 * @arg @ref I2S_IT_RXFO RX FIFO receive overflow interrupt 397 * @arg @ref I2S_IT_RXDA RX FIFO data available interrupt 398 * @retval None 399 */ 400 #define __HAL_I2S_ENABLE_IT(__HANDLE__, __INTERRUPT__) \ 401 CLEAR_BITS((__HANDLE__)->p_instance->I2S_CHANNEL[0].INTMASK, (__INTERRUPT__)) 402 403 /** @brief Disable the specified I2S interrupts. 404 * @param __HANDLE__ Specifies the I2S handle. 405 * @param __INTERRUPT__ Specifies the interrupt source to disable. 406 * This parameter can be one of the following values: 407 * @arg @ref I2S_IT_TXFO TX FIFO write overflow interrupt 408 * @arg @ref I2S_IT_TXFE TX FIFO empty trigger interrupt 409 * @arg @ref I2S_IT_RXFO RX FIFO receive overflow interrupt 410 * @arg @ref I2S_IT_RXDA RX FIFO data available interrupt 411 * @retval None 412 */ 413 #define __HAL_I2S_DISABLE_IT(__HANDLE__, __INTERRUPT__) \ 414 SET_BITS((__HANDLE__)->p_instance->I2S_CHANNEL[0].INTMASK, (__INTERRUPT__)) 415 416 /** @brief Check whether the specified I2S flag is set or not. 417 * @param __HANDLE__ Specifies the I2S Handle. 418 * @param __FLAG__ Specifies the flag to check. 419 * This parameter can be one of the following values: 420 * @arg @ref I2S_FLAG_TXFO TX FIFO write overflow flag 421 * @arg @ref I2S_FLAG_TXFE TX FIFO empty trigger flag 422 * @arg @ref I2S_FLAG_RXFO RX FIFO receive overflow flag 423 * @arg @ref I2S_FLAG_RXDA RX FIFO data available flag 424 * @retval The new state of __FLAG__ (TRUE or FALSE). 425 */ 426 #define __HAL_I2S_GET_FLAG(__HANDLE__, __FLAG__) \ 427 ((READ_BITS((__HANDLE__)->p_instance->I2S_CHANNEL[0].INTSTAT, (__FLAG__)) != 0) ? SET : RESET) 428 429 /** @brief Clear the specified I2S flag. 430 * @param __HANDLE__ Specifies the I2S Handle. 431 * @param __FLAG__ Specifies the flag to check. 432 * This parameter can be one of the following values: 433 * @arg @ref I2S_FLAG_TXFO TX FIFO write overflow flag 434 * @arg @ref I2S_FLAG_RXFO RX FIFO receive overflow flag 435 * @retval None 436 */ 437 #define __HAL_I2S_CLEAR_FLAG(__HANDLE__, __FLAG__) \ 438 do { \ 439 if ((__FLAG__) & I2S_FLAG_RXFO) \ 440 { \ 441 READ_BITS((__HANDLE__)->p_instance->I2S_CHANNEL[0].RXOVR, I2S_RXOVR_RXCHO); \ 442 } \ 443 if ((__FLAG__) & I2S_FLAG_TXFO) \ 444 { \ 445 READ_BITS((__HANDLE__)->p_instance->I2S_CHANNEL[0].TXOVR, I2S_TXOVR_TXCHO); \ 446 } \ 447 } while (0) 448 449 /** @} */ 450 451 /* Private macros ------------------------------------------------------------*/ 452 /** @defgroup I2S_Private_Macro I2S Private Macros 453 * @{ 454 */ 455 456 /** @brief Check if I2S Direction Mode is valid. 457 * @param __MODE__ I2S Direction Mode. 458 * @retval SET (__MODE__ is valid) or RESET (__MODE__ is invalid) 459 */ 460 #define IS_I2S_DIRECTION(__MODE__) (((__MODE__) == I2S_DIRECTION_FULL_DUPLEX) || \ 461 ((__MODE__) == I2S_DIRECTION_SIMPLEX_TX) || \ 462 ((__MODE__) == I2S_DIRECTION_SIMPLEX_RX)) 463 464 /** @brief Check if I2S Data Size is valid. 465 * @param __DATASIZE__ I2S Data Size. 466 * @retval SET (__DATASIZE__ is valid) or RESET (__DATASIZE__ is invalid) 467 */ 468 #define IS_I2S_DATASIZE(__DATASIZE__) (((__DATASIZE__) == I2S_DATASIZE_12BIT) || \ 469 ((__DATASIZE__) == I2S_DATASIZE_16BIT) || \ 470 ((__DATASIZE__) == I2S_DATASIZE_20BIT) || \ 471 ((__DATASIZE__) == I2S_DATASIZE_24BIT) || \ 472 ((__DATASIZE__) == I2S_DATASIZE_32BIT)) 473 474 /** @brief Check if I2S Clock Polarity is valid. 475 * @param __CPOL__ I2S Clock Polarity. 476 * @retval SET (__CPOL__ is valid) or RESET (__CPOL__ is invalid) 477 */ 478 #define IS_I2S_CPOL(__CPOL__) (((__CPOL__) == I2S_POLARITY_LOW) || \ 479 ((__CPOL__) == I2S_POLARITY_HIGH)) 480 481 /** @brief Check if I2S Audio Frequency is valid. 482 * @param __FREQUENCY__ I2S Audio Frequency. 483 * @retval SET (__FREQUENCY__ is valid) or RESET (__FREQUENCY__ is invalid) 484 */ 485 #define IS_I2S_AUDIO_FREQUENCY(__FREQUENCY__) (((__FREQUENCY__) > 0) && ((__FREQUENCY__) <= 1500000)) 486 487 /** @brief Check if I2S FIFO Threshold is valid. 488 * @param __THR__ I2S FIFO Threshold. 489 * @retval SET (__THR__ is valid) or RESET (__THR__ is invalid) 490 */ 491 #define IS_I2S_FIFO_THRESHOLD(__THR__) (((__THR__) >= 0) && ((__THR__) <= I2S_TX_FIFO_LEVEL_MAX)) 492 493 /** @} */ 494 495 /** @} */ 496 497 /* Exported functions --------------------------------------------------------*/ 498 /** @addtogroup HAL_I2S_DRIVER_FUNCTIONS Functions 499 * @{ 500 */ 501 502 /** @defgroup I2S_Exported_Functions_Group1 Initialization and de-initialization functions 503 * @brief Initialization and de-initializations functions 504 * 505 @verbatim 506 =============================================================================== 507 ##### Initialization and de-initialization functions ##### 508 =============================================================================== 509 [..] This subsection provides a set of functions allowing to initialize and 510 de-initialize the I2Sx peripheral. 511 512 (+) User must implement hal_i2s_msp_init() function in which he configures 513 all related peripherals resources (GPIO, DMA, IT and NVIC ). 514 515 (+) Call the function hal_i2s_init() to configure the selected device with 516 the selected configuration: 517 (++) Data Size 518 (++) Clock Polarity 519 (++) Audio Frequency 520 521 (+) Call the function hal_i2s_deinit() to restore the default configuration 522 of the selected I2Sx peripheral. 523 524 @endverbatim 525 * @{ 526 */ 527 528 /** 529 **************************************************************************************** 530 * @brief Initialize the I2S according to the specified parameters 531 * in the i2s_init_t and initialize the associated handle. 532 * @param[in] p_i2s: Pointer to a I2S handle which contains the configuration information for the specified I2S module. 533 * @retval ::HAL_OK: Operation is OK. 534 * @retval ::HAL_ERROR: Parameter error or operation not supported. 535 * @retval ::HAL_BUSY: Driver is busy. 536 * @retval ::HAL_TIMEOUT: Timeout occurred. 537 **************************************************************************************** 538 */ 539 hal_status_t hal_i2s_init(i2s_handle_t *p_i2s); 540 541 /** 542 **************************************************************************************** 543 * @brief De-initialize the I2S peripheral. 544 * @param[in] p_i2s: Pointer to a I2S handle which contains the configuration information for the specified I2S module. 545 * @retval ::HAL_OK: Operation is OK. 546 * @retval ::HAL_ERROR: Parameter error or operation not supported. 547 * @retval ::HAL_BUSY: Driver is busy. 548 * @retval ::HAL_TIMEOUT: Timeout occurred. 549 **************************************************************************************** 550 */ 551 hal_status_t hal_i2s_deinit(i2s_handle_t *p_i2s); 552 553 /** 554 **************************************************************************************** 555 * @brief Initialize the I2S MSP. 556 * @note This function should not be modified. When the callback is needed, 557 the hal_i2s_msp_deinit can be implemented in the user file. 558 * @param[in] p_i2s: Pointer to a I2S handle which contains the configuration information for the specified I2S module. 559 **************************************************************************************** 560 */ 561 void hal_i2s_msp_init(i2s_handle_t *p_i2s); 562 563 /** 564 **************************************************************************************** 565 * @brief De-initialize the I2S MSP. 566 * @note This function should not be modified. When the callback is needed, 567 the hal_i2s_msp_deinit can be implemented in the user file. 568 * @param[in] p_i2s: Pointer to a I2S handle which contains the configuration information for the specified I2S module. 569 **************************************************************************************** 570 */ 571 void hal_i2s_msp_deinit(i2s_handle_t *p_i2s); 572 573 /** @} */ 574 575 /** @defgroup I2S_Exported_Functions_Group2 IO operation functions 576 * @brief Data transfers functions 577 * 578 @verbatim 579 ============================================================================== 580 ##### IO operation functions ##### 581 =============================================================================== 582 [..] 583 This subsection provides a set of functions allowing to manage the I2S 584 data transfers. 585 586 [..] The I2S supports master and slave mode: 587 588 (#) There are two modes of transfer: 589 (++) Blocking mode: The communication is performed in polling mode. 590 The HAL status of all data processing is returned by the same function 591 after finishing transfer. 592 (++) No-Blocking mode: The communication is performed using Interrupts 593 or DMA, These APIs return the HAL status. 594 The end of the data processing will be indicated through the 595 dedicated I2S IRQ when using Interrupt mode or the DMA IRQ when 596 using DMA mode. 597 The hal_i2s_tx_cplt_callback(), hal_i2s_rx_cplt_callback() and hal_i2s_tx_rx_cplt_callback() user callbacks 598 will be executed respectively at the end of the transmit or Receive process 599 The hal_i2s_error_callback() user callback will be executed when a communication error is detected. 600 601 (#) APIs provided for these 2 transfer modes (Blocking mode or Non blocking mode using either Interrupt or DMA) 602 exist for 1-Line (simplex) and 2-Line (full duplex) modes. 603 604 @endverbatim 605 * @{ 606 */ 607 608 /** 609 **************************************************************************************** 610 * @brief Transmit an amount of data in blocking mode. 611 * @param[in] p_i2s: Pointer to a I2S handle which contains the configuration information for the specified I2S module. 612 * @param[in] p_data: Pointer to data buffer 613 * @param[in] length: Amount of data to be sent in halfword, data of a channel. 614 * For example, when 32 bytes of data need to be sent in each of the left and right channels, length = 16. 615 * @param[in] timeout: Timeout duration 616 * @retval ::HAL_OK: Operation is OK. 617 * @retval ::HAL_ERROR: Parameter error or operation not supported. 618 * @retval ::HAL_BUSY: Driver is busy. 619 * @retval ::HAL_TIMEOUT: Timeout occurred. 620 **************************************************************************************** 621 */ 622 hal_status_t hal_i2s_transmit(i2s_handle_t *p_i2s, uint16_t *p_data, uint32_t length, uint32_t timeout); 623 624 /** 625 **************************************************************************************** 626 * @brief Receive an amount of data in blocking mode. 627 * @param[in] p_i2s: Pointer to a I2S handle which contains the configuration information for the specified I2S module. 628 * @param[out] p_data: Pointer to data buffer 629 * @param[in] length: Amount of data to be received in halfword, data of a channel. 630 * For example, when 32 bytes of data need to be sent in each of the left and right channels, length = 16. 631 * @param[in] timeout: Timeout duration 632 * @retval ::HAL_OK: Operation is OK. 633 * @retval ::HAL_ERROR: Parameter error or operation not supported. 634 * @retval ::HAL_BUSY: Driver is busy. 635 * @retval ::HAL_TIMEOUT: Timeout occurred. 636 **************************************************************************************** 637 */ 638 hal_status_t hal_i2s_receive(i2s_handle_t *p_i2s, uint16_t *p_data, uint32_t length, uint32_t timeout); 639 640 /** 641 **************************************************************************************** 642 * @brief Transmit and Receive an amount of data in blocking mode. 643 * @param[in] p_i2s: Pointer to a I2S handle which contains the configuration information for the specified I2S module. 644 * @param[in] p_tx_data: Pointer to transmission data buffer 645 * @param[out] p_rx_data: Pointer to reception data buffer 646 * @param[in] length: Amount of data to be sent and received in bytes 647 * @param[in] timeout: Timeout duration 648 * @retval ::HAL_OK: Operation is OK. 649 * @retval ::HAL_ERROR: Parameter error or operation not supported. 650 * @retval ::HAL_BUSY: Driver is busy. 651 * @retval ::HAL_TIMEOUT: Timeout occurred. 652 **************************************************************************************** 653 */ 654 hal_status_t hal_i2s_transmit_receive(i2s_handle_t *p_i2s, uint16_t *p_tx_data, uint16_t *p_rx_data, 655 uint32_t length, uint32_t timeout); 656 657 /** 658 **************************************************************************************** 659 * @brief Transmit an amount of data in non-blocking mode with Interrupt. 660 * @param[in] p_i2s: Pointer to a I2S handle which contains the configuration information for the specified I2S module. 661 * @param[in] p_data: Pointer to data buffer 662 * @param[in] length: Amount of data to be sent in halfword, data of a channel. 663 * For example, when 32 bytes of data need to be sent in each of the left and right channels, length = 16. 664 * @retval ::HAL_OK: Operation is OK. 665 * @retval ::HAL_ERROR: Parameter error or operation not supported. 666 * @retval ::HAL_BUSY: Driver is busy. 667 * @retval ::HAL_TIMEOUT: Timeout occurred. 668 **************************************************************************************** 669 */ 670 hal_status_t hal_i2s_transmit_it(i2s_handle_t *p_i2s, uint16_t *p_data, uint32_t length); 671 672 /** 673 **************************************************************************************** 674 * @brief Receive an amount of data in non-blocking mode with Interrupt. 675 * @param[in] p_i2s: Pointer to a I2S handle which contains the configuration information for the specified I2S module. 676 * @param[out] p_data: Pointer to data buffer 677 * @param[in] length: Amount of data to be sent in halfword, data of a channel. 678 * For example, when 32 bytes of data need to be sent in each of the left and right channels, length = 16. 679 * @retval ::HAL_OK: Operation is OK. 680 * @retval ::HAL_ERROR: Parameter error or operation not supported. 681 * @retval ::HAL_BUSY: Driver is busy. 682 * @retval ::HAL_TIMEOUT: Timeout occurred. 683 **************************************************************************************** 684 */ 685 hal_status_t hal_i2s_receive_it(i2s_handle_t *p_i2s, uint16_t *p_data, uint32_t length); 686 687 /** 688 **************************************************************************************** 689 * @brief Transmit and Receive an amount of data in non-blocking mode with Interrupt. 690 * @param[in] p_i2s: Pointer to a I2S handle which contains the configuration information for the specified SPI module. 691 * @param[in] p_tx_data: Pointer to transmission data buffer 692 * @param[out] p_rx_data: Pointer to reception data buffer 693 * @param[in] length: Amount of data to be sent and received in bytes 694 * @retval ::HAL_OK: Operation is OK. 695 * @retval ::HAL_ERROR: Parameter error or operation not supported. 696 * @retval ::HAL_BUSY: Driver is busy. 697 * @retval ::HAL_TIMEOUT: Timeout occurred. 698 **************************************************************************************** 699 */ 700 hal_status_t hal_i2s_transmit_receive_it(i2s_handle_t *p_i2s, uint16_t *p_tx_data, 701 uint16_t *p_rx_data, uint32_t length); 702 703 /** 704 **************************************************************************************** 705 * @brief Transmit an amount of data in non-blocking mode with DMA. 706 * @param[in] p_i2s: Pointer to a I2S handle which contains the configuration information for the specified I2S module. 707 * @param[in] p_data: Pointer to data buffer 708 * @param[in] length: Amount of data to be sent in halfword, data of a channel, ranging between 1 and 4095. 709 * For example, when 32 bytes of data need to be sent in each of the left and right channels, length = 16. 710 * @retval ::HAL_OK: Operation is OK. 711 * @retval ::HAL_ERROR: Parameter error or operation not supported. 712 * @retval ::HAL_BUSY: Driver is busy. 713 * @retval ::HAL_TIMEOUT: Timeout occurred. 714 **************************************************************************************** 715 */ 716 hal_status_t hal_i2s_transmit_dma(i2s_handle_t *p_i2s, uint16_t *p_data, uint32_t length); 717 718 /** 719 **************************************************************************************** 720 * @brief Receive an amount of data in non-blocking mode with DMA. 721 * @param[in] p_i2s: Pointer to a I2S handle which contains the configuration information for the specified I2S module. 722 * @param[out] p_data: Pointer to data buffer 723 * @param[in] length: Amount of data to be sent in halfword, data of a channel, ranging between 1 and 4095. 724 * For example, when 32 bytes of data need to be sent in each of the left and right channels, length = 16. 725 * @retval ::HAL_OK: Operation is OK. 726 * @retval ::HAL_ERROR: Parameter error or operation not supported. 727 * @retval ::HAL_BUSY: Driver is busy. 728 * @retval ::HAL_TIMEOUT: Timeout occurred. 729 **************************************************************************************** 730 */ 731 hal_status_t hal_i2s_receive_dma(i2s_handle_t *p_i2s, uint16_t *p_data, uint32_t length); 732 733 /** 734 **************************************************************************************** 735 * @brief Transmit and Receive an amount of data in non-blocking mode with DMA. 736 * @param[in] p_i2s: Pointer to a I2S handle which contains the configuration information for the specified I2S module. 737 * @param[in] p_tx_data: Pointer to transmission data buffer 738 * @param[out] p_rx_data: Pointer to reception data buffer 739 * @param[in] length: Amount of data to be sent in bytes, ranging between 0 and 4095. 740 * @retval ::HAL_OK: Operation is OK. 741 * @retval ::HAL_ERROR: Parameter error or operation not supported. 742 * @retval ::HAL_BUSY: Driver is busy. 743 * @retval ::HAL_TIMEOUT: Timeout occurred. 744 **************************************************************************************** 745 */ 746 hal_status_t hal_i2s_transmit_receive_dma(i2s_handle_t *p_i2s, uint16_t *p_tx_data, 747 uint16_t *p_rx_data, uint32_t length); 748 749 /** 750 **************************************************************************************** 751 * @brief Start the I2S master clock. 752 * @note In case of SLAVE mode, this function will not take effect. 753 * @param[in] p_i2s: Pointer to a I2S handle which contains the configuration information for the specified I2S module. 754 * @retval ::HAL_OK: Operation is OK. 755 * @retval ::HAL_ERROR: Parameter error or operation not supported. 756 * @retval ::HAL_BUSY: Driver is busy. 757 * @retval ::HAL_TIMEOUT: Timeout occurred. 758 **************************************************************************************** 759 */ 760 hal_status_t hal_i2s_start_clock(i2s_handle_t *p_i2s); 761 762 /** 763 **************************************************************************************** 764 * @brief Stop the I2S master clock. 765 * @note In case of SLAVE mode, this function will not take effect. 766 * @param[in] p_i2s: Pointer to a I2S handle which contains the configuration information for the specified I2S module. 767 * @retval ::HAL_OK: Operation is OK. 768 * @retval ::HAL_ERROR: Parameter error or operation not supported. 769 * @retval ::HAL_BUSY: Driver is busy. 770 * @retval ::HAL_TIMEOUT: Timeout occurred. 771 **************************************************************************************** 772 */ 773 hal_status_t hal_i2s_stop_clock(i2s_handle_t *p_i2s); 774 775 /** 776 **************************************************************************************** 777 * @brief Abort ongoing transfer (blocking mode). 778 * @param[in] p_i2s: I2S handle. 779 * @note This procedure could be used for aborting any ongoing transfer (TX and RX), 780 * started in Interrupt or DMA mode. 781 * This procedure performs following operations : 782 * - Disable I2S Interrupts (depending of transfer direction) 783 * - Disable the DMA transfer in the peripheral register (if enabled) 784 * - Abort DMA transfer by calling hal_dma_abort (in case of transfer in DMA mode) 785 * - Set handle State to READY 786 * @note This procedure is executed in blocking mode: When exiting function, Abort is considered as completed. 787 * @retval ::HAL_OK: Operation is OK. 788 * @retval ::HAL_ERROR: Parameter error or operation not supported. 789 * @retval ::HAL_BUSY: Driver is busy. 790 * @retval ::HAL_TIMEOUT: Timeout occurred. 791 **************************************************************************************** 792 */ 793 hal_status_t hal_i2s_abort(i2s_handle_t *p_i2s); 794 795 /** @} */ 796 797 /** @addtogroup I2S_IRQ_Handler_and_Callbacks IRQ Handler and Callbacks 798 * @brief IRQ Handler and Callbacks functions 799 * @{ 800 */ 801 802 /** 803 **************************************************************************************** 804 * @brief Handle I2S interrupt request. 805 * @param[in] p_i2s: Pointer to a I2S handle which contains the configuration information for the specified I2S module. 806 **************************************************************************************** 807 */ 808 void hal_i2s_irq_handler(i2s_handle_t *p_i2s); 809 810 /** 811 **************************************************************************************** 812 * @brief TX Transfer completed callback. 813 * @param[in] p_i2s: Pointer to a I2S handle which contains the configuration information for the specified I2S module. 814 **************************************************************************************** 815 */ 816 void hal_i2s_tx_cplt_callback(i2s_handle_t *p_i2s); 817 818 /** 819 **************************************************************************************** 820 * @brief RX Transfer completed callback. 821 * @param[in] p_i2s: Pointer to a I2S handle which contains the configuration information for the specified I2S module. 822 **************************************************************************************** 823 */ 824 void hal_i2s_rx_cplt_callback(i2s_handle_t *p_i2s); 825 826 /** 827 **************************************************************************************** 828 * @brief TX/RX Transfer completed callback. 829 * @param[in] p_i2s: Pointer to a I2S handle which contains the configuration information for the specified I2S module. 830 **************************************************************************************** 831 */ 832 void hal_i2s_tx_rx_cplt_callback(i2s_handle_t *p_i2s); 833 834 /** 835 **************************************************************************************** 836 * @brief I2S error callback. 837 * @param[in] p_i2s: Pointer to a I2S handle which contains the configuration information for the specified I2S module. 838 **************************************************************************************** 839 */ 840 void hal_i2s_error_callback(i2s_handle_t *p_i2s); 841 842 /** @} */ 843 844 /** @defgroup I2S_Exported_Functions_Group3 Peripheral State and Errors functions 845 * @brief I2S control functions 846 * 847 @verbatim 848 =============================================================================== 849 ##### Peripheral State and Errors functions ##### 850 =============================================================================== 851 [..] 852 This subsection provides a set of functions allowing to control the I2S. 853 (+) hal_i2s_get_state() API can be helpful to check in run-time the state of the I2S peripheral 854 (+) hal_i2s_get_error() check in run-time Errors occurring during communication 855 (+) hal_i2s_set_timeout() set the timeout during internal process 856 (+) hal_i2s_set_tx_fifo_threshold() set the TX FIFO Threshold 857 (+) hal_i2s_set_rx_fifo_threshold() set the RX FIFO Threshold 858 (+) hal_i2s_get_tx_fifo_threshold() get the TX FIFO Threshold 859 (+) hal_i2s_get_rx_fifo_threshold() get the RX FIFO Threshold 860 @endverbatim 861 * @{ 862 */ 863 864 /** 865 **************************************************************************************** 866 * @brief Return the I2S handle state. 867 * @param[in] p_i2s: Pointer to a I2S handle which contains the configuration information for the specified I2S module. 868 * @retval ::HAL_I2S_STATE_RESET: Peripheral not initialized. 869 * @retval ::HAL_I2S_STATE_READY: Peripheral initialized and ready for use. 870 * @retval ::HAL_I2S_STATE_BUSY: An internal process is ongoing. 871 * @retval ::HAL_I2S_STATE_BUSY_TX: Data Transmii2son process is ongoing. 872 * @retval ::HAL_I2S_STATE_BUSY_RX: Data Reception process is ongoing. 873 * @retval ::HAL_I2S_STATE_ABORT: Peripheral with abort request ongoing. 874 * @retval ::HAL_I2S_STATE_ERROR: Peripheral in error. 875 **************************************************************************************** 876 */ 877 hal_i2s_state_t hal_i2s_get_state(i2s_handle_t *p_i2s); 878 879 /** 880 **************************************************************************************** 881 * @brief Return the I2S error code. 882 * @param[in] p_i2s: Pointer to a I2S handle which contains the configuration information for the specified I2S module. 883 * @return I2S error code in bitmap format 884 **************************************************************************************** 885 */ 886 uint32_t hal_i2s_get_error(i2s_handle_t *p_i2s); 887 888 /** 889 **************************************************************************************** 890 * @brief Set the TX FIFO threshold. 891 * @param[in] p_i2s: Pointer to a I2S handle which contains the configuration information for the specified I2S module. 892 * @param[in] threshold: TX FIFO threshold value ranging bwtween 0x0U ~ 0x7U. 893 * @retval ::HAL_OK: Operation is OK. 894 * @retval ::HAL_ERROR: Parameter error or operation not supported. 895 * @retval ::HAL_BUSY: Driver is busy. 896 * @retval ::HAL_TIMEOUT: Timeout occurred. 897 **************************************************************************************** 898 */ 899 hal_status_t hal_i2s_set_tx_fifo_threshold(i2s_handle_t *p_i2s, uint32_t threshold); 900 901 /** 902 **************************************************************************************** 903 * @brief Set the RX FIFO threshold. 904 * @param[in] p_i2s: Pointer to a I2S handle which contains the configuration information for the specified I2S module. 905 * @param[in] threshold: RX FIFO threshold value ranging bwtween 0x0U ~ 0x7U. 906 * @retval ::HAL_OK: Operation is OK. 907 * @retval ::HAL_ERROR: Parameter error or operation not supported. 908 * @retval ::HAL_BUSY: Driver is busy. 909 * @retval ::HAL_TIMEOUT: Timeout occurred. 910 **************************************************************************************** 911 */ 912 hal_status_t hal_i2s_set_rx_fifo_threshold(i2s_handle_t *p_i2s, uint32_t threshold); 913 914 /** 915 **************************************************************************************** 916 * @brief Get the TX FIFO threshold. 917 * @param[in] p_i2s: Pointer to a I2S handle which contains the configuration information for the specified I2S module. 918 * @return TX FIFO threshold 919 **************************************************************************************** 920 */ 921 uint32_t hal_i2s_get_tx_fifo_threshold(i2s_handle_t *p_i2s); 922 923 /** 924 **************************************************************************************** 925 * @brief Get the RX FIFO threshold. 926 * @param[in] p_i2s: Pointer to a I2S handle which contains the configuration information for the specified I2S module. 927 * @return RX FIFO threshold 928 **************************************************************************************** 929 */ 930 uint32_t hal_i2s_get_rx_fifo_threshold(i2s_handle_t *p_i2s); 931 932 /** 933 **************************************************************************************** 934 * @brief Suspend some registers related to I2S configuration before sleep. 935 * @param[in] p_i2s: Pointer to a I2S handle which contains the configuration 936 * information for the specified I2S module. 937 * @retval ::HAL_OK: Operation is OK. 938 * @retval ::HAL_ERROR: Parameter error or operation not supported. 939 * @retval ::HAL_BUSY: Driver is busy. 940 * @retval ::HAL_TIMEOUT: Timeout occurred. 941 **************************************************************************************** 942 */ 943 hal_status_t hal_i2s_suspend_reg(i2s_handle_t *p_i2s); 944 945 /** 946 **************************************************************************************** 947 * @brief Restore some registers related to I2S configuration after sleep. 948 * This function must be used in conjunction with the hal_i2s_suspend_reg(). 949 * @param[in] p_i2s: Pointer to a I2S handle which contains the configuration 950 * information for the specified I2S module. 951 * @retval ::HAL_OK: Operation is OK. 952 * @retval ::HAL_ERROR: Parameter error or operation not supported. 953 * @retval ::HAL_BUSY: Driver is busy. 954 * @retval ::HAL_TIMEOUT: Timeout occurred. 955 **************************************************************************************** 956 */ 957 hal_status_t hal_i2s_resume_reg(i2s_handle_t *p_i2s); 958 959 /** @} */ 960 961 /** @} */ 962 963 #ifdef __cplusplus 964 } 965 #endif 966 967 #endif /* __GR55xx_HAL_I2S_H__ */ 968 969 /** @} */ 970 971 /** @} */ 972 973 /** @} */ 974