1 /* 2 * Copyright (c) 2015-2016, Freescale Semiconductor, Inc. 3 * Copyright 2016-2018, 2020-2023 NXP 4 * All rights reserved. 5 * 6 * SPDX-License-Identifier: BSD-3-Clause 7 */ 8 #ifndef _FSL_TRNG_DRIVER_H_ 9 #define _FSL_TRNG_DRIVER_H_ 10 11 #include "fsl_common.h" 12 13 #if defined(FSL_FEATURE_SOC_TRNG_COUNT) && FSL_FEATURE_SOC_TRNG_COUNT 14 15 /*! 16 * @addtogroup trng 17 * @{ 18 */ 19 20 /******************************************************************************* 21 * Definitions 22 *******************************************************************************/ 23 24 /*! @name Driver version */ 25 /*@{*/ 26 /*! @brief TRNG driver version 2.0.16. 27 * 28 * Current version: 2.0.16 29 * 30 31 * Change log: 32 * - version 2.0.16 33 * - Added support for Dual oscillator mode. 34 * - version 2.0.15 35 * - Changed TRNG_USER_CONFIG_DEFAULT_XXX values according to latest reccomended by design team. 36 * - version 2.0.14 37 * - add support for RW610 and RW612 38 * - version 2.0.13 39 * - After deepsleep it might return error, added clearing bits in TRNG_GetRandomData() and generating new entropy. 40 * - Modified reloading entropy in TRNG_GetRandomData(), for some data length it doesn't reloading entropy correctly. 41 * - version 2.0.12 42 * - For KW34A4_SERIES, KW35A4_SERIES, KW36A4_SERIES set TRNG_USER_CONFIG_DEFAULT_OSC_DIV to kTRNG_RingOscDiv8. 43 * - version 2.0.11 44 * - Add clearing pending errors in TRNG_Init(). 45 * - version 2.0.10 46 * - Fixed doxygen issues. 47 * - version 2.0.9 48 * - Fix HIS_CCM metrics issues. 49 * - version 2.0.8 50 * - For K32L2A41A_SERIES set TRNG_USER_CONFIG_DEFAULT_OSC_DIV to kTRNG_RingOscDiv4. 51 * - version 2.0.7 52 * - Fix MISRA 2004 issue rule 12.5. 53 * - version 2.0.6 54 * - For KW35Z4_SERIES set TRNG_USER_CONFIG_DEFAULT_OSC_DIV to kTRNG_RingOscDiv8. 55 * - version 2.0.5 56 * - Add possibility to define default TRNG configuration by device specific preprocessor macros 57 * for FRQMIN, FRQMAX and OSCDIV. 58 * - version 2.0.4 59 * - Fix MISRA-2012 issues. 60 * - Version 2.0.3 61 * - update TRNG_Init to restart entropy generation 62 * - Version 2.0.2 63 * - fix MISRA issues 64 * - Version 2.0.1 65 * - add support for KL8x and KL28Z 66 * - update default OSCDIV for K81 to divide by 2 67 */ 68 #define FSL_TRNG_DRIVER_VERSION (MAKE_VERSION(2, 0, 16)) 69 /*@}*/ 70 71 /*! @brief TRNG sample mode. Used by trng_config_t. */ 72 typedef enum _trng_sample_mode 73 { 74 kTRNG_SampleModeVonNeumann = 0U, /*!< Use von Neumann data in both Entropy shifter and Statistical Checker. */ 75 kTRNG_SampleModeRaw = 1U, /*!< Use raw data into both Entropy shifter and Statistical Checker. */ 76 kTRNG_SampleModeVonNeumannRaw = 77 2U /*!< Use von Neumann data in Entropy shifter. Use raw data into Statistical Checker. */ 78 } trng_sample_mode_t; 79 80 /*! @brief TRNG clock mode. Used by trng_config_t. */ 81 typedef enum _trng_clock_mode 82 { 83 kTRNG_ClockModeRingOscillator = 0U, /*!< Ring oscillator is used to operate the TRNG (default). */ 84 kTRNG_ClockModeSystem = 1U /*!< System clock is used to operate the TRNG. This is for test use only, and 85 indeterminate results may occur. */ 86 } trng_clock_mode_t; 87 88 /*! @brief TRNG ring oscillator divide. Used by trng_config_t. */ 89 typedef enum _trng_ring_osc_div 90 { 91 kTRNG_RingOscDiv0 = 0U, /*!< Ring oscillator with no divide */ 92 kTRNG_RingOscDiv2 = 1U, /*!< Ring oscillator divided-by-2. */ 93 kTRNG_RingOscDiv4 = 2U, /*!< Ring oscillator divided-by-4. */ 94 kTRNG_RingOscDiv8 = 3U /*!< Ring oscillator divided-by-8. */ 95 } trng_ring_osc_div_t; 96 97 #if defined(FSL_FEATURE_TRNG_HAS_DUAL_OSCILATORS) && (FSL_FEATURE_TRNG_HAS_DUAL_OSCILATORS > 0) 98 /*! @brief TRNG oscillator mode . Used by trng_config_t. */ 99 typedef enum trng_oscillator_mode_t 100 { 101 kTRNG_SingleOscillatorModeOsc1 = 0U, /*!< Single oscillator mode, using OSC1 (default)*/ 102 kTRNG_DualOscillatorMode = 1U, /*!< Dual oscillator mode*/ 103 kTRNG_SingleOscillatorModeOsc2 = 2U, /*!< Single oscillator mode, using OSC2 */ 104 } trng_oscillator_mode_t; 105 #endif /* FSL_FEATURE_TRNG_HAS_DUAL_OSCILATORS */ 106 107 /*! @brief Data structure for definition of statistical check limits. Used by trng_config_t. */ 108 typedef struct _trng_statistical_check_limit 109 { 110 uint32_t maximum; /*!< Maximum limit.*/ 111 uint32_t minimum; /*!< Minimum limit.*/ 112 } trng_statistical_check_limit_t; 113 114 /*! 115 * @brief Data structure for the TRNG initialization 116 * 117 * This structure initializes the TRNG by calling the TRNG_Init() function. 118 * It contains all TRNG configurations. 119 */ 120 typedef struct _trng_user_config 121 { 122 bool lock; /*!< @brief Disable programmability of TRNG registers. */ 123 trng_clock_mode_t clockMode; /*!< @brief Clock mode used to operate TRNG.*/ 124 trng_ring_osc_div_t ringOscDiv; /*!< @brief Ring oscillator divide used by TRNG. */ 125 trng_sample_mode_t sampleMode; /*!< @brief Sample mode of the TRNG ring oscillator. */ 126 #if defined(FSL_FEATURE_TRNG_HAS_DUAL_OSCILATORS) && (FSL_FEATURE_TRNG_HAS_DUAL_OSCILATORS > 0) 127 trng_oscillator_mode_t oscillatorMode; /*!< @brief TRNG oscillator mode . */ 128 trng_ring_osc_div_t ringOsc2Div; /*!< @brief Divider used for Ring oscillator 2. */ 129 #endif /* FSL_FEATURE_TRNG_HAS_DUAL_OSCILATORS */ 130 /* Seed Control*/ 131 uint16_t 132 entropyDelay; /*!< @brief Entropy Delay. Defines the length (in system clocks) of each Entropy sample taken. */ 133 uint16_t sampleSize; /*!< @brief Sample Size. Defines the total number of Entropy samples that will be taken during 134 Entropy generation. */ 135 uint16_t sparseBitLimit; /*!< @brief Sparse Bit Limit which defines the maximum number of 136 * consecutive samples that may be discarded before an error is generated. 137 * This limit is used only for during von Neumann sampling (enabled by 138 * TRNG_HAL_SetSampleMode()). Samples are discarded if two consecutive raw samples are both 139 * 0 or both 1. If this discarding occurs for a long period of time, it indicates that 140 * there is insufficient Entropy. */ 141 /* Statistical Check Parameters.*/ 142 uint8_t retryCount; /*!< @brief Retry count. It defines the number of times a statistical check may fails 143 * during the TRNG Entropy Generation before generating an error. */ 144 uint8_t longRunMaxLimit; /*!< @brief Largest allowable number of consecutive samples of all 1, or all 0, 145 * that is allowed during the Entropy generation. */ 146 trng_statistical_check_limit_t monobitLimit; /*!< @brief Maximum and minimum limits for statistical check of number 147 of ones/zero detected during entropy generation. */ 148 trng_statistical_check_limit_t runBit1Limit; /*!< @brief Maximum and minimum limits for statistical check of number 149 of runs of length 1 detected during entropy generation. */ 150 trng_statistical_check_limit_t runBit2Limit; /*!< @brief Maximum and minimum limits for statistical check of number 151 of runs of length 2 detected during entropy generation. */ 152 trng_statistical_check_limit_t runBit3Limit; /*!< @brief Maximum and minimum limits for statistical check of number 153 of runs of length 3 detected during entropy generation. */ 154 trng_statistical_check_limit_t runBit4Limit; /*!< @brief Maximum and minimum limits for statistical check of number 155 of runs of length 4 detected during entropy generation. */ 156 trng_statistical_check_limit_t runBit5Limit; /*!< @brief Maximum and minimum limits for statistical check of number 157 of runs of length 5 detected during entropy generation. */ 158 trng_statistical_check_limit_t runBit6PlusLimit; /*!< @brief Maximum and minimum limits for statistical check of 159 number of runs of length 6 or more detected during entropy 160 generation. */ 161 trng_statistical_check_limit_t 162 pokerLimit; /*!< @brief Maximum and minimum limits for statistical check of "Poker Test". */ 163 trng_statistical_check_limit_t frequencyCountLimit; /*!< @brief Maximum and minimum limits for statistical check of 164 entropy sample frequency count. */ 165 } trng_config_t; 166 167 /******************************************************************************* 168 * API 169 *******************************************************************************/ 170 171 #if defined(__cplusplus) 172 extern "C" { 173 #endif 174 175 /*! 176 * @brief Initializes the user configuration structure to default values. 177 * 178 * This function initializes the configuration structure to default values. The default 179 * values are as follows. 180 * @code 181 * userConfig->lock = 0; 182 * userConfig->clockMode = kTRNG_ClockModeRingOscillator; 183 * userConfig->ringOscDiv = kTRNG_RingOscDiv0; Or to other kTRNG_RingOscDiv[2|8] depending on the platform. 184 * userConfig->sampleMode = kTRNG_SampleModeRaw; 185 * userConfig->entropyDelay = 3200; 186 * userConfig->sampleSize = 2500; 187 * userConfig->sparseBitLimit = 63; 188 * userConfig->retryCount = 1; 189 * userConfig->longRunMaxLimit = 32; 190 * userConfig->monobitLimit.maximum = 317; 191 * userConfig->monobitLimit.minimum = 195; 192 * userConfig->runBit1Limit.maximum = 107; 193 * userConfig->runBit1Limit.minimum = 27; 194 * userConfig->runBit2Limit.maximum = 62; 195 * userConfig->runBit2Limit.minimum = 7; 196 * userConfig->runBit3Limit.maximum = 39; 197 * userConfig->runBit3Limit.minimum = 0; 198 * userConfig->runBit4Limit.maximum = 26; 199 * userConfig->runBit4Limit.minimum = 0; 200 * userConfig->runBit5Limit.maximum = 18; 201 * userConfig->runBit5Limit.minimum = 0; 202 * userConfig->runBit6PlusLimit.maximum = 17; 203 * userConfig->runBit6PlusLimit.minimum = 0; 204 * userConfig->pokerLimit.maximum = 1600; 205 * userConfig->pokerLimit.minimum = 1030; 206 * userConfig->frequencyCountLimit.maximum = 30000; 207 * userConfig->frequencyCountLimit.minimum = 1600; 208 * @endcode 209 * 210 * @param userConfig User configuration structure. 211 * @return If successful, returns the kStatus_TRNG_Success. Otherwise, it returns an error. 212 */ 213 status_t TRNG_GetDefaultConfig(trng_config_t *userConfig); 214 215 /*! 216 * @brief Initializes the TRNG. 217 * 218 * This function initializes the TRNG. 219 * When called, the TRNG entropy generation starts immediately. 220 * 221 * @param base TRNG base address 222 * @param userConfig Pointer to the initialization configuration structure. 223 * @return If successful, returns the kStatus_TRNG_Success. Otherwise, it returns an error. 224 */ 225 status_t TRNG_Init(TRNG_Type *base, const trng_config_t *userConfig); 226 227 /*! 228 * @brief Shuts down the TRNG. 229 * 230 * This function shuts down the TRNG. 231 * 232 * @param base TRNG base address. 233 */ 234 void TRNG_Deinit(TRNG_Type *base); 235 236 /*! 237 * @brief Gets random data. 238 * 239 * This function gets random data from the TRNG. 240 * 241 * @param base TRNG base address. 242 * @param data Pointer address used to store random data. 243 * @param dataSize Size of the buffer pointed by the data parameter. 244 * @return random data 245 */ 246 status_t TRNG_GetRandomData(TRNG_Type *base, void *data, size_t dataSize); 247 248 #if defined(__cplusplus) 249 } 250 #endif 251 252 /*! @}*/ 253 254 #endif /* FSL_FEATURE_SOC_TRNG_COUNT */ 255 #endif /*_FSL_TRNG_H_*/ 256
