app_rng.h
Go to the documentation of this file.
1 /**
2 ****************************************************************************************
3 *
4 * @file app_rng.h
5 * @author BLE Driver Team
6 * @brief Header file containing functions prototypes of RNG app 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 APP_DRIVER APP DRIVER
43 * @{
44 */
45
46 /** @defgroup APP_RNG RNG
47 * @brief RNG APP module driver.
48 * @{
49 */
50
51
52 #ifndef _APP_RNG_H_
53 #define _APP_RNG_H_
54
55 #include "grx_hal.h"
56 #include "app_drv_error.h"
57 #include "app_drv_config.h"
58
59 #ifdef __cplusplus
60 extern "C" {
61 #endif
62
63 #ifdef HAL_RNG_MODULE_ENABLED
64
65 /** @addtogroup APP_RNG_ENUM Enumerations
66 * @{
67 */
68
69 /**
70 * @brief RNG operating mode Enumerations definition
71 */
72 typedef enum
73 {
74 APP_RNG_TYPE_INTERRUPT, /**< Interrupt operation mode. */
75 APP_RNG_TYPE_POLLING, /**< Polling operation mode. */
76 APP_RNG_TYPE_MAX /**< Only for check parameter, not used as input parameters. */
77 } app_rng_type_t;
78
79 /**
80 * @brief RNG event Enumerations definition
81 */
82 typedef enum
83 {
84 APP_RNG_EVT_DONE, /**< Generated random by UART peripheral. */
85 APP_RNG_EVT_ERROR, /**< Error reported by UART peripheral. */
86 } app_rng_evt_type_t;
87 /** @} */
88
89 /** @addtogroup HAL_APP_RNG_STRUCTURES Structures
90 * @{
91 */
92 /**
93 * @brief RNG event structure definition
94 */
95 typedef struct
96 {
97 app_rng_evt_type_t type; /**< Type of event. */
98 uint32_t random_data; /**< Random number. */
99 } app_rng_evt_t;
100
101 /** @} */
102
103 /** @addtogroup APP_RNG_TYPEDEFS Type definitions
104 * @{
105 */
106 /**
107 * @brief RNG event callback definition
108 */
109 typedef void (*app_rng_evt_handler_t)(app_rng_evt_t *p_evt);
110
111 /** @} */
112
113 /** @addtogroup APP_RNG_ENUM Enumerations
114 * @{
115 */
116 /**
117 * @brief App rng state types.
118 */
119 typedef enum
120 {
121 APP_RNG_INVALID = 0,
122 APP_RNG_ACTIVITY,
123 #ifdef APP_DRIVER_WAKEUP_CALL_FUN
124 APP_RNG_SLEEP,
125 #endif
126 } app_rng_state_t;
127
128 /** @} */
129
130 /** @addtogroup HAL_APP_RNG_STRUCTURES Structures
131 * @{
132 */
133 /**
134 * @brief RNG device structure definition
135 */
136 typedef struct
137 {
138 app_rng_evt_handler_t evt_handler; /**< RNG event callback. */
139 rng_handle_t handle; /**< RNG handle Structure. */
140 app_rng_type_t use_type; /**< RNG operating mode. */
141 app_rng_state_t rng_state; /**< App rng state types. */
142 } rng_env_t;
143 /**
144 * @brief RNG parameters structure definition
145 */
146 typedef struct
147 {
148 app_rng_type_t use_type; /**< Specifies the operation mode of RNG. */
149 rng_init_t init; /**< RNG required parameters. */
150 rng_env_t rng_env; /**< RNG device structure definition. */
151 } app_rng_params_t;
152
153 /** @} */
154
155 /* Exported functions --------------------------------------------------------*/
156 /** @addtogroup APP_RNG_DRIVER_FUNCTIONS Functions
157 * @{
158 */
159
160 /**
161 ****************************************************************************************
162 * @brief Initialize the APP RNG DRIVER according to the specified parameters
163 * in the app_rng_params_t and app_rng_evt_handler_t.
164 * @note If interrupt mode is set, you can use blocking mode. Conversely, if blocking mode
165 * is set, you can't use interrupt mode.
166 *
167 * @param[in] p_params: Pointer to app_rng_params_t parameter which contains the
168 * configuration information for the specified RNG module.
169 * @param[in] evt_handler: RNG user callback function.
170 *
171 * @return Result of initialization.
172 ****************************************************************************************
173 */
174 uint16_t app_rng_init(app_rng_params_t *p_params, app_rng_evt_handler_t evt_handler);
175
176 /**
177 ****************************************************************************************
178 * @brief De-initialize the APP RNG DRIVER peripheral.
179 *
180 * @return Result of De-initialization.
181 ****************************************************************************************
182 */
183 uint16_t app_rng_deinit(void);
184
185 /**
186 ****************************************************************************************
187 * @brief Generate a 32-bit random number.
188 *
189 * @param[in] p_seed: user configured seeds. the seed is valid when seed_mode member of
190 * rng_init_t is configured as RNG_SEED_USER. If 59-bit random number is
191 * selected, the seed need to provide [0~58] bit spaces. If 128-bit random
192 * number is selected, the seed need to provide [0~127] bit spaces.
193 * @param[out] p_random32bit: Pointer to generated random number variable if successful.
194 *
195 * @return Result of operation.
196 ****************************************************************************************
197 */
198 uint16_t app_rng_gen_sync(uint16_t *p_seed, uint32_t *p_random32bit);
199
200 /**
201 ****************************************************************************************
202 * @brief Generate a 32-bit random number in interrupt mode.
203 *
204 * @param[in] p_seed: user configured seeds. the seed is valid when seed_mode member of
205 * rng_init_t is configured as RNG_SEED_USER. If 59-bit random number is
206 * selected, the seed need to provide [0~58] bit spaces. If 128-bit random
207 * number is selected, the seed need to provide [0~127] bit spaces.
208 *
209 * @return Result of operation.
210 ****************************************************************************************
211 */
212 uint16_t app_rng_gen_async(uint16_t *p_seed);
213
214 /**
215 ****************************************************************************************
216 * @brief Return the RNG handle.
217 *
218 * @return Pointer to the RNG handle.
219 ****************************************************************************************
220 */
221 rng_handle_t *app_rng_get_handle(void);
222
223 /** @} */
224
225 #endif
226
227 #ifdef __cplusplus
228 }
229 #endif
230
231 #endif
232
233 /** @} */
234 /** @} */
235 /** @} */
app_rng_gen_async
uint16_t app_rng_gen_async(uint16_t *p_seed)
Generate a 32-bit random number in interrupt mode.
app_rng_type_t
app_rng_type_t
RNG operating mode Enumerations definition.
Definition: app_rng.h:73
rng_env_t::evt_handler
app_rng_evt_handler_t evt_handler
Definition: app_rng.h:138
app_rng_evt_t::type
app_rng_evt_type_t type
Definition: app_rng.h:97
APP_RNG_EVT_DONE
@ APP_RNG_EVT_DONE
Definition: app_rng.h:84
APP_RNG_TYPE_MAX
@ APP_RNG_TYPE_MAX
Definition: app_rng.h:76
rng_env_t::use_type
app_rng_type_t use_type
Definition: app_rng.h:140
APP_RNG_TYPE_INTERRUPT
@ APP_RNG_TYPE_INTERRUPT
Definition: app_rng.h:74
app_rng_gen_sync
uint16_t app_rng_gen_sync(uint16_t *p_seed, uint32_t *p_random32bit)
Generate a 32-bit random number.
rng_env_t::handle
rng_handle_t handle
Definition: app_rng.h:139
app_rng_params_t
RNG parameters structure definition.
Definition: app_rng.h:147
app_rng_evt_handler_t
void(* app_rng_evt_handler_t)(app_rng_evt_t *p_evt)
RNG event callback definition.
Definition: app_rng.h:109
app_rng_state_t
app_rng_state_t
App rng state types.
Definition: app_rng.h:120
app_rng_evt_t::random_data
uint32_t random_data
Definition: app_rng.h:98
app_rng_deinit
uint16_t app_rng_deinit(void)
De-initialize the APP RNG DRIVER peripheral.
app_rng_evt_type_t
app_rng_evt_type_t
RNG event Enumerations definition.
Definition: app_rng.h:83
app_rng_params_t::init
rng_init_t init
Definition: app_rng.h:149
app_rng_evt_t
RNG event structure definition.
Definition: app_rng.h:96
grx_hal.h
This file contains all the functions prototypes for the HAL module driver.
_rng_handle
RNG handle Structure definition.
Definition: gr55xx_hal_rng.h:125
APP_RNG_EVT_ERROR
@ APP_RNG_EVT_ERROR
Definition: app_rng.h:85
_rng_init
RNG init structure definition.
Definition: gr55xx_hal_rng.h:100
app_rng_get_handle
rng_handle_t * app_rng_get_handle(void)
Return the RNG handle.
APP_RNG_TYPE_POLLING
@ APP_RNG_TYPE_POLLING
Definition: app_rng.h:75
rng_env_t::rng_state
app_rng_state_t rng_state
Definition: app_rng.h:141
rng_env_t
RNG device structure definition.
Definition: app_rng.h:137
app_rng_params_t::use_type
app_rng_type_t use_type
Definition: app_rng.h:148
APP_RNG_INVALID
@ APP_RNG_INVALID
Definition: app_rng.h:121
app_drv_error.h
Header file of app driver error code.
app_drv_config.h
Header file of app driver config code.
app_rng_params_t::rng_env
rng_env_t rng_env
Definition: app_rng.h:150
app_rng_init
uint16_t app_rng_init(app_rng_params_t *p_params, app_rng_evt_handler_t evt_handler)
Initialize the APP RNG DRIVER according to the specified parameters in the app_rng_params_t and app_r...
APP_RNG_ACTIVITY
@ APP_RNG_ACTIVITY
Definition: app_rng.h:122