1 /** 2 **************************************************************************************** 3 * 4 * @file gr55xx_hal_rng.h 5 * @author BLE Driver Team 6 * @brief Header file containing functions prototypes of RNG 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_RNG RNG 47 * @brief RNG HAL module driver. 48 * @{ 49 */ 50 51 /* Define to prevent recursive inclusion -------------------------------------*/ 52 #ifndef __GR55xx_HAL_RNG_H__ 53 #define __GR55xx_HAL_RNG_H__ 54 55 /* Includes ------------------------------------------------------------------*/ 56 #include "gr55xx_ll_rng.h" 57 #include "gr55xx_hal_def.h" 58 59 #ifdef __cplusplus 60 extern "C" { 61 #endif 62 63 /* Exported types ------------------------------------------------------------*/ 64 /** @addtogroup HAL_RNG_ENUMERATIONS Enumerations 65 * @{ 66 */ 67 68 /** @defgroup HAL_RNG_state HAL RNG state 69 * @{ 70 */ 71 72 /** 73 * @brief HAL RNG State Enumerations definition 74 */ 75 typedef enum { 76 HAL_RNG_STATE_RESET = 0x00, /**< RNG not initialized or disabled yet */ 77 HAL_RNG_STATE_READY = 0x01, /**< RNG initialized and ready for use */ 78 HAL_RNG_STATE_BUSY = 0x02, /**< RNG internal process is ongoing */ 79 HAL_RNG_STATE_TIMEOUT = 0x03, /**< RNG timeout state */ 80 HAL_RNG_STATE_ERROR = 0x04 /**< RNG error state */ 81 } hal_rng_state_t; 82 83 /** @} */ 84 85 /** @} */ 86 87 /** @addtogroup HAL_RNG_STRUCTURES Structures 88 * @{ 89 */ 90 91 /** @defgroup RNG_Configuration RNG Configuration 92 * @{ 93 */ 94 95 /** 96 * @brief RNG init structure definition 97 */ 98 typedef struct _rng_init { 99 uint32_t seed_mode; /**< Specifies the seed source for the LFSR. 100 This parameter can be a value of @ref RNG_SEED_SOURCE */ 101 102 uint32_t lfsr_mode; /**< Specifies the configuration mode for the LFSR. 103 This parameter can be a value of @ref RNG_LFSR_MODE */ 104 105 uint32_t out_mode; /**< Specifies the Output mode for the RNG. 106 This parameter can be a value of @ref RNG_OUTPUT_MODE */ 107 108 uint32_t post_mode; /**< Specifies post-process configuration for the RNG. 109 This parameter can be a value of @ref RNG_POST_PRO */ 110 } rng_init_t; 111 112 /** @} */ 113 114 /** @defgroup RNG_handle RNG handle 115 * @{ 116 */ 117 118 /** 119 * @brief RNG handle Structure definition 120 */ 121 typedef struct _rng_handle { 122 rng_regs_t *p_instance; /**< Register base address */ 123 124 rng_init_t init; /**< RNG required parameters */ 125 126 hal_lock_t lock; /**< RNG locking object */ 127 128 __IO hal_rng_state_t state; /*!< RNG communication state */ 129 130 uint32_t random_number; /*!< Last-generated RNG Data */ 131 132 uint32_t retention[1]; /**< RNG important register information. */ 133 } rng_handle_t; 134 135 /** @} */ 136 137 /** @} */ 138 139 /** @addtogroup HAL_RNG_CALLBACK_STRUCTURES Callback Structures 140 * @{ 141 */ 142 143 /** @defgroup HAL_RNG_Callback Callback 144 * @{ 145 */ 146 147 /** 148 * @brief HAL_RNG Callback function definition 149 */ 150 151 typedef struct _hal_rng_callback { 152 void (*rng_msp_init)(rng_handle_t *p_rng); /**< RNG init MSP callback */ 153 void (*rng_msp_deinit)(rng_handle_t *p_rng); /**< RNG de-init MSP callback */ 154 void (*rng_ready_data_callback)(rng_handle_t *p_rng, uint32_t random32bit); /**< RNG data ready callback */ 155 } hal_rng_callback_t; 156 157 /** @} */ 158 159 /** @} */ 160 161 /** 162 * @defgroup HAL_RNG_MACRO Defines 163 * @{ 164 */ 165 166 /* Exported constants --------------------------------------------------------*/ 167 /** @defgroup RNG_Exported_Constants RNG Exported Constants 168 * @{ 169 */ 170 171 /** @defgroup RNG_SEED_SOURCE LFSR seed source 172 * @{ 173 */ 174 #define RNG_SEED_FR0_S0 LL_RNG_SEED_FR0_S0 /**< LFSR seed is from the switching oscillator S0. */ 175 #define RNG_SEED_USER LL_RNG_SEED_USER /**< LFSR seed is configured by users. */ 176 /** @} */ 177 178 179 /** @defgroup RNG_LFSR_MODE LFSR configuration mode 180 * @{ 181 */ 182 #define RNG_LFSR_MODE_59BIT LL_RNG_LFSR_MODE_59BIT /**< 59-bit LFSR. */ 183 #define RNG_LFSR_MODE_128BIT LL_RNG_LFSR_MODE_128BIT /**< 128-bit LFSR. */ 184 /** @} */ 185 186 /** @defgroup RNG_POST_PRO Post-process mode 187 * @{ 188 */ 189 #define RNG_POST_PRO_NOT LL_RNG_POST_PRO_NOT /**< No post process. */ 190 #define RNG_POST_PRO_SKIPPING LL_RNG_POST_PRO_SKIPPING /**< bit skipping. */ 191 #define RNG_POST_PRO_COUNTING LL_RNG_POST_PRO_COUNTING /**< bit counting. */ 192 #define RNG_POST_PRO_NEUMANN LL_RNG_POST_PRO_NEUMANN /**< Von-Neumann. */ 193 /** @} */ 194 195 /** @defgroup RNG_OUTPUT_MODE RNG Output mode 196 * @{ 197 */ 198 #define RNG_OUTPUT_FR0_S0 LL_RNG_OUTPUT_FR0_S0 /**< Digital RNG direct output, 199 for ring oscillator S0 LFSR seed. */ 200 #define RNG_OUTPUT_CYCLIC_PARITY LL_RNG_OUTPUT_CYCLIC_PARITY /**< LFSR and RNG cyclic sampling and 201 parity generation. */ 202 #define RNG_OUTPUT_CYCLIC LL_RNG_OUTPUT_CYCLIC /**< LFSR and RNG cyclic sampling. */ 203 #define RNG_OUTPUT_LFSR_RNG LL_RNG_OUTPUT_LFSR_RNG /**< LFSR ⊕ RNG. */ 204 #define RNG_OUTPUT_LFSR LL_RNG_OUTPUT_LFSR /**< LFSR direct output. */ 205 /** @} */ 206 207 /** @} */ 208 209 /** @} */ 210 211 /* Exported functions --------------------------------------------------------*/ 212 /** @addtogroup HAL_RNG_DRIVER_FUNCTIONS Functions 213 * @{ 214 */ 215 216 /** @addtogroup RNG_Exported_Functions_Group1 Initialization and de-initialization functions 217 * @brief Initialization and de-initialization functions. 218 * 219 @verbatim 220 ============================================================================== 221 ##### Initialization and de-initialization functions ##### 222 ============================================================================== 223 [..] 224 This section provides functions allowing to: 225 (+) Initialize and start the RNG according to the specified parameters 226 in the rng_init_t of associated handle. 227 (+) Initialize the RNG MSP. 228 229 @endverbatim 230 * @{ 231 */ 232 233 /** 234 **************************************************************************************** 235 * @brief Initialize the RNG according to the specified 236 * parameters in the rng_init_t of associated handle. 237 * @param[in] p_rng: Pointer to a RNG handle which contains the configuration 238 * information for the specified RNG module. 239 * @retval ::HAL_OK: Operation is OK. 240 * @retval ::HAL_ERROR: Parameter error or operation not supported. 241 * @retval ::HAL_BUSY: Driver is busy. 242 * @retval ::HAL_TIMEOUT: Timeout occurred. 243 **************************************************************************************** 244 */ 245 hal_status_t hal_rng_init(rng_handle_t *p_rng); 246 247 /** 248 **************************************************************************************** 249 * @brief De-initialize the RNG peripheral. 250 * @param[in] p_rng: RNG handle. 251 * @retval ::HAL_OK: Operation is OK. 252 * @retval ::HAL_ERROR: Parameter error or operation not supported. 253 * @retval ::HAL_BUSY: Driver is busy. 254 * @retval ::HAL_TIMEOUT: Timeout occurred. 255 **************************************************************************************** 256 */ 257 hal_status_t hal_rng_deinit(rng_handle_t *p_rng); 258 259 /** 260 **************************************************************************************** 261 * @brief Initialize the RNG MSP. 262 * @param[in] p_rng: Pointer to a RNG handle which contains the configuration 263 * information for the specified RNG module. 264 * @note When rewriting this function in user file, mechanism may be added 265 * to avoid multiple initialize when hal_rng_init function is called 266 * again to change parameters. 267 **************************************************************************************** 268 */ 269 void hal_rng_msp_init(rng_handle_t *p_rng); 270 271 /** 272 **************************************************************************************** 273 * @brief De-initialize the RNG MSP. 274 * @param[in] p_rng: Pointer to a RNG handle which contains the configuration 275 * information for the specified RNG module. 276 * @note When rewriting this function in user file, mechanism may be added 277 * to avoid multiple initialize when hal_rng_init function is called 278 * again to change parameters. 279 **************************************************************************************** 280 */ 281 void hal_rng_msp_deinit(rng_handle_t *p_rng); 282 283 /** @} */ 284 285 /** @addtogroup RNG_Exported_Functions_Group2 Peripheral Control functions 286 * @brief Peripheral Control functions 287 * 288 @verbatim 289 ============================================================================== 290 ##### Peripheral Control functions ##### 291 ============================================================================== 292 [..] 293 This section provides functions allowing to: 294 (+) Generate Random Number. 295 (+) Handle RNG interrupt request and associated function callback. 296 297 @endverbatim 298 * @{ 299 */ 300 301 /** 302 **************************************************************************************** 303 * @brief Generate a 32-bit random number. 304 * @param[in] p_rng: Pointer to a RNG handle which contains the configuration 305 * information for the specified RNG module. 306 * @param[in] p_seed: user configured seeds. the seed is valid when seed_mode member of 307 * rng_init_t is configured as RNG_SEED_USER. If 59-bit random number is 308 * selected, the seed need to provide [0~58] bit spaces. If 128-bit random 309 * number is selected, the seed need to provide [0~127] bit spaces. 310 * @param[out] p_random32bit: Pointer to generated random number variable if successful. 311 * @retval ::HAL_OK: Operation is OK. 312 * @retval ::HAL_ERROR: Parameter error or operation not supported. 313 * @retval ::HAL_BUSY: Driver is busy. 314 * @retval ::HAL_TIMEOUT: Timeout occurred. 315 **************************************************************************************** 316 */ 317 hal_status_t hal_rng_generate_random_number(rng_handle_t *p_rng, uint16_t *p_seed, uint32_t *p_random32bit); 318 319 /** 320 **************************************************************************************** 321 * @brief Generate a 32-bit random number in interrupt mode. 322 * @param[in] p_rng: Pointer to a RNG handle which contains the configuration 323 * information for the specified RNG module. 324 * @param[in] p_seed: user configured seeds. the seed is valid when seed_mode member of 325 * rng_init_t is configured as RNG_SEED_USER. If 59-bit random number is 326 * selected, the seed need to provide [0~58] bit spaces. If 128-bit random 327 * number is selected, the seed need to provide [0~127] bit spaces. 328 * @retval ::HAL_OK: Operation is OK. 329 * @retval ::HAL_ERROR: Parameter error or operation not supported. 330 * @retval ::HAL_BUSY: Driver is busy. 331 * @retval ::HAL_TIMEOUT: Timeout occurred. 332 **************************************************************************************** 333 */ 334 hal_status_t hal_rng_generate_random_number_it(rng_handle_t *p_rng, uint16_t *p_seed); 335 336 /** 337 **************************************************************************************** 338 * @brief Read the latest generated random number. 339 * @param[in] p_rng: Pointer to a RNG handle which contains the configuration 340 * information for the specified RNG module. 341 * @retval random value. 342 **************************************************************************************** 343 */ 344 uint32_t hal_rng_read_last_random_number(rng_handle_t *p_rng); 345 346 /** @} */ 347 348 /** @addtogroup RNG_IRQ_Handler_and_Callbacks IRQ Handler and Callbacks 349 * @brief IRQ Handler and Callback functions 350 * @{ 351 */ 352 /** 353 **************************************************************************************** 354 * @brief Handle RNG interrupt request. 355 * @param[in] p_rng: RNG handle. 356 **************************************************************************************** 357 */ 358 void hal_rng_irq_handler(rng_handle_t *p_rng); 359 360 /** 361 **************************************************************************************** 362 * @brief Data Ready callback in non-blocking mode. 363 * @note This function should not be modified. When the callback is needed, 364 the hal_rng_ready_data_callback can be implemented in the user file. 365 * @param[in] p_rng: Pointer to a RNG handle which contains the configuration 366 * information for the specified RNG module. 367 * @param random32bit: generated random value 368 * @retval None 369 **************************************************************************************** 370 */ 371 void hal_rng_ready_data_callback(rng_handle_t *p_rng, uint32_t random32bit); 372 373 /** @} */ 374 375 /** @defgroup RNG_Exported_Functions_Group3 Peripheral State functions 376 * @brief RNG State functions 377 * 378 @verbatim 379 =============================================================================== 380 ##### Peripheral State functions ##### 381 =============================================================================== 382 [..] 383 This subsection provides a set of functions allowing to control the RNG. 384 (+) hal_rng_get_state() API can be helpful to check in run-time the state of the RNG peripheral. 385 @endverbatim 386 * @{ 387 */ 388 /** 389 **************************************************************************************** 390 * @brief Return the RNG handle state. 391 * @param[in] p_rng: Pointer to a RNG handle which contains the configuration information 392 * for the specified HMAC module. 393 * @retval ::HAL_RNG_STATE_RESET: Peripheral not initialized. 394 * @retval ::HAL_RNG_STATE_READY: Peripheral initialized and ready for use. 395 * @retval ::HAL_RNG_STATE_BUSY: Peripheral in indirect mode and busy. 396 * @retval ::HAL_RNG_STATE_ERROR: Peripheral in error. 397 * @retval ::HAL_RNG_STATE_TIMEOUT: Peripheral in timeout. 398 **************************************************************************************** 399 */ 400 hal_rng_state_t hal_rng_get_state(rng_handle_t *p_rng); 401 402 /** 403 **************************************************************************************** 404 * @brief Suspend some registers related to RNG configuration before sleep. 405 * @param[in] p_rng: Pointer to a RNG handle which contains the configuration 406 * information for the specified RNG module. 407 * @retval ::HAL_OK: Operation is OK. 408 * @retval ::HAL_ERROR: Parameter error or operation not supported. 409 * @retval ::HAL_BUSY: Driver is busy. 410 * @retval ::HAL_TIMEOUT: Timeout occurred. 411 **************************************************************************************** 412 */ 413 hal_status_t hal_rng_suspend_reg(rng_handle_t *p_rng); 414 415 /** 416 **************************************************************************************** 417 * @brief Restore some registers related to RNG configuration after sleep. 418 * This function must be used in conjunction with the hal_rng_resume_reg(). 419 * @param[in] p_rng: Pointer to a RNG handle which contains the configuration 420 * information for the specified RNG module. 421 * @retval ::HAL_OK: Operation is OK. 422 * @retval ::HAL_ERROR: Parameter error or operation not supported. 423 * @retval ::HAL_BUSY: Driver is busy. 424 * @retval ::HAL_TIMEOUT: Timeout occurred. 425 **************************************************************************************** 426 */ 427 hal_status_t hal_rng_resume_reg(rng_handle_t *p_rng); 428 429 /** @} */ 430 431 /** @} */ 432 433 #ifdef __cplusplus 434 } 435 #endif 436 437 #endif /* __GR55xx_HAL_RNG_H__ */ 438 439 /** @} */ 440 441 /** @} */ 442 443 /** @} */ 444