![]() |
|
|||
File indexing completed on 2025-05-11 08:23:02
0001 /* 0002 * Copyright (c) 2015-2016, Freescale Semiconductor, Inc. 0003 * Copyright 2016-2018, 2020-2022 NXP 0004 * All rights reserved. 0005 * 0006 * SPDX-License-Identifier: BSD-3-Clause 0007 */ 0008 #ifndef _FSL_TRNG_DRIVER_H_ 0009 #define _FSL_TRNG_DRIVER_H_ 0010 0011 #include "fsl_common.h" 0012 0013 #if defined(FSL_FEATURE_SOC_TRNG_COUNT) && FSL_FEATURE_SOC_TRNG_COUNT 0014 0015 /*! 0016 * @addtogroup trng 0017 * @{ 0018 */ 0019 0020 /******************************************************************************* 0021 * Definitions 0022 *******************************************************************************/ 0023 0024 /*! @name Driver version */ 0025 /*@{*/ 0026 /*! @brief TRNG driver version 2.0.15. 0027 * 0028 * Current version: 2.0.15 0029 * 0030 0031 * Change log: 0032 * - version 2.0.15 0033 * - Changed TRNG_USER_CONFIG_DEFAULT_XXX values according to latest reccomended by design team. 0034 * - version 2.0.14 0035 * - add support for RW610 and RW612 0036 * - version 2.0.13 0037 * - After deepsleep it might return error, added clearing bits in TRNG_GetRandomData() and generating new entropy. 0038 * - Modified reloading entropy in TRNG_GetRandomData(), for some data length it doesn't reloading entropy correctly. 0039 * - version 2.0.12 0040 * - For KW34A4_SERIES, KW35A4_SERIES, KW36A4_SERIES set TRNG_USER_CONFIG_DEFAULT_OSC_DIV to kTRNG_RingOscDiv8. 0041 * - version 2.0.11 0042 * - Add clearing pending errors in TRNG_Init(). 0043 * - version 2.0.10 0044 * - Fixed doxygen issues. 0045 * - version 2.0.9 0046 * - Fix HIS_CCM metrics issues. 0047 * - version 2.0.8 0048 * - For K32L2A41A_SERIES set TRNG_USER_CONFIG_DEFAULT_OSC_DIV to kTRNG_RingOscDiv4. 0049 * - version 2.0.7 0050 * - Fix MISRA 2004 issue rule 12.5. 0051 * - version 2.0.6 0052 * - For KW35Z4_SERIES set TRNG_USER_CONFIG_DEFAULT_OSC_DIV to kTRNG_RingOscDiv8. 0053 * - version 2.0.5 0054 * - Add possibility to define default TRNG configuration by device specific preprocessor macros 0055 * for FRQMIN, FRQMAX and OSCDIV. 0056 * - version 2.0.4 0057 * - Fix MISRA-2012 issues. 0058 * - Version 2.0.3 0059 * - update TRNG_Init to restart entropy generation 0060 * - Version 2.0.2 0061 * - fix MISRA issues 0062 * - Version 2.0.1 0063 * - add support for KL8x and KL28Z 0064 * - update default OSCDIV for K81 to divide by 2 0065 */ 0066 #define FSL_TRNG_DRIVER_VERSION (MAKE_VERSION(2, 0, 15)) 0067 /*@}*/ 0068 0069 /*! @brief TRNG sample mode. Used by trng_config_t. */ 0070 typedef enum _trng_sample_mode 0071 { 0072 kTRNG_SampleModeVonNeumann = 0U, /*!< Use von Neumann data in both Entropy shifter and Statistical Checker. */ 0073 kTRNG_SampleModeRaw = 1U, /*!< Use raw data into both Entropy shifter and Statistical Checker. */ 0074 kTRNG_SampleModeVonNeumannRaw = 0075 2U /*!< Use von Neumann data in Entropy shifter. Use raw data into Statistical Checker. */ 0076 } trng_sample_mode_t; 0077 0078 /*! @brief TRNG clock mode. Used by trng_config_t. */ 0079 typedef enum _trng_clock_mode 0080 { 0081 kTRNG_ClockModeRingOscillator = 0U, /*!< Ring oscillator is used to operate the TRNG (default). */ 0082 kTRNG_ClockModeSystem = 1U /*!< System clock is used to operate the TRNG. This is for test use only, and 0083 indeterminate results may occur. */ 0084 } trng_clock_mode_t; 0085 0086 /*! @brief TRNG ring oscillator divide. Used by trng_config_t. */ 0087 typedef enum _trng_ring_osc_div 0088 { 0089 kTRNG_RingOscDiv0 = 0U, /*!< Ring oscillator with no divide */ 0090 kTRNG_RingOscDiv2 = 1U, /*!< Ring oscillator divided-by-2. */ 0091 kTRNG_RingOscDiv4 = 2U, /*!< Ring oscillator divided-by-4. */ 0092 kTRNG_RingOscDiv8 = 3U /*!< Ring oscillator divided-by-8. */ 0093 } trng_ring_osc_div_t; 0094 0095 /*! @brief Data structure for definition of statistical check limits. Used by trng_config_t. */ 0096 typedef struct _trng_statistical_check_limit 0097 { 0098 uint32_t maximum; /*!< Maximum limit.*/ 0099 uint32_t minimum; /*!< Minimum limit.*/ 0100 } trng_statistical_check_limit_t; 0101 0102 /*! 0103 * @brief Data structure for the TRNG initialization 0104 * 0105 * This structure initializes the TRNG by calling the TRNG_Init() function. 0106 * It contains all TRNG configurations. 0107 */ 0108 typedef struct _trng_user_config 0109 { 0110 bool lock; /*!< @brief Disable programmability of TRNG registers. */ 0111 trng_clock_mode_t clockMode; /*!< @brief Clock mode used to operate TRNG.*/ 0112 trng_ring_osc_div_t ringOscDiv; /*!< @brief Ring oscillator divide used by TRNG. */ 0113 trng_sample_mode_t sampleMode; /*!< @brief Sample mode of the TRNG ring oscillator. */ 0114 /* Seed Control*/ 0115 uint16_t 0116 entropyDelay; /*!< @brief Entropy Delay. Defines the length (in system clocks) of each Entropy sample taken. */ 0117 uint16_t sampleSize; /*!< @brief Sample Size. Defines the total number of Entropy samples that will be taken during 0118 Entropy generation. */ 0119 uint16_t sparseBitLimit; /*!< @brief Sparse Bit Limit which defines the maximum number of 0120 * consecutive samples that may be discarded before an error is generated. 0121 * This limit is used only for during von Neumann sampling (enabled by 0122 * TRNG_HAL_SetSampleMode()). Samples are discarded if two consecutive raw samples are both 0123 * 0 or both 1. If this discarding occurs for a long period of time, it indicates that 0124 * there is insufficient Entropy. */ 0125 /* Statistical Check Parameters.*/ 0126 uint8_t retryCount; /*!< @brief Retry count. It defines the number of times a statistical check may fails 0127 * during the TRNG Entropy Generation before generating an error. */ 0128 uint8_t longRunMaxLimit; /*!< @brief Largest allowable number of consecutive samples of all 1, or all 0, 0129 * that is allowed during the Entropy generation. */ 0130 trng_statistical_check_limit_t monobitLimit; /*!< @brief Maximum and minimum limits for statistical check of number 0131 of ones/zero detected during entropy generation. */ 0132 trng_statistical_check_limit_t runBit1Limit; /*!< @brief Maximum and minimum limits for statistical check of number 0133 of runs of length 1 detected during entropy generation. */ 0134 trng_statistical_check_limit_t runBit2Limit; /*!< @brief Maximum and minimum limits for statistical check of number 0135 of runs of length 2 detected during entropy generation. */ 0136 trng_statistical_check_limit_t runBit3Limit; /*!< @brief Maximum and minimum limits for statistical check of number 0137 of runs of length 3 detected during entropy generation. */ 0138 trng_statistical_check_limit_t runBit4Limit; /*!< @brief Maximum and minimum limits for statistical check of number 0139 of runs of length 4 detected during entropy generation. */ 0140 trng_statistical_check_limit_t runBit5Limit; /*!< @brief Maximum and minimum limits for statistical check of number 0141 of runs of length 5 detected during entropy generation. */ 0142 trng_statistical_check_limit_t runBit6PlusLimit; /*!< @brief Maximum and minimum limits for statistical check of 0143 number of runs of length 6 or more detected during entropy 0144 generation. */ 0145 trng_statistical_check_limit_t 0146 pokerLimit; /*!< @brief Maximum and minimum limits for statistical check of "Poker Test". */ 0147 trng_statistical_check_limit_t frequencyCountLimit; /*!< @brief Maximum and minimum limits for statistical check of 0148 entropy sample frequency count. */ 0149 } trng_config_t; 0150 0151 /******************************************************************************* 0152 * API 0153 *******************************************************************************/ 0154 0155 #if defined(__cplusplus) 0156 extern "C" { 0157 #endif 0158 0159 /*! 0160 * @brief Initializes the user configuration structure to default values. 0161 * 0162 * This function initializes the configuration structure to default values. The default 0163 * values are as follows. 0164 * @code 0165 * userConfig->lock = 0; 0166 * userConfig->clockMode = kTRNG_ClockModeRingOscillator; 0167 * userConfig->ringOscDiv = kTRNG_RingOscDiv0; Or to other kTRNG_RingOscDiv[2|8] depending on the platform. 0168 * userConfig->sampleMode = kTRNG_SampleModeRaw; 0169 * userConfig->entropyDelay = 3200; 0170 * userConfig->sampleSize = 2500; 0171 * userConfig->sparseBitLimit = 63; 0172 * userConfig->retryCount = 1; 0173 * userConfig->longRunMaxLimit = 32; 0174 * userConfig->monobitLimit.maximum = 317; 0175 * userConfig->monobitLimit.minimum = 195; 0176 * userConfig->runBit1Limit.maximum = 107; 0177 * userConfig->runBit1Limit.minimum = 27; 0178 * userConfig->runBit2Limit.maximum = 62; 0179 * userConfig->runBit2Limit.minimum = 7; 0180 * userConfig->runBit3Limit.maximum = 39; 0181 * userConfig->runBit3Limit.minimum = 0; 0182 * userConfig->runBit4Limit.maximum = 26; 0183 * userConfig->runBit4Limit.minimum = 0; 0184 * userConfig->runBit5Limit.maximum = 18; 0185 * userConfig->runBit5Limit.minimum = 0; 0186 * userConfig->runBit6PlusLimit.maximum = 17; 0187 * userConfig->runBit6PlusLimit.minimum = 0; 0188 * userConfig->pokerLimit.maximum = 1600; 0189 * userConfig->pokerLimit.minimum = 1030; 0190 * userConfig->frequencyCountLimit.maximum = 30000; 0191 * userConfig->frequencyCountLimit.minimum = 1600; 0192 * @endcode 0193 * 0194 * @param userConfig User configuration structure. 0195 * @return If successful, returns the kStatus_TRNG_Success. Otherwise, it returns an error. 0196 */ 0197 status_t TRNG_GetDefaultConfig(trng_config_t *userConfig); 0198 0199 /*! 0200 * @brief Initializes the TRNG. 0201 * 0202 * This function initializes the TRNG. 0203 * When called, the TRNG entropy generation starts immediately. 0204 * 0205 * @param base TRNG base address 0206 * @param userConfig Pointer to the initialization configuration structure. 0207 * @return If successful, returns the kStatus_TRNG_Success. Otherwise, it returns an error. 0208 */ 0209 status_t TRNG_Init(TRNG_Type *base, const trng_config_t *userConfig); 0210 0211 /*! 0212 * @brief Shuts down the TRNG. 0213 * 0214 * This function shuts down the TRNG. 0215 * 0216 * @param base TRNG base address. 0217 */ 0218 void TRNG_Deinit(TRNG_Type *base); 0219 0220 /*! 0221 * @brief Gets random data. 0222 * 0223 * This function gets random data from the TRNG. 0224 * 0225 * @param base TRNG base address. 0226 * @param data Pointer address used to store random data. 0227 * @param dataSize Size of the buffer pointed by the data parameter. 0228 * @return random data 0229 */ 0230 status_t TRNG_GetRandomData(TRNG_Type *base, void *data, size_t dataSize); 0231 0232 #if defined(__cplusplus) 0233 } 0234 #endif 0235 0236 /*! @}*/ 0237 0238 #endif /* FSL_FEATURE_SOC_TRNG_COUNT */ 0239 #endif /*_FSL_TRNG_H_*/
[ Source navigation ] | [ Diff markup ] | [ Identifier search ] | [ general search ] |
This page was automatically generated by the 2.3.7 LXR engine. The LXR team |
![]() ![]() |