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 APP_RNG_TYPE_INTERRUPT, /**< Interrupt operation mode */ 76 APP_RNG_TYPE_POLLING, /**< Polling operation mode */ 77 APP_RNG_TYPE_MAX /**< Only for check parameter, not used as input parameters. */ 78 } app_rng_type_t; 79 80 /** 81 * @brief RNG event Enumerations definition 82 */ 83 typedef enum { 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 parameters structure definition 94 */ 95 typedef struct { 96 app_rng_type_t use_type; /**< Specifies the operation mode of RNG. */ 97 rng_init_t init; /**< RNG required parameters. */ 98 } app_rng_params_t; 99 100 /** 101 * @brief RNG event structure definition 102 */ 103 typedef struct { 104 app_rng_evt_type_t type; /**< Type of event. */ 105 uint32_t random_data; /**< Random number. */ 106 } app_rng_evt_t; 107 108 /** 109 * @brief RNG event callback definition 110 */ 111 typedef void (*app_rng_evt_handler_t)(app_rng_evt_t *p_evt); 112 113 /** @} */ 114 115 /* Exported functions --------------------------------------------------------*/ 116 /** @addtogroup APP_RNG_DRIVER_FUNCTIONS Functions 117 * @{ 118 */ 119 120 /** 121 **************************************************************************************** 122 * @brief Initialize the APP RNG DRIVER according to the specified parameters 123 * in the app_rng_params_t and app_rng_evt_handler_t. 124 * @note If interrupt mode is set, you can use blocking mode. Conversely, if blocking mode 125 * is set, you can't use interrupt mode. 126 * 127 * @param[in] p_params: Pointer to app_rng_params_t parameter which contains the 128 * configuration information for the specified RNG module. 129 * @param[in] evt_handler: RNG user callback function. 130 * 131 * @return Result of initialization. 132 **************************************************************************************** 133 */ 134 uint16_t app_rng_init(app_rng_params_t *p_params, app_rng_evt_handler_t evt_handler); 135 136 /** 137 **************************************************************************************** 138 * @brief De-initialize the APP RNG DRIVER peripheral. 139 * 140 * @return Result of De-initialization. 141 **************************************************************************************** 142 */ 143 uint16_t app_rng_deinit(void); 144 145 /** 146 **************************************************************************************** 147 * @brief Generate a 32-bit random number. 148 * 149 * @param[in] p_seed: user configured seeds. the seed is valid when seed_mode member of 150 * rng_init_t is configured as RNG_SEED_USER. If 59-bit random number is 151 * selected, the seed need to provide [0~58] bit spaces. If 128-bit random 152 * number is selected, the seed need to provide [0~127] bit spaces. 153 * @param[out] p_random32bit: Pointer to generated random number variable if successful. 154 * 155 * @return Result of operation. 156 **************************************************************************************** 157 */ 158 uint16_t app_rng_gen_sync(uint16_t *p_seed, uint32_t *p_random32bit); 159 160 /** 161 **************************************************************************************** 162 * @brief Generate a 32-bit random number in interrupt mode. 163 * 164 * @param[in] p_seed: user configured seeds. the seed is valid when seed_mode member of 165 * rng_init_t is configured as RNG_SEED_USER. If 59-bit random number is 166 * selected, the seed need to provide [0~58] bit spaces. If 128-bit random 167 * number is selected, the seed need to provide [0~127] bit spaces. 168 * 169 * @return Result of operation. 170 **************************************************************************************** 171 */ 172 uint16_t app_rng_gen_async(uint16_t *p_seed); 173 174 /** 175 **************************************************************************************** 176 * @brief Return the RNG handle. 177 * 178 * @return Pointer to the RNG handle. 179 **************************************************************************************** 180 */ 181 rng_handle_t *app_rng_get_handle(void); 182 183 #ifdef ENV_RTOS_USE_SEMP 184 185 /** 186 **************************************************************************************** 187 * @brief [RTOS] Generate a 32-bit random number in interrupt mode. 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 * 194 * @return Result of operation. 195 **************************************************************************************** 196 */ 197 uint16_t app_rng_gen_sem_sync(uint16_t *p_seed); 198 199 #endif 200 201 #endif 202 /** @} */ 203 204 #ifdef __cplusplus 205 } 206 #endif 207 208 #endif 209 210 /** @} */ 211 /** @} */ 212 /** @} */ 213 214