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 /**
66 * @defgroup HAL_MACRO Defines
67 * @{
68 */
69
70 /* Private macros ------------------------------------------------------------*/
71 /* Exported macros ------------------------------------------------------------*/
72 /** @defgroup HAL_Exported_Constants HAL Exported Constants
73 * @{
74 */
75
76 /** @brief Disable interrupts globally in the system(apart from the NMI).
77 * This macro must be used in conjunction with the @ref GLOBAL_EXCEPTION_ENABLE macro
78 * since this last one will close the brace that the current macro opens. This means
79 * that both macros must be located at the same scope level.
80 */
81 #define GLOBAL_EXCEPTION_DISABLE() \
82 do { \
83 uint32_t __l_irq_rest = __get_PRIMASK(); \
84 __set_PRIMASK(1)
85
86
87 /** @brief Restore interrupts from the previous global disable(apart from the NMI).
88 * @sa GLOBAL_EXCEPTION_ENABLE
89 */
90 #define GLOBAL_EXCEPTION_ENABLE() \
91 __set_PRIMASK(__l_irq_rest); \
92 } while(0)
93
94 /** @brief Disable interrupts globally in the system.
95 * This macro must be used in conjunction with the @ref GLOBAL_INT_RESTORE macro.
96 */
97 #define GLOBAL_INT_DISABLE() \
98 do { \
99 extern uint32_t global_int_disable(void); \
100 uint32_t __res_mask = global_int_disable()
101
102 /** @brief Restore global interrupt.
103 * @sa GLOBAL_INT_RESTORE
104 */
105 #define GLOBAL_INT_RESTORE() \
106 extern void global_int_enable(uint32_t mask); \
107 global_int_enable(__res_mask); \
108 } while(0)
109
110
111 /** @brief Disable external interrupts with a priority lower than IRQn_Type in the system.
112 * This macro must be used in conjunction with the @ref LOCAL_INT_RESTORE macro
113 * since this last one will close the brace that the current macro opens. This
114 * means that both macros must be located at the same scope level.
115 */
116 #define LOCAL_INT_DISABLE(IRQn_Type) \
117 do { \
118 uint32_t __l_irq_rest = __get_BASEPRI(); \
119 __set_BASEPRI(NVIC_GetPriority(IRQn_Type) + \
120 (1 << (NVIC_GetPriorityGrouping() + 1))); \
121
122 /** @brief Restore external interrupts(apart from the BLE) from the previous disable.
123 * @sa EXP_BLE_INT_RESTORE
124 */
125 #define LOCAL_INT_RESTORE() \
126 __set_BASEPRI(__l_irq_rest); \
127 } while(0)
128
129
130 /** @brief Check if the program is running on the FPGA platform.
131 */
132 #define CHECK_IS_ON_FPGA() (MCU_SUB->FPGA_CTRL & MCU_SUB_FPGA_CTRL_REG_EXIST)
133 #define SYSTICK_RELOAD_VALUE (SysTick->LOAD) /**< SysTick Reload value. */
134 #define SYSTICK_CURRENT_VALUE (SysTick->VAL) /**< SysTick Current value. */
135
136 /** @} */
137
138 /** @} */
139
140 /* Exported types ------------------------------------------------------------*/
141 /* Exported constants --------------------------------------------------------*/
142 /* Exported functions --------------------------------------------------------*/
143 /** @addtogroup HAL_HAL_DRIVER_FUNCTIONS Functions
144 * @{
145 */
146
147 /** @addtogroup HAL_Exported_Functions_Group1 Initialization and De-initialization Functions
148 * @brief Initialization and de-initialization functions
149 *
150 @verbatim
151 ===============================================================================
152 ##### Initialization and de-initialization functions #####
153 ===============================================================================
154 [..] This section provides functions allowing to:
155 (+) Initialize the Flash interface, the NVIC allocation and initial clock
156 configuration. It also initializes the source of time base when timeout
157 is needed.
158 (+) De-initialize common part of the HAL.
159 (+) Configure The time base source to have 1ms time base with a dedicated
160 Tick interrupt priority.
161 (++) SysTick timer is used by default as source of time base, but user can
162 eventually implement his or her proper time base source (a general purpose
163 timer for example or other time source), keeping in mind that Time base
164 duration should be kept as 1ms since PPP_TIMEOUT_VALUEs are defined and
165 handled in milliseconds basis.
166 (++) Time base configuration function (hal_init_tick()) is called automatically
167 at the beginning of the program after reset by hal_init().
168 (++) Source of time base is configured to generate interrupts at regular
169 time intervals. Care must be taken if hal_delay() is called from a
170 peripheral ISR process, the Tick interrupt line must have higher priority
171 (numerically lower) than the peripheral interrupt. Otherwise the caller
172 ISR process will be blocked.
173 (++) Functions affecting time base configurations are declared as __Weak
174 to make override possible in case of other implementations in user file.
175
176 @endverbatim
177 * @{
178 */
179
180 /**
181 ****************************************************************************************
182 * @brief This function configures time base source, NVIC and Low level hardware.
183 *
184 * @note This function is called at the beginning of program after reset and before
185 * the clock configuration.
186 * The SysTick configuration is based on AHB clock.
187 * When the time base configuration is done, time base tick starts incrementing.
188 * In the default implementation, SysTick is used as source of time base.
189 * The tick variable is incremented each 1ms in its ISR.
190 *
191 * @retval ::HAL_OK: Operation is OK.
192 * @retval ::HAL_ERROR: Parameter error or operation not supported.
193 * @retval ::HAL_BUSY: Driver is busy.
194 * @retval ::HAL_TIMEOUT: Timeout occurred.
195 ****************************************************************************************
196 */
197 hal_status_t hal_init(void);
198
199 /**
200 ****************************************************************************************
201 * @brief This function de-initializes common part of the HAL and stops the source
202 * of time base.
203 *
204 * @note This function is optional.
205 *
206 * @retval ::HAL_OK: Operation is OK.
207 * @retval ::HAL_ERROR: Parameter error or operation not supported.
208 * @retval ::HAL_BUSY: Driver is busy.
209 * @retval ::HAL_TIMEOUT: Timeout occurred.
210 ****************************************************************************************
211 */
212 hal_status_t hal_deinit(void);
213
214 /**
215 ****************************************************************************************
216 * @brief Initialize the MSP.
217 *
218 * @note This function should not be modified. When the callback is needed,
219 * the hal_msp_init could be implemented in the user file.
220 ****************************************************************************************
221 */
222 void hal_msp_init(void);
223
224 /**
225 ****************************************************************************************
226 * @brief De-initialize the MSP.
227 *
228 * @note This function should not be modified. When the callback is needed,
229 * the hal_msp_deinit could be implemented in the user file.
230 ****************************************************************************************
231 */
232 void hal_msp_deinit(void);
233
234 /** @} */
235
236 /** @addtogroup HAL_IRQ_Handler_and_Callbacks IRQ Handler and Callbacks
237 * @brief IRQ Handler and Callbacks functions.
238 * @{
239 */
240
241 /**
242 ****************************************************************************************
243 * @brief This function handles SYSTICK interrupt request.
244 ****************************************************************************************
245 */
246 void hal_systick_irq_handler(void);
247
248 /**
249 ****************************************************************************************
250 * @brief SYSTICK callback.
251 *
252 * @note This function should not be modified. When the callback is needed,
253 * the hal_systick_callback can be implemented in the user file.
254 ****************************************************************************************
255 */
256 void hal_systick_callback(void);
257
258 /** @} */
259
260
261 /** @addtogroup HAL_Exported_Functions_Group2 HAL Control functions
262 * @brief HAL Control functions
263 *
264 @verbatim
265 ===============================================================================
266 ##### HAL Control functions #####
267 ===============================================================================
268 [..] This section provides functions allowing to:
269 (+) Provide a tick value in millisecond
270 (+) Provide a blocking delay in millisecond
271 (+) Suspend the time base source interrupt
272 (+) Resume the time base source interrupt
273 (+) Get the HAL API driver version
274
275 @endverbatim
276 * @{
277 */
278
279 /**
280 ****************************************************************************************
281 * @brief This function is called to increment a global variable "g_tick"
282 * used as application time base.
283 *
284 * @note In the default implementation, this variable is incremented by 1 each 1ms
285 * in Systick ISR.
286 * This function is declared as __WEAK to be overwritten in case of other
287 * implementations in user file.
288 ****************************************************************************************
289 */
290 void hal_increment_tick(void);
291
292 /**
293 ****************************************************************************************
294 * @brief Povides a tick value in millisecond.
295 *
296 * @note The function is declared as __WEAK to be overwritten in case of other
297 * implementations in user file.
298 *
299 * @return Tick value
300 ****************************************************************************************
301 */
302 uint32_t hal_get_tick(void);
303
304 /**
305 ****************************************************************************************
306 * @brief This function provides accurate delay (in milliseconds) based
307 * on variable incremented.
308 *
309 * @note In the default implementation , SysTick timer is the source of time base.
310 * It is used to generate interrupts at regular time intervals where g_tick
311 * is incremented.
312 * The function is declared as __WEAK to be overwritten in case of other
313 * implementations in user file.
314 *
315 * @param[in] delay: Specify the delay time length, in milliseconds.
316 ****************************************************************************************
317 */
318 void hal_delay(__IO uint32_t delay);
319
320 /**
321 ****************************************************************************************
322 * @brief Suspend Tick increment.
323 *
324 * @note In the default implementation , SysTick timer is the source of time base. It is
325 * used to generate interrupts at regular time intervals. Once hal_suspend_tick()
326 * is called, the SysTick interrupt will be disabled and so Tick increment
327 * is suspended.
328 * This function is declared as __WEAK to be overwritten in case of other
329 * implementations in user file.
330 ****************************************************************************************
331 */
332 void hal_suspend_tick(void);
333
334 /**
335 ****************************************************************************************
336 * @brief Resume Tick increment.
337 *
338 * @note In the default implementation , SysTick timer is the source of time base. It is
339 * used to generate interrupts at regular time intervals. Once hal_resume_tick()
340 * is called, the SysTick interrupt will be enabled and so Tick increment
341 * is resumed.
342 * The function is declared as __WEAK to be overwritten in case of other
343 * implementations in user file.
344 ****************************************************************************************
345 */
346 void hal_resume_tick(void);
347
348 /**
349 ****************************************************************************************
350 * @brief This function returns the HAL revision
351 *
352 * @return version: 0xXYZR (8 bits for each decimal, R for RC)
353 ****************************************************************************************
354 */
355 uint32_t hal_get_hal_version(void);
356
357 /**
358 ****************************************************************************************
359 * @brief This function enable the DWT function
360 * @param[in] _demcr_initial: Enable register
361 * @param[in] _dwt_ctrl_initial: Control register
362 * @return none
363 ****************************************************************************************
364 */
365 void hal_dwt_enable(uint32_t _demcr_initial, uint32_t _dwt_ctrl_initial);
366
367 /**
368 ****************************************************************************************
369 * @brief This function disable the DWT function
370 * @param[in] _demcr_initial: Enable register
371 * @param[in] _dwt_ctrl_initial: Control register
372 * @return none
373 ****************************************************************************************
374 */
375 void hal_dwt_disable(uint32_t _demcr_initial, uint32_t _dwt_ctrl_initial);
376
377
378 /** @} */
379
380 /** @} */
381
382 #ifdef __cplusplus
383 }
384 #endif
385
386 #endif /* __GR55xx_HAL_H__ */
387
388 /** @} */
389
390 /** @} */
391
392 /** @} */
hal_dwt_disable
void hal_dwt_disable(uint32_t _demcr_initial, uint32_t _dwt_ctrl_initial)
This function disable the DWT function.
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_delay
void hal_delay(__IO uint32_t delay)
This function provides accurate delay (in milliseconds) based on variable incremented.
hal_get_hal_version
uint32_t hal_get_hal_version(void)
This function returns the HAL revision.
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_dwt_enable
void hal_dwt_enable(uint32_t _demcr_initial, uint32_t _dwt_ctrl_initial)
This function enable the DWT function.
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_systick_irq_handler
void hal_systick_irq_handler(void)
This function handles SYSTICK interrupt request.
hal_msp_init
void hal_msp_init(void)
Initialize the MSP.
hal_increment_tick
void hal_increment_tick(void)
This function is called to increment a global variable "g_tick" used as application time base.
hal_msp_deinit
void hal_msp_deinit(void)
De-initialize the MSP.
gr55xx_hal_conf.h
HAL configuration file.
hal_systick_callback
void hal_systick_callback(void)
SYSTICK callback.
hal_get_tick
uint32_t hal_get_tick(void)
Povides a tick value in millisecond.