1 /** 2 **************************************************************************************** 3 * 4 * @file gr55xx_hal_comp.h 5 * @author BLE Driver Team 6 * @brief Header file containing functions prototypes of COMP 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_COMP COMP 47 * @brief COMP HAL module driver. 48 * @{ 49 */ 50 51 /* Define to prevent recursive inclusion -------------------------------------*/ 52 #ifndef __GR55xx_HAL_COMP_H__ 53 #define __GR55xx_HAL_COMP_H__ 54 55 /* Includes ------------------------------------------------------------------*/ 56 #include "gr55xx_ll_comp.h" 57 #include "gr55xx_hal_def.h" 58 59 #ifdef __cplusplus 60 extern "C" { 61 #endif 62 63 /* Exported types ------------------------------------------------------------*/ 64 /** @addtogroup HAL_COMP_ENUMERATIONS Enumerations 65 * @{ 66 */ 67 68 /** @defgroup HAL_COMP_state HAL COMP state 69 * @{ 70 */ 71 72 /** 73 * @brief HAL COMP State Enumerations definition 74 */ 75 typedef enum { 76 HAL_COMP_STATE_RESET = 0x00, /**< Peripheral not initialized */ 77 HAL_COMP_STATE_READY = 0x01, /**< Peripheral initialized and ready for use */ 78 HAL_COMP_STATE_BUSY = 0x02, /**< An internal process is ongoing */ 79 HAL_COMP_STATE_ERROR = 0x04 /**< Peripheral in error */ 80 } hal_comp_state_t; 81 82 /** @} */ 83 84 /** @} */ 85 86 /** @addtogroup HAL_COMP_STRUCTURES Structures 87 * @{ 88 */ 89 90 /** @defgroup COMP_Configuration COMP Configuration 91 * @{ 92 */ 93 94 /** 95 * @brief COMP init structure definition 96 */ 97 typedef ll_comp_init_t comp_init_t; 98 /** @} */ 99 100 /** @defgroup COMP_handle COMP handle 101 * @{ 102 */ 103 104 /** 105 * @brief COMP handle Structure definition 106 */ 107 typedef struct _comp_handle { 108 comp_init_t init; /**< COMP configuration parameters */ 109 110 __IO hal_lock_t lock; /**< Locking object */ 111 112 __IO hal_comp_state_t state; /**< COMP communication state */ 113 114 __IO uint32_t error_code; /**< COMP error code */ 115 116 uint32_t retention[1]; /**< COMP important register information. */ 117 } comp_handle_t; 118 /** @} */ 119 120 /** @} */ 121 122 /** @addtogroup HAL_COMP_CALLBACK_STRUCTURES Callback Structures 123 * @{ 124 */ 125 126 /** @defgroup COMP_Callback COMP Callback 127 * @{ 128 */ 129 130 /** 131 * @brief HAL COMP Callback function definition 132 */ 133 typedef struct _comp_callback { 134 void (*comp_msp_init)(comp_handle_t *p_comp); /**< COMP init MSP callback */ 135 void (*comp_msp_deinit)(comp_handle_t *p_comp); /**< COMP de-init MSP callback */ 136 void (*comp_trigger_callback)(comp_handle_t *p_comp); /**< COMP comparator callback */ 137 } comp_callback_t; 138 139 /** @} */ 140 141 /** @} */ 142 143 /** 144 * @defgroup HAL_COMP_MACRO Defines 145 * @{ 146 */ 147 148 /* Exported constants --------------------------------------------------------*/ 149 /** @defgroup COMP_Exported_Constants COMP Exported Constants 150 * @{ 151 */ 152 153 /** @defgroup COMP_Error_Code COMP Error Code 154 * @{ 155 */ 156 #define HAL_COMP_ERROR_NONE ((uint32_t)0x00000000) /**< No error */ 157 #define HAL_COMP_ERROR_TIMEOUT ((uint32_t)0x00000001) /**< Timeout error */ 158 #define HAL_COMP_ERROR_INVALID_PARAM ((uint32_t)0x00000002) /**< Invalid parameters error */ 159 /** @} */ 160 161 162 /** @defgroup COMP_INPUT_SOURCE COMP Input Channel Select 163 * @{ 164 */ 165 #define COMP_INPUT_SRC_IO0 LL_COMP_INPUT_SRC_IO0 /**< Set MSIO_0 as inputs for the comparator */ 166 #define COMP_INPUT_SRC_IO1 LL_COMP_INPUT_SRC_IO1 /**< Set MSIO_1 as inputs for the comparator */ 167 #define COMP_INPUT_SRC_IO2 LL_COMP_INPUT_SRC_IO2 /**< Set MSIO_2 as inputs for the comparator */ 168 #define COMP_INPUT_SRC_IO3 LL_COMP_INPUT_SRC_IO3 /**< Set MSIO_3 as inputs for the comparator */ 169 #define COMP_INPUT_SRC_IO4 LL_COMP_INPUT_SRC_IO4 /**< Set MSIO_4 as inputs for the comparator */ 170 /** @} */ 171 172 /** @defgroup COMP_REFERENCE_SOURCE COMP Reference Source Select 173 * @{ 174 */ 175 #define COMP_REF_SRC_IO0 LL_COMP_REF_SRC_IO0 /**< Set MSIO_0 as references for the comparator */ 176 #define COMP_REF_SRC_IO1 LL_COMP_REF_SRC_IO1 /**< Set MSIO_1 as references for the comparator */ 177 #define COMP_REF_SRC_IO2 LL_COMP_REF_SRC_IO2 /**< Set MSIO_2 as references for the comparator */ 178 #define COMP_REF_SRC_IO3 LL_COMP_REF_SRC_IO3 /**< Set MSIO_3 as references for the comparator */ 179 #define COMP_REF_SRC_IO4 LL_COMP_REF_SRC_IO4 /**< Set MSIO_4 as references for the comparator */ 180 #define COMP_REF_SRC_VBAT LL_COMP_REF_SRC_VBAT /**< Set VBATT as references for the comparator */ 181 #define COMP_REF_SRC_VREF LL_COMP_REF_SRC_VREF /**< Set VREF as references for the comparator */ 182 /** @} */ 183 184 /** 185 * @brief Default configuartion for initializing structure 186 */ 187 #define COMP_DEFAULT_CONFIG LL_COMP_DEFAULT_CONFIG 188 /** @} */ 189 190 /* Private macros ------------------------------------------------------------*/ 191 /** @addtogroup COMP_Private_Macros COMP Private Macros 192 * @{ 193 */ 194 195 /** 196 * @brief Check if COMP input source is valid. 197 * @param __INPUT__ COMP input source. 198 * @retval SET (__INPUT__ is valid) or RESET (__INPUT__ is invalid) 199 */ 200 #define IS_COMP_INPUT(__INPUT__) (((__INPUT__) == COMP_INPUT_SRC_IO0) || \ 201 ((__INPUT__) == COMP_INPUT_SRC_IO1) || \ 202 ((__INPUT__) == COMP_INPUT_SRC_IO2) || \ 203 ((__INPUT__) == COMP_INPUT_SRC_IO3) || \ 204 ((__INPUT__) == COMP_INPUT_SRC_IO4)) 205 206 /** 207 * @brief Check if COMP reference source is valid. 208 * @param __INPUT__ COMP reference source. 209 * @retval SET (__INPUT__ is valid) or RESET (__INPUT__ is invalid) 210 */ 211 #define IS_COMP_REF(__INPUT__) (((__INPUT__) == COMP_REF_SRC_IO0) || \ 212 ((__INPUT__) == COMP_REF_SRC_IO1) || \ 213 ((__INPUT__) == COMP_REF_SRC_IO2) || \ 214 ((__INPUT__) == COMP_REF_SRC_IO3) || \ 215 ((__INPUT__) == COMP_REF_SRC_IO4) || \ 216 ((__INPUT__) == COMP_REF_SRC_VBAT) || \ 217 ((__INPUT__) == COMP_REF_SRC_VREF)) 218 219 /** @} */ 220 221 /** @} */ 222 223 /* Exported functions --------------------------------------------------------*/ 224 /** @addtogroup HAL_COMP_DRIVER_FUNCTIONS Functions 225 * @{ 226 */ 227 228 /** @addtogroup COMP_Exported_Functions_Group1 Initialization and de-initialization functions 229 * @brief Initialization and Configuration functions 230 * @{ 231 */ 232 233 /** 234 **************************************************************************************** 235 * @brief Initialize the COMP according to the specified parameters 236 * in the comp_init_t and initialize the associated handle. 237 * 238 * @param[in] p_comp: Pointer to a COMP handle which contains the configuration information for 239 * the specified COMP module. 240 * 241 * @retval ::HAL_OK: Operation is OK. 242 * @retval ::HAL_ERROR: Parameter error or operation not supported. 243 * @retval ::HAL_BUSY: Driver is busy. 244 * @retval ::HAL_TIMEOUT: Timeout occurred. 245 **************************************************************************************** 246 */ 247 hal_status_t hal_comp_init(comp_handle_t *p_comp); 248 249 /** 250 **************************************************************************************** 251 * @brief De-initialize the COMP peripheral. 252 * 253 * @param[in] p_comp: Pointer to a COMP handle which contains the configuration information for 254 * the specified COMP module. 255 * 256 * @retval ::HAL_OK: Operation is OK. 257 * @retval ::HAL_ERROR: Parameter error or operation not supported. 258 * @retval ::HAL_BUSY: Driver is busy. 259 * @retval ::HAL_TIMEOUT: Timeout occurred. 260 **************************************************************************************** 261 */ 262 hal_status_t hal_comp_deinit(comp_handle_t *p_comp); 263 264 /** 265 **************************************************************************************** 266 * @brief Initialize the COMP MSP. 267 * 268 * @note This function should not be modified. When the callback is needed, 269 * the hal_comp_msp_deinit can be implemented in the user file. 270 * 271 * @param[in] p_comp: Pointer to a COMP handle which contains the configuration information for 272 * the specified COMP module. 273 **************************************************************************************** 274 */ 275 void hal_comp_msp_init(comp_handle_t *p_comp); 276 277 /** 278 **************************************************************************************** 279 * @brief De-initialize the COMP MSP. 280 * 281 * @note This function should not be modified. When the callback is needed, 282 * the hal_comp_msp_deinit can be implemented in the user file. 283 * 284 * @param[in] p_comp: Pointer to a COMP handle which contains the configuration information for 285 * the specified COMP module. 286 **************************************************************************************** 287 */ 288 void hal_comp_msp_deinit(comp_handle_t *p_comp); 289 290 /** @} */ 291 292 /** @addtogroup COMP_Exported_Functions_Group2 IO operation functions 293 * @brief COMP polling and DMA conversion management functions. 294 * @{ 295 */ 296 297 /** 298 **************************************************************************************** 299 * @brief Start the comparator. 300 * 301 * @param[in] p_comp: Pointer to a COMP handle which contains the configuration information for 302 * the specified COMP module. 303 * 304 * @retval ::HAL_OK: Operation is OK. 305 * @retval ::HAL_ERROR: Parameter error or operation not supported. 306 * @retval ::HAL_BUSY: Driver is busy. 307 * @retval ::HAL_TIMEOUT: Timeout occurred. 308 **************************************************************************************** 309 */ 310 hal_status_t hal_comp_start(comp_handle_t *p_comp); 311 312 /** 313 **************************************************************************************** 314 * @brief Stop the comparator. 315 * 316 * @param[in] p_comp: Pointer to a COMP handle which contains the configuration information for 317 * the specified COMP module. 318 * 319 * @retval ::HAL_OK: Operation is OK. 320 * @retval ::HAL_ERROR: Parameter error or operation not supported. 321 * @retval ::HAL_BUSY: Driver is busy. 322 * @retval ::HAL_TIMEOUT: Timeout occurred. 323 **************************************************************************************** 324 */ 325 hal_status_t hal_comp_stop(comp_handle_t *p_comp); 326 327 /** @} */ 328 329 /** @addtogroup COMP_IRQ_Handler_and_Callbacks IRQ Handler and Callbacks 330 * @brief IRQ Handler and Callbacks functions 331 * @{ 332 */ 333 334 /** 335 **************************************************************************************** 336 * @brief Handle COMP interrupt request. 337 * @param[in] p_comp: Pointer to a COMP handle which contains the configuration information 338 * for the specified COMP module. 339 **************************************************************************************** 340 */ 341 void hal_comp_irq_handler(comp_handle_t *p_comp); 342 343 /** 344 **************************************************************************************** 345 * @brief comparator callback. 346 * 347 * @note This function should not be modified. When the callback is needed, 348 * the hal_comp_trigger_callback can be implemented in the user file. 349 * 350 * @param[in] p_comp: Pointer to a COMP handle which contains the configuration information for 351 * the specified COMP module. 352 **************************************************************************************** 353 */ 354 void hal_comp_trigger_callback(comp_handle_t *p_comp); 355 356 /** @} */ 357 358 /** @defgroup COMP_Exported_Functions_Group3 Peripheral State and Errors functions 359 * @brief COMP control functions 360 * 361 @verbatim 362 =============================================================================== 363 ##### Peripheral State and Errors functions ##### 364 =============================================================================== 365 [..] 366 This subsection provides a set of functions allowing to control the COMP. 367 (+) hal_comp_get_state() API can be helpful to check in run-time the state of the COMP peripheral. 368 (+) hal_comp_get_error() check in run-time Errors occurring during communication. 369 @endverbatim 370 * @{ 371 */ 372 373 /** 374 **************************************************************************************** 375 * @brief Return the COMP handle state. 376 * 377 * @param[in] p_comp: Pointer to a COMP handle which contains the configuration information for 378 * the specified COMP module. 379 * 380 * @retval ::HAL_COMP_STATE_RESET: Peripheral not initialized. 381 * @retval ::HAL_COMP_STATE_READY: Peripheral initialized and ready for use. 382 * @retval ::HAL_COMP_STATE_BUSY: An internal process is ongoing. 383 * @retval ::HAL_COMP_STATE_ERROR: Peripheral in error. 384 **************************************************************************************** 385 */ 386 hal_comp_state_t hal_comp_get_state(comp_handle_t *p_comp); 387 388 /** 389 **************************************************************************************** 390 * @brief Return the COMP error code. 391 * 392 * @param[in] p_comp: Pointer to a COMP handle which contains the configuration information for 393 * the specified COMP module. 394 * 395 * @return COMP error code in bitmap format 396 **************************************************************************************** 397 */ 398 uint32_t hal_comp_get_error(comp_handle_t *p_comp); 399 400 /** 401 **************************************************************************************** 402 * @brief Suspend some registers related to COMP configuration before sleep. 403 * @param[in] p_comp: Pointer to a COMP handle which contains the configuration 404 * information for the specified COMP module. 405 * @retval ::HAL_OK: Operation is OK. 406 * @retval ::HAL_ERROR: Parameter error or operation not supported. 407 * @retval ::HAL_BUSY: Driver is busy. 408 * @retval ::HAL_TIMEOUT: Timeout occurred. 409 **************************************************************************************** 410 */ 411 hal_status_t hal_comp_suspend_reg(comp_handle_t *p_comp); 412 413 /** 414 **************************************************************************************** 415 * @brief Restore some registers related to COMP configuration after sleep. 416 * This function must be used in conjunction with the hal_comp_suspend_reg(). 417 * @param[in] p_comp: Pointer to a COMP handle which contains the configuration 418 * information for the specified COMP module. 419 * @retval ::HAL_OK: Operation is OK. 420 * @retval ::HAL_ERROR: Parameter error or operation not supported. 421 * @retval ::HAL_BUSY: Driver is busy. 422 * @retval ::HAL_TIMEOUT: Timeout occurred. 423 **************************************************************************************** 424 */ 425 hal_status_t hal_comp_resume_reg(comp_handle_t *p_comp); 426 427 /** @} */ 428 429 /** @} */ 430 431 #ifdef __cplusplus 432 } 433 #endif 434 435 #endif /* __GR55xx_HAL_COMP_H__ */ 436 437 /** @} */ 438 439 /** @} */ 440 441 /** @} */ 442