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 */
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  */
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 
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 */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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
Definition: gr55xx_hal_comp.h:80
_comp_handle::retention
uint32_t retention[1]
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)
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. This function must be used in conju...
_comp_callback::comp_trigger_callback
void(* comp_trigger_callback)(comp_handle_t *p_comp)
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)
Definition: gr55xx_hal_comp.h:138
_comp_handle::error_code
__IO uint32_t 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
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
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
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
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
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
Definition: gr55xx_hal_comp.h:114