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