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 "gr55xx_hal.h"
56 #include "app_drv_error.h"
57 #ifdef ENV_USE_FREERTOS
58 #include "app_rtos_cfg.h"
59 #endif
60 
61 #ifdef __cplusplus
62 extern "C" {
63 #endif
64 
65 #ifdef HAL_RNG_MODULE_ENABLED
66 
67 /** @addtogroup APP_RNG_ENUM Enumerations
68  * @{
69  */
70 
71 /**
72  * @brief RNG operating mode Enumerations definition
73  */
74 typedef enum
75 {
76  APP_RNG_TYPE_INTERRUPT, /**< Interrupt operation mode */
77  APP_RNG_TYPE_POLLING, /**< Polling operation mode */
78  APP_RNG_TYPE_MAX /**< Only for check parameter, not used as input parameters. */
80 
81 /**
82  * @brief RNG event Enumerations definition
83  */
84 typedef enum
85 {
86  APP_RNG_EVT_DONE, /**< Generated random by UART peripheral. */
87  APP_RNG_EVT_ERROR, /**< Error reported by UART peripheral. */
89 /** @} */
90 
91 /** @addtogroup HAL_APP_RNG_STRUCTURES Structures
92  * @{
93  */
94 /**
95  * @brief RNG parameters structure definition
96  */
97 typedef struct
98 {
99  app_rng_type_t use_type; /**< Specifies the operation mode of RNG. */
100  rng_init_t init; /**< RNG required parameters. */
102 
103 /**
104  * @brief RNG event structure definition
105  */
106 typedef struct
107 {
108  app_rng_evt_type_t type; /**< Type of event. */
109  uint32_t random_data; /**< Random number. */
110 } app_rng_evt_t;
111 
112 /**
113  * @brief RNG event callback definition
114  */
115 typedef void (*app_rng_evt_handler_t)(app_rng_evt_t *p_evt);
116 
117 /** @} */
118 
119 /* Exported functions --------------------------------------------------------*/
120 /** @addtogroup APP_RNG_DRIVER_FUNCTIONS Functions
121  * @{
122  */
123 
124 /**
125  ****************************************************************************************
126  * @brief Initialize the APP RNG DRIVER according to the specified parameters
127  * in the app_rng_params_t and app_rng_evt_handler_t.
128  * @note If interrupt mode is set, you can use blocking mode. Conversely, if blocking mode
129  * is set, you can't use interrupt mode.
130  *
131  * @param[in] p_params: Pointer to app_rng_params_t parameter which contains the
132  * configuration information for the specified RNG module.
133  * @param[in] evt_handler: RNG user callback function.
134  *
135  * @return Result of initialization.
136  ****************************************************************************************
137  */
138 uint16_t app_rng_init(app_rng_params_t *p_params, app_rng_evt_handler_t evt_handler);
139 
140 /**
141  ****************************************************************************************
142  * @brief De-initialize the APP RNG DRIVER peripheral.
143  *
144  * @return Result of De-initialization.
145  ****************************************************************************************
146  */
147 uint16_t app_rng_deinit(void);
148 
149 /**
150  ****************************************************************************************
151  * @brief Generate a 32-bit random number.
152  *
153  * @param[in] p_seed: user configured seeds. the seed is valid when seed_mode member of
154  * rng_init_t is configured as RNG_SEED_USER. If 59-bit random number is
155  * selected, the seed need to provide [0~58] bit spaces. If 128-bit random
156  * number is selected, the seed need to provide [0~127] bit spaces.
157  * @param[out] p_random32bit: Pointer to generated random number variable if successful.
158  *
159  * @return Result of operation.
160  ****************************************************************************************
161  */
162 uint16_t app_rng_gen_sync(uint16_t *p_seed, uint32_t *p_random32bit);
163 
164 /**
165  ****************************************************************************************
166  * @brief Generate a 32-bit random number in interrupt mode.
167  *
168  * @param[in] p_seed: user configured seeds. the seed is valid when seed_mode member of
169  * rng_init_t is configured as RNG_SEED_USER. If 59-bit random number is
170  * selected, the seed need to provide [0~58] bit spaces. If 128-bit random
171  * number is selected, the seed need to provide [0~127] bit spaces.
172  *
173  * @return Result of operation.
174  ****************************************************************************************
175  */
176 uint16_t app_rng_gen_async(uint16_t *p_seed);
177 
178 /**
179  ****************************************************************************************
180  * @brief Return the RNG handle.
181  *
182  * @return Pointer to the RNG handle.
183  ****************************************************************************************
184  */
186 
187 #ifdef ENV_RTOS_USE_SEMP
188 
189 /**
190  ****************************************************************************************
191  * @brief [RTOS] Generate a 32-bit random number in interrupt mode.
192  *
193  * @param[in] p_seed: user configured seeds. the seed is valid when seed_mode member of
194  * rng_init_t is configured as RNG_SEED_USER. If 59-bit random number is
195  * selected, the seed need to provide [0~58] bit spaces. If 128-bit random
196  * number is selected, the seed need to provide [0~127] bit spaces.
197  *
198  * @return Result of operation.
199  ****************************************************************************************
200  */
201 uint16_t app_rng_gen_sem_sync(uint16_t *p_seed);
202 
203 #endif
204 
205 #endif
206 /** @} */
207 
208 #ifdef __cplusplus
209 }
210 #endif
211 
212 #endif
213 
214 /** @} */
215 /** @} */
216 /** @} */
217 
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:75
app_rng_evt_t::type
app_rng_evt_type_t type
Type of event.
Definition: app_rng.h:108
APP_RNG_EVT_DONE
@ APP_RNG_EVT_DONE
Generated random by UART peripheral.
Definition: app_rng.h:86
APP_RNG_TYPE_MAX
@ APP_RNG_TYPE_MAX
Only for check parameter, not used as input parameters.
Definition: app_rng.h:78
APP_RNG_TYPE_INTERRUPT
@ APP_RNG_TYPE_INTERRUPT
Interrupt operation mode.
Definition: app_rng.h:76
app_rng_gen_sync
uint16_t app_rng_gen_sync(uint16_t *p_seed, uint32_t *p_random32bit)
Generate a 32-bit random number.
app_rng_params_t
RNG parameters structure definition.
Definition: app_rng.h:98
app_rng_evt_t::random_data
uint32_t random_data
Random number.
Definition: app_rng.h:109
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:85
app_rng_params_t::init
rng_init_t init
RNG required parameters.
Definition: app_rng.h:100
app_rng_evt_t
RNG event structure definition.
Definition: app_rng.h:107
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:115
_rng_handle
RNG handle Structure definition.
Definition: gr55xx_hal_rng.h:125
APP_RNG_EVT_ERROR
@ APP_RNG_EVT_ERROR
Error reported by UART peripheral.
Definition: app_rng.h:87
_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.
gr55xx_hal.h
This file contains all the functions prototypes for the HAL module driver.
APP_RNG_TYPE_POLLING
@ APP_RNG_TYPE_POLLING
Polling operation mode
Definition: app_rng.h:77
app_rng_params_t::use_type
app_rng_type_t use_type
Specifies the operation mode of RNG.
Definition: app_rng.h:99
app_rtos_cfg.h
Header file of app rtos config code.
app_drv_error.h
Header file of app driver error code.
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...