1 /** 2 **************************************************************************************** 3 * 4 * @file gr55xx_hal_pwm.h 5 * @author BLE Driver Team 6 * @brief Header file containing functions prototypes of PWM 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_PWM PWM 47 * @brief PWM HAL module driver. 48 * @{ 49 */ 50 51 /* Define to prevent recursive inclusion -------------------------------------*/ 52 #ifndef __GR55xx_HAL_PWM_H__ 53 #define __GR55xx_HAL_PWM_H__ 54 55 /* Includes ------------------------------------------------------------------*/ 56 #include "gr55xx_hal_def.h" 57 #include "gr55xx_ll_pwm.h" 58 59 #ifdef __cplusplus 60 extern "C" { 61 #endif 62 63 /* Exported types ------------------------------------------------------------*/ 64 /** @addtogroup HAL_PWM_ENUMERATIONS Enumerations 65 * @{ 66 */ 67 68 /** @defgroup HAL_PWM_state HAL PWM state 69 * @{ 70 */ 71 72 /** 73 * @brief HAL PWM State Enumerations definition 74 */ 75 typedef enum { 76 HAL_PWM_STATE_RESET = 0x00, /**< Peripheral is not initialized or disabled */ 77 HAL_PWM_STATE_READY = 0x01, /**< Peripheral is initialized and ready for use */ 78 HAL_PWM_STATE_BUSY = 0x02, /**< An internal process is ongoing */ 79 HAL_PWM_STATE_ERROR = 0x04 /**< Reception process is ongoing */ 80 } hal_pwm_state_t; 81 /** @} */ 82 83 /** @defgroup HAL_PWM_active_channel HAL PWM active channel 84 * @{ 85 */ 86 87 /** 88 * @brief HAL PWM active channel Enumerations definition 89 */ 90 typedef enum { 91 HAL_PWM_ACTIVE_CHANNEL_A = 0x01, /**< The active channel is A */ 92 HAL_PWM_ACTIVE_CHANNEL_B = 0x02, /**< The active channel is B */ 93 HAL_PWM_ACTIVE_CHANNEL_C = 0x04, /**< The active channel is C */ 94 HAL_PWM_ACTIVE_CHANNEL_ALL = 0x07, /**< The active channels are ALL */ 95 HAL_PWM_ACTIVE_CHANNEL_CLEARED = 0x00 /**< All active channels are cleared */ 96 } hal_pwm_active_channel_t; 97 /** @} */ 98 99 /** @} */ 100 101 /** @addtogroup HAL_PWM_STRUCTURES Structures 102 * @{ 103 */ 104 105 /** @defgroup PWM_Configuration PWM Configuration 106 * @{ 107 */ 108 109 /** 110 * @brief PWM Channel init Structure definition 111 */ 112 typedef struct { 113 uint8_t duty; /**< Specifies the duty in PWM output mode. 114 This parameter must be a number between 0 ~ 100. */ 115 116 uint8_t drive_polarity; /**< Specifies the drive polarity in PWM output mode. 117 This parameter can be a value of @ref PWM_Drive_Polarity. */ 118 } pwm_channel_init_t; 119 120 /** 121 * @brief PWM init Structure definition 122 */ 123 typedef struct { 124 uint32_t mode; /**< Specifies the PWM output mode state. 125 This parameter can be a value of @ref PWM_Mode */ 126 127 uint32_t align; /**< Specifies the PWM alignment mode with three channels 128 This parameter can be a value of @ref PWM_Alignment_Mode */ 129 130 uint32_t freq; /**< Specifies the PWM frequency. 131 This parameter must be a number between 0 ~ SystemFreq/2 (max = 32Mhz). */ 132 133 uint32_t bperiod; /**< Specifies the PWM breath period in breath mode. Unit: ms. 134 This parameter must be a number between 0 ~ 0xFFFFFFFF/SystemFreq*1000. */ 135 136 uint32_t hperiod; /**< Specifies the PWM hold period in breath mode. Unit: ms. 137 This parameter must be a number between 0 ~ 0xFFFFFF/SystemFreq*1000. */ 138 139 pwm_channel_init_t channel_a; /**< Specifies the configuration parameters of channel A. */ 140 141 pwm_channel_init_t channel_b; /**< Specifies the configuration parameters of channel B. */ 142 143 pwm_channel_init_t channel_c; /**< Specifies the configuration parameters of channel C. */ 144 } pwm_init_t; 145 /** @} */ 146 147 /** @defgroup PWM_handle PWM handle 148 * @{ 149 */ 150 151 /** 152 * @brief PWM handle Structure definition 153 */ 154 typedef struct { 155 pwm_regs_t *p_instance; /**< Register base address */ 156 157 pwm_init_t init; /**< Required parameters for PWM Base */ 158 159 hal_pwm_active_channel_t active_channel; /**< Active channel */ 160 161 __IO hal_lock_t lock; /**< Lock object */ 162 163 __IO hal_pwm_state_t state; /**< PWM operation state */ 164 165 uint32_t retention[11]; /**< PWM important register information. */ 166 } pwm_handle_t; 167 168 /** @} */ 169 170 /** @} */ 171 172 /** @addtogroup HAL_PWM_CALLBACK_STRUCTURES Callback Structures 173 * @{ 174 */ 175 176 /** @defgroup HAL_PWM_Callback Callback 177 * @{ 178 */ 179 180 /** 181 * @brief HAL_PWM Callback function definition 182 */ 183 184 typedef struct _hal_pwm_callback { 185 void (*pwm_msp_init)(pwm_handle_t *p_pwm); /**< PWM init MSP callback */ 186 void (*pwm_msp_deinit)(pwm_handle_t *p_pwm); /**< PWM de-init MSP callback */ 187 } hal_pwm_callback_t; 188 189 /** @} */ 190 191 /** @} */ 192 193 /** 194 * @defgroup HAL_PWM_MACRO Defines 195 * @{ 196 */ 197 198 /* Exported constants --------------------------------------------------------*/ 199 /** @defgroup PWM_Exported_Constants PWM Exported Constants 200 * @{ 201 */ 202 203 /** @defgroup PWM_Mode PWM Mode 204 * @{ 205 */ 206 #define PWM_MODE_FLICKER LL_PWM_FLICKER_MODE /**< PWM flicker mode */ 207 #define PWM_MODE_BREATH LL_PWM_BREATH_MODE /**< PWM breath mode */ 208 /** @} */ 209 210 /** @defgroup PWM_Alignment_Mode PWM Pulses Aligned. 211 * @{ 212 */ 213 #define PWM_ALIGNED_EDGE LL_PWM_EDGE_ALIGNED /**< PWM edge-aligned */ 214 #define PWM_ALIGNED_CENTER LL_PWM_CENTER_ALIGNED /**< PWM center-aligned */ 215 /** @} */ 216 217 /** @defgroup PWM_Drive_Polarity PWM Drive Polarity 218 * @{ 219 */ 220 #define PWM_DRIVEPOLARITY_NEGATIVE LL_PWM_DRIVEPOLARITY_NEGATIVE /**< PWM led-negative-drive mode */ 221 #define PWM_DRIVEPOLARITY_POSITIVE LL_PWM_DRIVEPOLARITY_POSITIVE /**< PWM led-positive-drive mode */ 222 /** @} */ 223 /** @} */ 224 225 /* Exported macro ------------------------------------------------------------*/ 226 /** @defgroup PWM_Exported_Macros PWM Exported Macros 227 * @{ 228 */ 229 230 /** @brief Reset PWM handle states. 231 * @param __HANDLE__ PWM handle. 232 * @retval None 233 */ 234 #define __HAL_PWM_RESET_HANDLE_STATE(__HANDLE__) ((__HANDLE__)->state = HAL_PWM_STATE_RESET) 235 236 /** @brief Enable the specified PWM peripheral. 237 * @param __HANDLE__ specifies the PWM Handle. 238 * @retval None 239 */ 240 #define __HAL_PWM_ENABLE(__HANDLE__) SET_BITS((__HANDLE__)->p_instance->MODE, PWM_MODE_EN) 241 242 /** @brief Disable the specified PWM peripheral. 243 * @param __HANDLE__ specifies the PWM Handle. 244 * @retval None 245 */ 246 #define __HAL_PWM_DISABLE(__HANDLE__) CLEAR_BITS((__HANDLE__)->p_instance->MODE, PWM_MODE_EN) 247 248 /** @brief Enable PWM breath mode. 249 * @param __HANDLE__ specifies the PWM Handle. 250 * @retval None 251 */ 252 #define __HAL_PWM_ENABLE_BREATH(__HANDLE__) SET_BITS((__HANDLE__)->p_instance->MODE, PWM_MODE_BREATHEN) 253 254 /** @brief Disable PWM breath mode. 255 * @param __HANDLE__ specifies the PWM Handle. 256 * @retval None 257 */ 258 #define __HAL_PWM_DISABLE_BREATH(__HANDLE__) CLEAR_BITS((__HANDLE__)->p_instance->MODE, PWM_MODE_BREATHEN) 259 260 /** @} */ 261 262 /* Private macros ------------------------------------------------------------*/ 263 /** @defgroup PWM_Private_Macro PWM Private Macros 264 * @{ 265 */ 266 267 /** 268 * @brief Check if PWM mode is valid. 269 * @param __MODE__ PWM mode. 270 * @retval SET (__MODE__ is valid) or RESET (__MODE__ is invalid) 271 */ 272 #define IS_PWM_MODE(__MODE__) (((__MODE__) == PWM_MODE_FLICKER) || \ 273 ((__MODE__) == PWM_MODE_BREATH)) 274 275 /** 276 * @brief Check if PWM Alignment mode is valid. 277 * @param __MODE__ PWM Alignment mode. 278 * @retval SET (__MODE__ is valid) or RESET (__MODE__ is invalid) 279 */ 280 #define IS_PWM_ALIGNMENT_MODE(__MODE__) (((__MODE__) == PWM_EDGE) || \ 281 ((__MODE__) == PWM_CENTER)) 282 283 /** 284 * @brief Check if PWM drive polarity is valid. 285 * @param __POLARITY__ PWM drive polarity. 286 * @retval SET (__POLARITY__ is valid) or RESET (__POLARITY__ is invalid) 287 */ 288 #define IS_PWM_DRIVEPOLARITY(__POLARITY__) (((__POLARITY__) == PWM_DRIVEPOLARITY_NEGATIVE) || \ 289 ((__POLARITY__) == PWM_DRIVEPOLARITY_POSITIVE)) 290 291 /** @} */ 292 293 /** @} */ 294 295 296 /* Exported functions --------------------------------------------------------*/ 297 /** @addtogroup HAL_PWM_DRIVER_FUNCTIONS Functions 298 * @{ 299 */ 300 301 /** @addtogroup PWM_Exported_Functions_Group1 Initialization and de-initialization functions 302 * @brief Initialization and de-initialization functions 303 * 304 * @verbatim 305 =============================================================================== 306 ##### Initialization and de-initialization functions ##### 307 =============================================================================== 308 [..] 309 This subsection provides a set of functions allowing to initialize the PWMx. 310 (+) The parameters below can only be configured in breath mode: 311 (++) BreathPeriod 312 (++) HoldPeriod 313 314 @endverbatim 315 * @{ 316 */ 317 318 /** 319 **************************************************************************************** 320 * @brief Initialize the PWM mode according to the specified 321 * parameters in the pwm_init_t and initialize the associated handle. 322 * @param[in] p_pwm: Pointer to a PWM handle that contains the configuration information for the specified PWM module. 323 * @retval ::HAL_OK: Operation is OK. 324 * @retval ::HAL_ERROR: Parameter error or operation not supported. 325 * @retval ::HAL_BUSY: Driver is busy. 326 * @retval ::HAL_TIMEOUT: Timeout occurred. 327 **************************************************************************************** 328 */ 329 hal_status_t hal_pwm_init(pwm_handle_t *p_pwm); 330 331 /** 332 **************************************************************************************** 333 * @brief De-initialize the PWM peripheral. 334 * @param[in] p_pwm: Pointer to a PWM handle that contains the configuration information for the specified PWM module. 335 * @retval ::HAL_OK: Operation is OK. 336 * @retval ::HAL_ERROR: Parameter error or operation not supported. 337 * @retval ::HAL_BUSY: Driver is busy. 338 * @retval ::HAL_TIMEOUT: Timeout occurred. 339 **************************************************************************************** 340 */ 341 hal_status_t hal_pwm_deinit(pwm_handle_t *p_pwm); 342 343 /** 344 **************************************************************************************** 345 * @brief Initialize the PWM MSP. 346 * @note This function should not be modified. When the callback is needed, 347 the hal_pwm_msp_init can be implemented in the user file. 348 * @param[in] p_pwm: Pointer to a PWM handle that contains the configuration information for the specified PWM module. 349 **************************************************************************************** 350 */ 351 void hal_pwm_msp_init(pwm_handle_t *p_pwm); 352 353 /** 354 **************************************************************************************** 355 * @brief De-initialize the PWM MSP. 356 * @note This function should not be modified. When the callback is needed, 357 the hal_pwm_msp_deinit can be implemented in the user file. 358 * @param[in] p_pwm: Pointer to a PWM handle that contains the configuration information for the specified PWM module. 359 **************************************************************************************** 360 */ 361 void hal_pwm_msp_deinit(pwm_handle_t *p_pwm); 362 363 /** @} */ 364 365 /** @addtogroup PWM_Exported_Functions_Group2 IO operation functions 366 * @brief IO operation functions 367 * 368 @verbatim 369 ============================================================================== 370 ##### IO operation functions ##### 371 ============================================================================== 372 [..] 373 This section provides functions allowing to: 374 (+) Start the PWM. 375 (+) Stop the PWM. 376 (+) Configure the specified PWM channel. 377 378 @endverbatim 379 * @{ 380 */ 381 382 /** 383 **************************************************************************************** 384 * @brief Starts the PWM signal generation on the output. 385 * @param[in] p_pwm: Pointer to a PWM handle that contains the configuration information for the specified PWM module. 386 * @retval ::HAL_OK: Operation is OK. 387 * @retval ::HAL_ERROR: Parameter error or operation not supported. 388 * @retval ::HAL_BUSY: Driver is busy. 389 * @retval ::HAL_TIMEOUT: Timeout occurred. 390 **************************************************************************************** 391 */ 392 hal_status_t hal_pwm_start(pwm_handle_t *p_pwm); 393 394 /** 395 **************************************************************************************** 396 * @brief Stops the PWM signal generation on the output. 397 * @param[in] p_pwm: Pointer to a PWM handle that contains the configuration information for the specified PWM module. 398 * @retval ::HAL_OK: Operation is OK. 399 * @retval ::HAL_ERROR: Parameter error or operation not supported. 400 * @retval ::HAL_BUSY: Driver is busy. 401 * @retval ::HAL_TIMEOUT: Timeout occurred. 402 **************************************************************************************** 403 */ 404 hal_status_t hal_pwm_stop(pwm_handle_t *p_pwm); 405 406 /** 407 **************************************************************************************** 408 * @brief Update the PWM frequency on the output. 409 * @param[in] p_pwm: Pointer to a PWM handle that contains the configuration information for the specified PWM module. 410 * @param[in] freq: This parameter ranges between min = 0 and max = SystemFreq / 2. 411 * @retval ::HAL_OK: Operation is OK. 412 * @retval ::HAL_ERROR: Parameter error or operation not supported. 413 * @retval ::HAL_BUSY: Driver is busy. 414 * @retval ::HAL_TIMEOUT: Timeout occurred. 415 **************************************************************************************** 416 */ 417 hal_status_t hal_pwm_update_freq(pwm_handle_t *p_pwm, uint32_t freq); 418 419 /** 420 **************************************************************************************** 421 * @brief Suspend some registers related to PWM configuration before sleep. 422 * @param[in] p_pwm: Pointer to a PWM handle which contains the configuration 423 * information for the specified PWM module. 424 * @retval ::HAL_OK: Operation is OK. 425 * @retval ::HAL_ERROR: Parameter error or operation not supported. 426 * @retval ::HAL_BUSY: Driver is busy. 427 * @retval ::HAL_TIMEOUT: Timeout occurred. 428 **************************************************************************************** 429 */ 430 hal_status_t hal_pwm_suspend_reg(pwm_handle_t *p_pwm); 431 432 /** 433 **************************************************************************************** 434 * @brief Restore some registers related to PWM configuration after sleep. 435 * This function must be used in conjunction with the hal_pwm_suspend_reg(). 436 * @param[in] p_pwm: Pointer to a PWM handle which contains the configuration 437 * information for the specified PWM module. 438 * @retval ::HAL_OK: Operation is OK. 439 * @retval ::HAL_ERROR: Parameter error or operation not supported. 440 * @retval ::HAL_BUSY: Driver is busy. 441 * @retval ::HAL_TIMEOUT: Timeout occurred. 442 **************************************************************************************** 443 */ 444 hal_status_t hal_pwm_resume_reg(pwm_handle_t *p_pwm); 445 446 /** 447 **************************************************************************************** 448 * @brief Initialize the PWM channels according to the specified 449 * parameters in the pwm_init_t. 450 * @param[in] p_pwm: Pointer to a PWM handle that contains the configuration information for the specified PWM module. 451 * @param[in] p_config: PWM Channels configuration structure. 452 * @param[in] channel: PWM Channels to be configured. 453 * This parameter can be one of the following values: 454 * @arg @ref HAL_PWM_ACTIVE_CHANNEL_A :PWM Channel A is active 455 * @arg @ref HAL_PWM_ACTIVE_CHANNEL_B :PWM Channel B is active 456 * @arg @ref HAL_PWM_ACTIVE_CHANNEL_C :PWM Channel C is active 457 * @arg @ref HAL_PWM_ACTIVE_CHANNEL_ALL :All Channels are active 458 * @retval ::HAL_OK: Operation is OK. 459 * @retval ::HAL_ERROR: Parameter error or operation not supported. 460 * @retval ::HAL_BUSY: Driver is busy. 461 * @retval ::HAL_TIMEOUT: Timeout occurred. 462 **************************************************************************************** 463 */ 464 hal_status_t hal_pwm_config_channel(pwm_handle_t *p_pwm, pwm_channel_init_t *p_config, 465 hal_pwm_active_channel_t channel); 466 467 /** @} */ 468 469 /** @addtogroup PWM_Exported_Functions_Group3 Peripheral Control and State functions 470 * @brief PWM Peripheral State functions 471 * 472 @verbatim 473 ============================================================================== 474 ##### Peripheral Control and State functions ##### 475 ============================================================================== 476 [..] 477 This subsection provides functions allowing to : 478 (+) Return the PWM handle state. 479 480 @endverbatim 481 * @{ 482 */ 483 484 /** 485 **************************************************************************************** 486 * @brief Return the PWM handle state. 487 * @param[in] p_pwm: Pointer to a PWM handle that contains the configuration 488 * information for the specified PWM module. 489 * @retval ::HAL_PWM_STATE_RESET: Peripheral is not initialized or disabled. 490 * @retval ::HAL_PWM_STATE_READY: Peripheral is initialized and ready for use. 491 * @retval ::HAL_PWM_STATE_BUSY: An internal process is ongoing. 492 * @retval ::HAL_PWM_STATE_ERROR: Reception process is ongoing. 493 **************************************************************************************** 494 */ 495 hal_pwm_state_t hal_pwm_get_state(pwm_handle_t *p_pwm); 496 497 /** @} */ 498 499 /** @} */ 500 501 #ifdef __cplusplus 502 } 503 #endif 504 505 #endif /* __GR55xx_HAL_PWM_H__ */ 506 507 /** @} */ 508 509 /** @} */ 510 511 /** @} */ 512