1 /* 2 * Copyright (c) 2015-2016, Freescale Semiconductor, Inc. 3 * Copyright 2016-2017 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 /******************************************************************************* 22 * Definitions 23 *******************************************************************************/ 24 25 /*! @name Driver version */ 26 /*@{*/ 27 /*! @brief TRNG driver version 2.0.1. 28 * 29 * Current version: 2.0.1 30 * 31 * Change log: 32 * - Version 2.0.1 33 * - add support for KL8x and KL28Z 34 * - update default OSCDIV for K81 to divide by 2 35 */ 36 #define FSL_TRNG_DRIVER_VERSION (MAKE_VERSION(2, 0, 1)) 37 /*@}*/ 38 39 /*! @brief TRNG sample mode. Used by trng_config_t. */ 40 typedef enum _trng_sample_mode 41 { 42 kTRNG_SampleModeVonNeumann = 0U, /*!< Use von Neumann data in both Entropy shifter and Statistical Checker. */ 43 kTRNG_SampleModeRaw = 1U, /*!< Use raw data into both Entropy shifter and Statistical Checker. */ 44 kTRNG_SampleModeVonNeumannRaw = 45 2U /*!< Use von Neumann data in Entropy shifter. Use raw data into Statistical Checker. */ 46 } trng_sample_mode_t; 47 48 /*! @brief TRNG clock mode. Used by trng_config_t. */ 49 typedef enum _trng_clock_mode 50 { 51 kTRNG_ClockModeRingOscillator = 0U, /*!< Ring oscillator is used to operate the TRNG (default). */ 52 kTRNG_ClockModeSystem = 1U /*!< System clock is used to operate the TRNG. This is for test use only, and 53 indeterminate results may occur. */ 54 } trng_clock_mode_t; 55 56 /*! @brief TRNG ring oscillator divide. Used by trng_config_t. */ 57 typedef enum _trng_ring_osc_div 58 { 59 kTRNG_RingOscDiv0 = 0U, /*!< Ring oscillator with no divide */ 60 kTRNG_RingOscDiv2 = 1U, /*!< Ring oscillator divided-by-2. */ 61 kTRNG_RingOscDiv4 = 2U, /*!< Ring oscillator divided-by-4. */ 62 kTRNG_RingOscDiv8 = 3U /*!< Ring oscillator divided-by-8. */ 63 } trng_ring_osc_div_t; 64 65 /*! @brief Data structure for definition of statistical check limits. Used by trng_config_t. */ 66 typedef struct _trng_statistical_check_limit 67 { 68 uint32_t maximum; /*!< Maximum limit.*/ 69 uint32_t minimum; /*!< Minimum limit.*/ 70 } trng_statistical_check_limit_t; 71 72 /*! 73 * @brief Data structure for the TRNG initialization 74 * 75 * This structure initializes the TRNG by calling the TRNG_Init() function. 76 * It contains all TRNG configurations. 77 */ 78 typedef struct _trng_user_config 79 { 80 bool lock; /*!< @brief Disable programmability of TRNG registers. */ 81 trng_clock_mode_t clockMode; /*!< @brief Clock mode used to operate TRNG.*/ 82 trng_ring_osc_div_t ringOscDiv; /*!< @brief Ring oscillator divide used by TRNG. */ 83 trng_sample_mode_t sampleMode; /*!< @brief Sample mode of the TRNG ring oscillator. */ 84 /* Seed Control*/ 85 uint16_t 86 entropyDelay; /*!< @brief Entropy Delay. Defines the length (in system clocks) of each Entropy sample taken. */ 87 uint16_t sampleSize; /*!< @brief Sample Size. Defines the total number of Entropy samples that will be taken during 88 Entropy generation. */ 89 uint16_t 90 sparseBitLimit; /*!< @brief Sparse Bit Limit which defines the maximum number of 91 * consecutive samples that may be discarded before an error is generated. 92 * This limit is used only for during von Neumann sampling (enabled by TRNG_HAL_SetSampleMode()). 93 * Samples are discarded if two consecutive raw samples are both 0 or both 1. If 94 * this discarding occurs for a long period of time, it indicates that there is 95 * insufficient Entropy. */ 96 /* Statistical Check Parameters.*/ 97 uint8_t retryCount; /*!< @brief Retry count. It defines the number of times a statistical check may fails 98 * during the TRNG Entropy Generation before generating an error. */ 99 uint8_t longRunMaxLimit; /*!< @brief Largest allowable number of consecutive samples of all 1, or all 0, 100 * that is allowed during the Entropy generation. */ 101 trng_statistical_check_limit_t 102 monobitLimit; /*!< @brief Maximum and minimum limits for statistical check of number of ones/zero detected 103 during entropy generation. */ 104 trng_statistical_check_limit_t 105 runBit1Limit; /*!< @brief Maximum and minimum limits for statistical check of number of runs of length 1 106 detected during entropy generation. */ 107 trng_statistical_check_limit_t 108 runBit2Limit; /*!< @brief Maximum and minimum limits for statistical check of number of runs of length 2 109 detected during entropy generation. */ 110 trng_statistical_check_limit_t 111 runBit3Limit; /*!< @brief Maximum and minimum limits for statistical check of number of runs of length 3 112 detected during entropy generation. */ 113 trng_statistical_check_limit_t 114 runBit4Limit; /*!< @brief Maximum and minimum limits for statistical check of number of runs of length 4 115 detected during entropy generation. */ 116 trng_statistical_check_limit_t 117 runBit5Limit; /*!< @brief Maximum and minimum limits for statistical check of number of runs of length 5 118 detected during entropy generation. */ 119 trng_statistical_check_limit_t runBit6PlusLimit; /*!< @brief Maximum and minimum limits for statistical check of 120 number of runs of length 6 or more detected during entropy 121 generation. */ 122 trng_statistical_check_limit_t 123 pokerLimit; /*!< @brief Maximum and minimum limits for statistical check of "Poker Test". */ 124 trng_statistical_check_limit_t 125 frequencyCountLimit; /*!< @brief Maximum and minimum limits for statistical check of entropy sample frequency 126 count. */ 127 } trng_config_t; 128 129 /******************************************************************************* 130 * API 131 *******************************************************************************/ 132 133 #if defined(__cplusplus) 134 extern "C" { 135 #endif 136 137 /*! 138 * @brief Initializes the user configuration structure to default values. 139 * 140 * This function initializes the configuration structure to default values. The default 141 * values are as follows. 142 * @code 143 * user_config->lock = 0; 144 * user_config->clockMode = kTRNG_ClockModeRingOscillator; 145 * user_config->ringOscDiv = kTRNG_RingOscDiv0; Or to other kTRNG_RingOscDiv[2|8] depending on the platform. 146 * user_config->sampleMode = kTRNG_SampleModeRaw; 147 * user_config->entropyDelay = 3200; 148 * user_config->sampleSize = 2500; 149 * user_config->sparseBitLimit = TRNG_USER_CONFIG_DEFAULT_SPARSE_BIT_LIMIT; 150 * user_config->retryCount = 63; 151 * user_config->longRunMaxLimit = 34; 152 * user_config->monobitLimit.maximum = 1384; 153 * user_config->monobitLimit.minimum = 1116; 154 * user_config->runBit1Limit.maximum = 405; 155 * user_config->runBit1Limit.minimum = 227; 156 * user_config->runBit2Limit.maximum = 220; 157 * user_config->runBit2Limit.minimum = 98; 158 * user_config->runBit3Limit.maximum = 125; 159 * user_config->runBit3Limit.minimum = 37; 160 * user_config->runBit4Limit.maximum = 75; 161 * user_config->runBit4Limit.minimum = 11; 162 * user_config->runBit5Limit.maximum = 47; 163 * user_config->runBit5Limit.minimum = 1; 164 * user_config->runBit6PlusLimit.maximum = 47; 165 * user_config->runBit6PlusLimit.minimum = 1; 166 * user_config->pokerLimit.maximum = 26912; 167 * user_config->pokerLimit.minimum = 24445; 168 * user_config->frequencyCountLimit.maximum = 0x3fffff; 169 * user_config->frequencyCountLimit.minimum = 1600; 170 * @endcode 171 * 172 * @param user_config User configuration structure. 173 * @return If successful, returns the kStatus_TRNG_Success. Otherwise, it returns an error. 174 */ 175 status_t TRNG_GetDefaultConfig(trng_config_t *userConfig); 176 177 /*! 178 * @brief Initializes the TRNG. 179 * 180 * This function initializes the TRNG. 181 * When called, the TRNG entropy generation starts immediately. 182 * 183 * @param base TRNG base address 184 * @param userConfig Pointer to the initialization configuration structure. 185 * @return If successful, returns the kStatus_TRNG_Success. Otherwise, it returns an error. 186 */ 187 status_t TRNG_Init(TRNG_Type *base, const trng_config_t *userConfig); 188 189 /*! 190 * @brief Shuts down the TRNG. 191 * 192 * This function shuts down the TRNG. 193 * 194 * @param base TRNG base address. 195 */ 196 void TRNG_Deinit(TRNG_Type *base); 197 198 /*! 199 * @brief Gets random data. 200 * 201 * This function gets random data from the TRNG. 202 * 203 * @param base TRNG base address. 204 * @param data Pointer address used to store random data. 205 * @param dataSize Size of the buffer pointed by the data parameter. 206 * @return random data 207 */ 208 status_t TRNG_GetRandomData(TRNG_Type *base, void *data, size_t dataSize); 209 210 #if defined(__cplusplus) 211 } 212 #endif 213 214 /*! @}*/ 215 216 #endif /* FSL_FEATURE_SOC_TRNG_COUNT */ 217 #endif /*_FSL_TRNG_H_*/ 218
