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