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