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