Goodix
GR551x API Reference  V1_6_06_B5676
gr55xx_hal.h
Go to the documentation of this file.
1 /**
2  ****************************************************************************************
3  *
4  * @file gr55xx_hal.h
5  * @author BLE Driver Team
6  * @brief This file contains all the functions prototypes for the HAL
7  * module driver.
8  *
9  ****************************************************************************************
10  * @attention
11  #####Copyright (c) 2019 GOODIX
12  All rights reserved.
13 
14  Redistribution and use in source and binary forms, with or without
15  modification, are permitted provided that the following conditions are met:
16  * Redistributions of source code must retain the above copyright
17  notice, this list of conditions and the following disclaimer.
18  * Redistributions in binary form must reproduce the above copyright
19  notice, this list of conditions and the following disclaimer in the
20  documentation and/or other materials provided with the distribution.
21  * Neither the name of GOODIX nor the names of its contributors may be used
22  to endorse or promote products derived from this software without
23  specific prior written permission.
24 
25  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
26  AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
27  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
28  ARE DISCLAIMED. IN NO EVENT SHALL COPYRIGHT HOLDERS AND CONTRIBUTORS BE
29  LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
30  CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
31  SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
32  INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
33  CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
34  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
35  POSSIBILITY OF SUCH DAMAGE.
36  ****************************************************************************************
37  */
38 
39 /** @addtogroup PERIPHERAL Peripheral Driver
40  * @{
41  */
42 
43 /** @addtogroup HAL_DRIVER HAL Driver
44  * @{
45  */
46 
47 /** @defgroup HAL_HAL HAL
48  * @brief HAL module driver.
49  * @{
50  */
51 
52 /* Define to prevent recursive inclusion -------------------------------------*/
53 #ifndef __GR55xx_HAL_H__
54 #define __GR55xx_HAL_H__
55 
56 #ifdef __cplusplus
57 extern "C" {
58 #endif
59 
60 /* Includes ------------------------------------------------------------------*/
61 #include "gr55xx.h"
62 #include "gr55xx_hal_conf.h"
63 #include "gr55xx_delay.h"
64 
65 /** @addtogroup HAL_HAL_CALLBACK_STRUCTURES Callback Structures
66  * @{
67  */
68 
69 /** @defgroup HAL_HAL_Callback Callback
70  * @{
71  */
72 
73 /**
74  * @brief HAL_HAL Callback function definition
75  */
76 
77 typedef struct _hal_callback
78 {
79  void (*msp_init)(void); /**< HAL init MSP callback */
80  void (*msp_deinit)(void); /**< HAL de-init MSP callback */
82 
83 /** @} */
84 
85 /** @} */
86 
87 /**
88  * @defgroup HAL_MACRO Defines
89  * @{
90  */
91 
92 /* Private macros ------------------------------------------------------------*/
93 /* Exported macros ------------------------------------------------------------*/
94 /** @defgroup HAL_Exported_Constants HAL Exported Constants
95  * @{
96  */
97 
98 //** @brief Disable interrupts globally in the system(apart from the NMI).
99 // * This macro must be used in conjunction with the @ref GLOBAL_EXCEPTION_ENABLE macro
100 // * since this last one will close the brace that the current macro opens. This means
101 // * that both macros must be located at the same scope level.
102 // */
103 //#define GLOBAL_EXCEPTION_DISABLE() \
104 //do { \
105 // uint32_t __l_irq_rest = __get_PRIMASK(); \
106 // __set_PRIMASK(1)
107 
108 
109 //** @brief Restore interrupts from the previous global disable(apart from the NMI).
110 // * @sa GLOBAL_EXCEPTION_ENABLE
111 // */
112 //#define GLOBAL_EXCEPTION_ENABLE() \
113 // if(__l_irq_rest == 0) \
114 // { \
115 // __set_PRIMASK(0); \
116 // } \
117 // else \
118 // { \
119 // __set_PRIMASK(1); \
120 // } \
121 //} while(0)
122 
123 /** @brief compare if a > b
124  * @sa CO_MAX
125  */
126 #define CO_MAX(a,b) ((a) > (b) ? (a) : (b))
127 
128 /** @brief Disable BLE_IRQn and BLESLP_IRQn.
129  * @sa BLE_INT_DISABLE
130  */
131 #define BLE_INT_DISABLE() \
132 do { \
133  extern volatile uint32_t g_ble_irq_disable_cnt; \
134  extern volatile uint32_t g_max_ble_irq_disable_depth; \
135  extern volatile uint32_t g_ble_irq_enable_status; \
136  extern volatile uint32_t g_ble_slp_irq_enable_status; \
137  volatile uint32_t __ble_l_irq_rest = __get_PRIMASK(); \
138  __set_PRIMASK(1); \
139  if(g_ble_irq_disable_cnt == 0) \
140  { \
141  g_ble_irq_enable_status = NVIC_GetEnableIRQ(BLE_IRQn); \
142  g_ble_slp_irq_enable_status = NVIC_GetEnableIRQ(BLESLP_IRQn); \
143  if (g_ble_irq_enable_status) \
144  { \
145  NVIC_DisableIRQ(BLE_IRQn); \
146  } \
147  if (g_ble_slp_irq_enable_status) \
148  { \
149  NVIC_DisableIRQ(BLESLP_IRQn); \
150  } \
151  } \
152  g_ble_irq_disable_cnt++; \
153  g_max_ble_irq_disable_depth = CO_MAX(g_max_ble_irq_disable_depth, g_ble_irq_disable_cnt); \
154  __set_PRIMASK(__ble_l_irq_rest);
155 
156 /** @brief Restore BLE_IRQn and BLESLP_IRQn.
157  * @sa BLE_INT_RESTORE
158  */
159 #define BLE_INT_RESTORE() \
160  __ble_l_irq_rest = __get_PRIMASK(); \
161  __set_PRIMASK(1); \
162  g_ble_irq_disable_cnt--; \
163  if(g_ble_irq_disable_cnt == 0) \
164  { \
165  if (g_ble_irq_enable_status) \
166  { \
167  NVIC_EnableIRQ(BLE_IRQn); \
168  } \
169  if (g_ble_slp_irq_enable_status) \
170  { \
171  NVIC_EnableIRQ(BLESLP_IRQn); \
172  } \
173  } \
174  __set_PRIMASK(__ble_l_irq_rest); \
175 } while(0)
176 
177 /** @brief Disable external interrupts(Exception Type: 16~255) in the system.
178  * This macro must be used in conjunction with the @ref GLOBAL_INT_RESTORE macro
179  * since the latter one will close the brace that the former one opens. This
180  * means that both macros must be located at the same scope level.
181  */
182 #define GLOBAL_INT_DISABLE() \
183 do { \
184  uint32_t __nvic_iser0; \
185  uint32_t __nvic_iser1; \
186  __nvic_iser0 = NVIC->ISER[0]; \
187  __nvic_iser1 = NVIC->ISER[1]; \
188  NVIC->ICER[0] = 0xFFFFFFFF; \
189  NVIC->ICER[1] = 0xFFFFFFFF; \
190  __DSB(); \
191  __ISB(); \
192 
193 /** @brief Restore external interrupts(Exception Type: 16~255) from the previous disable.
194  * @sa GLOBAL_INT_RESTORE
195  */
196 #define GLOBAL_INT_RESTORE() \
197  NVIC->ISER[0] = __nvic_iser0; \
198  NVIC->ISER[1] = __nvic_iser1; \
199 } while(0)
200 
201 /** @brief Disable external interrupts with a priority lower than IRQn_Type in the system.
202  * This macro must be used in conjunction with the @ref LOCAL_INT_RESTORE macro
203  * since this last one will close the brace that the current macro opens. This
204  * means that both macros must be located at the same scope level.
205  */
206 #define LOCAL_INT_DISABLE(IRQn_Type) \
207 do { \
208  uint32_t __l_irq_rest = __get_BASEPRI(); \
209  __set_BASEPRI(NVIC_GetPriority(IRQn_Type) + \
210  (1 << (NVIC_GetPriorityGrouping() + 1))); \
211 
212 /** @brief Restore external interrupts(apart from the BLE) from the previous disable.
213  * @sa EXP_BLE_INT_RESTORE
214  */
215 #define LOCAL_INT_RESTORE() \
216  __set_BASEPRI(__l_irq_rest); \
217 } while(0)
218 
219 
220 /** @brief Check if the program is running on the FPGA platform.
221  */
222 #define CHECK_IS_ON_FPGA() (AON->FPGA_CTRL & AON_REG_FPGA_CTRL_EXIST)
223 
224 #define SYSTICK_RELOAD_VALUE (SysTick->LOAD) /**< SysTick Reload value. */
225 #define SYSTICK_CURRENT_VALUE (SysTick->VAL) /**< SysTick Current value. */
226 
227 /** @} */
228 
229 /** @} */
230 
231 /* Exported types ------------------------------------------------------------*/
232 /* Exported constants --------------------------------------------------------*/
233 /* Exported functions --------------------------------------------------------*/
234 /** @addtogroup HAL_HAL_DRIVER_FUNCTIONS Functions
235  * @{
236  */
237 
238 /** @addtogroup HAL_Exported_Functions_Group1 Initialization and De-initialization Functions
239  * @brief Initialization and de-initialization functions
240  *
241 @verbatim
242  ===============================================================================
243  ##### Initialization and de-initialization functions #####
244  ===============================================================================
245  [..] This section provides functions allowing to:
246  (+) Initialize the Flash interface, the NVIC allocation and initial clock
247  configuration. It also initializes the source of time base when timeout
248  is needed.
249  (+) De-initialize common part of the HAL.
250  (+) Configure The time base source to have 1ms time base with a dedicated
251  Tick interrupt priority.
252  (++) SysTick timer is used by default as source of time base, but user can
253  eventually implement his or her proper time base source (a general purpose
254  timer for example or other time source), keeping in mind that Time base
255  duration should be kept as 1ms since PPP_TIMEOUT_VALUEs are defined and
256  handled in milliseconds basis.
257  (++) Time base configuration function (hal_init_tick()) is called automatically
258  at the beginning of the program after reset by hal_init().
259  (++) Source of time base is configured to generate interrupts at regular
260  time intervals. Care must be taken if hal_delay() is called from a
261  peripheral ISR process, the Tick interrupt line must have higher priority
262  (numerically lower) than the peripheral interrupt. Otherwise the caller
263  ISR process will be blocked.
264  (++) Functions affecting time base configurations are declared as __Weak
265  to make override possible in case of other implementations in user file.
266 
267 @endverbatim
268  * @{
269  */
270 
271 /**
272  ****************************************************************************************
273  * @brief This function configures time base source, NVIC and Low level hardware.
274  *
275  * @note This function is called at the beginning of program after reset and before
276  * the clock configuration.
277  * The SysTick configuration is based on AHB clock and the NVIC configuration
278  * is set to Priority group 4.
279  * When the time base configuration is done, time base tick starts incrementing.
280  * In the default implementation, SysTick is used as source of time base.
281  * The tick variable is incremented each 1ms in its ISR.
282  *
283  * @retval ::HAL_OK: Operation is OK.
284  * @retval ::HAL_ERROR: Parameter error or operation not supported.
285  * @retval ::HAL_BUSY: Driver is busy.
286  * @retval ::HAL_TIMEOUT: Timeout occurred.
287  ****************************************************************************************
288  */
290 
291 /**
292  ****************************************************************************************
293  * @brief This function de-initializes common part of the HAL and stops the source
294  * of time base.
295  *
296  * @note This function is optional.
297  *
298  * @retval ::HAL_OK: Operation is OK.
299  * @retval ::HAL_ERROR: Parameter error or operation not supported.
300  * @retval ::HAL_BUSY: Driver is busy.
301  * @retval ::HAL_TIMEOUT: Timeout occurred.
302  ****************************************************************************************
303  */
305 
306 /**
307  ****************************************************************************************
308  * @brief Initialize the MSP.
309  *
310  * @note This function should not be modified. When the callback is needed,
311  * the hal_msp_init could be implemented in the user file.
312  ****************************************************************************************
313  */
314 void hal_msp_init(void);
315 
316 /**
317  ****************************************************************************************
318  * @brief De-initialize the MSP.
319  *
320  * @note This function should not be modified. When the callback is needed,
321  * the hal_msp_deinit could be implemented in the user file.
322  ****************************************************************************************
323  */
324 void hal_msp_deinit(void);
325 
326 /**
327  ****************************************************************************************
328  * @brief This function configures the source of the time base.
329  *
330  * @param[in] tick_priority: Tick interrupt priority.
331  *
332  * @retval ::HAL_OK: Operation is OK.
333  * @retval ::HAL_ERROR: Parameter error or operation not supported.
334  * @retval ::HAL_BUSY: Driver is busy.
335  * @retval ::HAL_TIMEOUT: Timeout occurred.
336  ****************************************************************************************
337  */
338 hal_status_t hal_init_tick (uint32_t tick_priority);
339 
340 /** @} */
341 
342 /** @addtogroup HAL_Exported_Functions_Group2 HAL Control functions
343  * @brief HAL Control functions
344  *
345 @verbatim
346  ===============================================================================
347  ##### HAL Control functions #####
348  ===============================================================================
349  [..] This section provides functions allowing to:
350  (+) Suspend the time base source interrupt
351  (+) Resume the time base source interrupt
352  (+) Get the HAL API driver version
353 
354 @endverbatim
355  * @{
356  */
357 
358 /**
359  ****************************************************************************************
360  * @brief Suspend Tick increment.
361  *
362  * @note In the default implementation , SysTick timer is the source of time base. It is
363  * used to generate interrupts at regular time intervals. Once hal_suspend_tick()
364  * is called, the SysTick interrupt will be disabled so Tick increment
365  * is suspended.
366  * This function is declared as __WEAK to be overwritten in case of other
367  * implementations in user file.
368  ****************************************************************************************
369  */
370 void hal_suspend_tick(void);
371 
372 /**
373  ****************************************************************************************
374  * @brief Resume Tick increment.
375  *
376  * @note In the default implementation , SysTick timer is the source of time base. It is
377  * used to generate interrupts at regular time intervals. Once hal_resume_tick()
378  * is called, the SysTick interrupt will be enabled so Tick increment
379  * is resumed.
380  * The function is declared as __WEAK to be overwritten in case of other
381  * implementations in user file.
382  ****************************************************************************************
383  */
384 void hal_resume_tick(void);
385 
386 /**
387  ****************************************************************************************
388  * @brief This function returns the HAL revision
389  *
390  * @return version: 0xXYZR (8 bits for each decimal, R for RC)
391  ****************************************************************************************
392  */
393 uint32_t hal_get_hal_version(void);
394 
395 /** @} */
396 
397 /** @} */
398 
399 #ifdef __cplusplus
400 }
401 #endif
402 
403 #endif /* __GR55xx_HAL_H__ */
404 
405 /** @} */
406 
407 /** @} */
408 
409 /** @} */
_hal_callback::msp_deinit
void(* msp_deinit)(void)
HAL de-init MSP callback
Definition: gr55xx_hal.h:80
gr55xx_delay.h
PERIPHERAL API DELAY DRIVER.
hal_init
hal_status_t hal_init(void)
This function configures time base source, NVIC and Low level hardware.
hal_get_hal_version
uint32_t hal_get_hal_version(void)
This function returns the HAL revision.
hal_callback_t
struct _hal_callback hal_callback_t
HAL_HAL Callback function definition.
hal_suspend_tick
void hal_suspend_tick(void)
Suspend Tick increment.
hal_deinit
hal_status_t hal_deinit(void)
This function de-initializes common part of the HAL and stops the source of time base.
hal_resume_tick
void hal_resume_tick(void)
Resume Tick increment.
hal_status_t
hal_status_t
HAL Status structures definition.
Definition: gr55xx_hal_def.h:70
_hal_callback
HAL_HAL Callback function definition.
Definition: gr55xx_hal.h:78
hal_init_tick
hal_status_t hal_init_tick(uint32_t tick_priority)
This function configures the source of the time base.
_hal_callback::msp_init
void(* msp_init)(void)
HAL init MSP callback
Definition: gr55xx_hal.h:79
hal_msp_init
void hal_msp_init(void)
Initialize the MSP.
hal_msp_deinit
void hal_msp_deinit(void)
De-initialize the MSP.
gr55xx_hal_conf.h
HAL configuration file.