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 */
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 
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. */
138 
139 /** @} */
140 
141 /** @} */
142 
143 /** @addtogroup HAL_RNG_CALLBACK_STRUCTURES Callback Structures
144  * @{
145  */
146 
147 /** @defgroup HAL_RNG_Callback 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 */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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.
_rng_handle::retention
uint32_t retention[1]
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
Definition: gr55xx_hal_rng.h:107
_rng_handle::lock
hal_lock_t lock
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
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_callback_t
struct _hal_rng_callback hal_rng_callback_t
HAL_RNG Callback function 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. This function must be used in conjun...
HAL_RNG_STATE_RESET
@ HAL_RNG_STATE_RESET
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
Definition: gr55xx_hal_rng.h:104
HAL_RNG_STATE_ERROR
@ HAL_RNG_STATE_ERROR
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)
Definition: gr55xx_hal_rng.h:157
_rng_init::post_mode
uint32_t post_mode
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
Definition: gr55xx_hal_rng.h:78
HAL_RNG_STATE_BUSY
@ HAL_RNG_STATE_BUSY
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
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
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)
Definition: gr55xx_hal_rng.h:159
_rng_init::seed_mode
uint32_t seed_mode
Definition: gr55xx_hal_rng.h:101
_hal_rng_callback::rng_msp_deinit
void(* rng_msp_deinit)(rng_handle_t *p_rng)
Definition: gr55xx_hal_rng.h:158
gr55xx_hal_def.h
This file contains HAL common definitions, enumeration, macros and structures definitions.