mbed official / mbed-dev

mbed library sources. Supersedes mbed-src.

Dependents:   Nucleo_Hello_Encoder BLE_iBeaconScan AM1805_DEMO DISCO-F429ZI_ExportTemplate1 ... more

cmsis/BUILD/mbed/TARGET_K82F/TOOLCHAIN_IAR/fsl_trng.h@189:f392fc9709a3, 2019-02-20 (annotated)

Committer:
AnnaBridge
Date:
Wed Feb 20 22:31:08 2019 +0000
Revision:
189:f392fc9709a3
mbed library release version 165

Who changed what in which revision?

UserRevisionLine numberNew contents of line
AnnaBridge 189:f392fc9709a3 1 /*
AnnaBridge 189:f392fc9709a3 2 * Copyright (c) 2015-2016, Freescale Semiconductor, Inc.
AnnaBridge 189:f392fc9709a3 3 * All rights reserved.
AnnaBridge 189:f392fc9709a3 4 *
AnnaBridge 189:f392fc9709a3 5 * Redistribution and use in source and binary forms, with or without modification,
AnnaBridge 189:f392fc9709a3 6 * are permitted provided that the following conditions are met:
AnnaBridge 189:f392fc9709a3 7 *
AnnaBridge 189:f392fc9709a3 8 * o Redistributions of source code must retain the above copyright notice, this list
AnnaBridge 189:f392fc9709a3 9 * of conditions and the following disclaimer.
AnnaBridge 189:f392fc9709a3 10 *
AnnaBridge 189:f392fc9709a3 11 * o Redistributions in binary form must reproduce the above copyright notice, this
AnnaBridge 189:f392fc9709a3 12 * list of conditions and the following disclaimer in the documentation and/or
AnnaBridge 189:f392fc9709a3 13 * other materials provided with the distribution.
AnnaBridge 189:f392fc9709a3 14 *
AnnaBridge 189:f392fc9709a3 15 * o Neither the name of Freescale Semiconductor, Inc. nor the names of its
AnnaBridge 189:f392fc9709a3 16 * contributors may be used to endorse or promote products derived from this
AnnaBridge 189:f392fc9709a3 17 * software without specific prior written permission.
AnnaBridge 189:f392fc9709a3 18 *
AnnaBridge 189:f392fc9709a3 19 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
AnnaBridge 189:f392fc9709a3 20 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
AnnaBridge 189:f392fc9709a3 21 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
AnnaBridge 189:f392fc9709a3 22 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
AnnaBridge 189:f392fc9709a3 23 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
AnnaBridge 189:f392fc9709a3 24 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
AnnaBridge 189:f392fc9709a3 25 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
AnnaBridge 189:f392fc9709a3 26 * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
AnnaBridge 189:f392fc9709a3 27 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
AnnaBridge 189:f392fc9709a3 28 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
AnnaBridge 189:f392fc9709a3 29 */
AnnaBridge 189:f392fc9709a3 30 #ifndef _FSL_TRNG_DRIVER_H_
AnnaBridge 189:f392fc9709a3 31 #define _FSL_TRNG_DRIVER_H_
AnnaBridge 189:f392fc9709a3 32
AnnaBridge 189:f392fc9709a3 33 #include "fsl_common.h"
AnnaBridge 189:f392fc9709a3 34
AnnaBridge 189:f392fc9709a3 35 #if defined(FSL_FEATURE_SOC_TRNG_COUNT) && FSL_FEATURE_SOC_TRNG_COUNT
AnnaBridge 189:f392fc9709a3 36
AnnaBridge 189:f392fc9709a3 37 /*!
AnnaBridge 189:f392fc9709a3 38 * @addtogroup trng_driver
AnnaBridge 189:f392fc9709a3 39 * @{
AnnaBridge 189:f392fc9709a3 40 */
AnnaBridge 189:f392fc9709a3 41
AnnaBridge 189:f392fc9709a3 42
AnnaBridge 189:f392fc9709a3 43 /*******************************************************************************
AnnaBridge 189:f392fc9709a3 44 * Definitions
AnnaBridge 189:f392fc9709a3 45 *******************************************************************************/
AnnaBridge 189:f392fc9709a3 46
AnnaBridge 189:f392fc9709a3 47 /*! @name Driver version */
AnnaBridge 189:f392fc9709a3 48 /*@{*/
AnnaBridge 189:f392fc9709a3 49 /*! @brief TRNG driver version 2.0.1.
AnnaBridge 189:f392fc9709a3 50 *
AnnaBridge 189:f392fc9709a3 51 * Current version: 2.0.1
AnnaBridge 189:f392fc9709a3 52 *
AnnaBridge 189:f392fc9709a3 53 * Change log:
AnnaBridge 189:f392fc9709a3 54 * - Version 2.0.1
AnnaBridge 189:f392fc9709a3 55 * - add support for KL8x and KL28Z
AnnaBridge 189:f392fc9709a3 56 * - update default OSCDIV for K81 to divide by 2
AnnaBridge 189:f392fc9709a3 57 */
AnnaBridge 189:f392fc9709a3 58 #define FSL_TRNG_DRIVER_VERSION (MAKE_VERSION(2, 0, 1))
AnnaBridge 189:f392fc9709a3 59 /*@}*/
AnnaBridge 189:f392fc9709a3 60
AnnaBridge 189:f392fc9709a3 61 /*! @brief TRNG sample mode. Used by trng_config_t. */
AnnaBridge 189:f392fc9709a3 62 typedef enum _trng_sample_mode
AnnaBridge 189:f392fc9709a3 63 {
AnnaBridge 189:f392fc9709a3 64 kTRNG_SampleModeVonNeumann = 0U, /*!< Use von Neumann data in both Entropy shifter and Statistical Checker. */
AnnaBridge 189:f392fc9709a3 65 kTRNG_SampleModeRaw = 1U, /*!< Use raw data into both Entropy shifter and Statistical Checker. */
AnnaBridge 189:f392fc9709a3 66 kTRNG_SampleModeVonNeumannRaw =
AnnaBridge 189:f392fc9709a3 67 2U /*!< Use von Neumann data in Entropy shifter. Use raw data into Statistical Checker. */
AnnaBridge 189:f392fc9709a3 68 } trng_sample_mode_t;
AnnaBridge 189:f392fc9709a3 69
AnnaBridge 189:f392fc9709a3 70 /*! @brief TRNG clock mode. Used by trng_config_t. */
AnnaBridge 189:f392fc9709a3 71 typedef enum _trng_clock_mode
AnnaBridge 189:f392fc9709a3 72 {
AnnaBridge 189:f392fc9709a3 73 kTRNG_ClockModeRingOscillator = 0U, /*!< Ring oscillator is used to operate the TRNG (default). */
AnnaBridge 189:f392fc9709a3 74 kTRNG_ClockModeSystem = 1U /*!< System clock is used to operate the TRNG. This is for test use only, and
AnnaBridge 189:f392fc9709a3 75 indeterminate results may occur. */
AnnaBridge 189:f392fc9709a3 76 } trng_clock_mode_t;
AnnaBridge 189:f392fc9709a3 77
AnnaBridge 189:f392fc9709a3 78 /*! @brief TRNG ring oscillator divide. Used by trng_config_t. */
AnnaBridge 189:f392fc9709a3 79 typedef enum _trng_ring_osc_div
AnnaBridge 189:f392fc9709a3 80 {
AnnaBridge 189:f392fc9709a3 81 kTRNG_RingOscDiv0 = 0U, /*!< Ring oscillator with no divide */
AnnaBridge 189:f392fc9709a3 82 kTRNG_RingOscDiv2 = 1U, /*!< Ring oscillator divided-by-2. */
AnnaBridge 189:f392fc9709a3 83 kTRNG_RingOscDiv4 = 2U, /*!< Ring oscillator divided-by-4. */
AnnaBridge 189:f392fc9709a3 84 kTRNG_RingOscDiv8 = 3U /*!< Ring oscillator divided-by-8. */
AnnaBridge 189:f392fc9709a3 85 } trng_ring_osc_div_t;
AnnaBridge 189:f392fc9709a3 86
AnnaBridge 189:f392fc9709a3 87 /*! @brief Data structure for definition of statistical check limits. Used by trng_config_t. */
AnnaBridge 189:f392fc9709a3 88 typedef struct _trng_statistical_check_limit
AnnaBridge 189:f392fc9709a3 89 {
AnnaBridge 189:f392fc9709a3 90 uint32_t maximum; /*!< Maximum limit.*/
AnnaBridge 189:f392fc9709a3 91 uint32_t minimum; /*!< Minimum limit.*/
AnnaBridge 189:f392fc9709a3 92 } trng_statistical_check_limit_t;
AnnaBridge 189:f392fc9709a3 93
AnnaBridge 189:f392fc9709a3 94 /*!
AnnaBridge 189:f392fc9709a3 95 * @brief Data structure for the TRNG initialization
AnnaBridge 189:f392fc9709a3 96 *
AnnaBridge 189:f392fc9709a3 97 * This structure initializes the TRNG by calling the the TRNG_Init() function.
AnnaBridge 189:f392fc9709a3 98 * It contains all TRNG configurations.
AnnaBridge 189:f392fc9709a3 99 */
AnnaBridge 189:f392fc9709a3 100 typedef struct _trng_user_config
AnnaBridge 189:f392fc9709a3 101 {
AnnaBridge 189:f392fc9709a3 102 bool lock; /*!< @brief Disable programmability of TRNG registers. */
AnnaBridge 189:f392fc9709a3 103 trng_clock_mode_t clockMode; /*!< @brief Clock mode used to operate TRNG.*/
AnnaBridge 189:f392fc9709a3 104 trng_ring_osc_div_t ringOscDiv; /*!< @brief Ring oscillator divide used by TRNG. */
AnnaBridge 189:f392fc9709a3 105 trng_sample_mode_t sampleMode; /*!< @brief Sample mode of the TRNG ring oscillator. */
AnnaBridge 189:f392fc9709a3 106 /* Seed Control*/
AnnaBridge 189:f392fc9709a3 107 uint16_t
AnnaBridge 189:f392fc9709a3 108 entropyDelay; /*!< @brief Entropy Delay. Defines the length (in system clocks) of each Entropy sample taken. */
AnnaBridge 189:f392fc9709a3 109 uint16_t sampleSize; /*!< @brief Sample Size. Defines the total number of Entropy samples that will be taken during
AnnaBridge 189:f392fc9709a3 110 Entropy generation. */
AnnaBridge 189:f392fc9709a3 111 uint16_t
AnnaBridge 189:f392fc9709a3 112 sparseBitLimit; /*!< @brief Sparse Bit Limit which defines the maximum number of
AnnaBridge 189:f392fc9709a3 113 * consecutive samples that may be discarded before an error is generated.
AnnaBridge 189:f392fc9709a3 114 * This limit is used only for during von Neumann sampling (enabled by TRNG_HAL_SetSampleMode()).
AnnaBridge 189:f392fc9709a3 115 * Samples are discarded if two consecutive raw samples are both 0 or both 1. If
AnnaBridge 189:f392fc9709a3 116 * this discarding occurs for a long period of time, it indicates that there is
AnnaBridge 189:f392fc9709a3 117 * insufficient Entropy. */
AnnaBridge 189:f392fc9709a3 118 /* Statistical Check Parameters.*/
AnnaBridge 189:f392fc9709a3 119 uint8_t retryCount; /*!< @brief Retry count. It defines the number of times a statistical check may fails
AnnaBridge 189:f392fc9709a3 120 * during the TRNG Entropy Generation before generating an error. */
AnnaBridge 189:f392fc9709a3 121 uint8_t longRunMaxLimit; /*!< @brief Largest allowable number of consecutive samples of all 1, or all 0,
AnnaBridge 189:f392fc9709a3 122 * that is allowed during the Entropy generation. */
AnnaBridge 189:f392fc9709a3 123 trng_statistical_check_limit_t
AnnaBridge 189:f392fc9709a3 124 monobitLimit; /*!< @brief Maximum and minimum limits for statistical check of number of ones/zero detected
AnnaBridge 189:f392fc9709a3 125 during entropy generation. */
AnnaBridge 189:f392fc9709a3 126 trng_statistical_check_limit_t
AnnaBridge 189:f392fc9709a3 127 runBit1Limit; /*!< @brief Maximum and minimum limits for statistical check of number of runs of length 1
AnnaBridge 189:f392fc9709a3 128 detected during entropy generation. */
AnnaBridge 189:f392fc9709a3 129 trng_statistical_check_limit_t
AnnaBridge 189:f392fc9709a3 130 runBit2Limit; /*!< @brief Maximum and minimum limits for statistical check of number of runs of length 2
AnnaBridge 189:f392fc9709a3 131 detected during entropy generation. */
AnnaBridge 189:f392fc9709a3 132 trng_statistical_check_limit_t
AnnaBridge 189:f392fc9709a3 133 runBit3Limit; /*!< @brief Maximum and minimum limits for statistical check of number of runs of length 3
AnnaBridge 189:f392fc9709a3 134 detected during entropy generation. */
AnnaBridge 189:f392fc9709a3 135 trng_statistical_check_limit_t
AnnaBridge 189:f392fc9709a3 136 runBit4Limit; /*!< @brief Maximum and minimum limits for statistical check of number of runs of length 4
AnnaBridge 189:f392fc9709a3 137 detected during entropy generation. */
AnnaBridge 189:f392fc9709a3 138 trng_statistical_check_limit_t
AnnaBridge 189:f392fc9709a3 139 runBit5Limit; /*!< @brief Maximum and minimum limits for statistical check of number of runs of length 5
AnnaBridge 189:f392fc9709a3 140 detected during entropy generation. */
AnnaBridge 189:f392fc9709a3 141 trng_statistical_check_limit_t runBit6PlusLimit; /*!< @brief Maximum and minimum limits for statistical check of
AnnaBridge 189:f392fc9709a3 142 number of runs of length 6 or more detected during entropy
AnnaBridge 189:f392fc9709a3 143 generation. */
AnnaBridge 189:f392fc9709a3 144 trng_statistical_check_limit_t
AnnaBridge 189:f392fc9709a3 145 pokerLimit; /*!< @brief Maximum and minimum limits for statistical check of "Poker Test". */
AnnaBridge 189:f392fc9709a3 146 trng_statistical_check_limit_t
AnnaBridge 189:f392fc9709a3 147 frequencyCountLimit; /*!< @brief Maximum and minimum limits for statistical check of entropy sample frequency
AnnaBridge 189:f392fc9709a3 148 count. */
AnnaBridge 189:f392fc9709a3 149 } trng_config_t;
AnnaBridge 189:f392fc9709a3 150
AnnaBridge 189:f392fc9709a3 151 /*******************************************************************************
AnnaBridge 189:f392fc9709a3 152 * API
AnnaBridge 189:f392fc9709a3 153 *******************************************************************************/
AnnaBridge 189:f392fc9709a3 154
AnnaBridge 189:f392fc9709a3 155 #if defined(__cplusplus)
AnnaBridge 189:f392fc9709a3 156 extern "C" {
AnnaBridge 189:f392fc9709a3 157 #endif
AnnaBridge 189:f392fc9709a3 158
AnnaBridge 189:f392fc9709a3 159 /*!
AnnaBridge 189:f392fc9709a3 160 * @brief Initializes the user configuration structure to default values.
AnnaBridge 189:f392fc9709a3 161 *
AnnaBridge 189:f392fc9709a3 162 * This function initializes the configuration structure to default values. The default
AnnaBridge 189:f392fc9709a3 163 * values are as follows.
AnnaBridge 189:f392fc9709a3 164 * @code
AnnaBridge 189:f392fc9709a3 165 * user_config->lock = 0;
AnnaBridge 189:f392fc9709a3 166 * user_config->clockMode = kTRNG_ClockModeRingOscillator;
AnnaBridge 189:f392fc9709a3 167 * user_config->ringOscDiv = kTRNG_RingOscDiv0; Or to other kTRNG_RingOscDiv[2|8] depending on the platform.
AnnaBridge 189:f392fc9709a3 168 * user_config->sampleMode = kTRNG_SampleModeRaw;
AnnaBridge 189:f392fc9709a3 169 * user_config->entropyDelay = 3200;
AnnaBridge 189:f392fc9709a3 170 * user_config->sampleSize = 2500;
AnnaBridge 189:f392fc9709a3 171 * user_config->sparseBitLimit = TRNG_USER_CONFIG_DEFAULT_SPARSE_BIT_LIMIT;
AnnaBridge 189:f392fc9709a3 172 * user_config->retryCount = 63;
AnnaBridge 189:f392fc9709a3 173 * user_config->longRunMaxLimit = 34;
AnnaBridge 189:f392fc9709a3 174 * user_config->monobitLimit.maximum = 1384;
AnnaBridge 189:f392fc9709a3 175 * user_config->monobitLimit.minimum = 1116;
AnnaBridge 189:f392fc9709a3 176 * user_config->runBit1Limit.maximum = 405;
AnnaBridge 189:f392fc9709a3 177 * user_config->runBit1Limit.minimum = 227;
AnnaBridge 189:f392fc9709a3 178 * user_config->runBit2Limit.maximum = 220;
AnnaBridge 189:f392fc9709a3 179 * user_config->runBit2Limit.minimum = 98;
AnnaBridge 189:f392fc9709a3 180 * user_config->runBit3Limit.maximum = 125;
AnnaBridge 189:f392fc9709a3 181 * user_config->runBit3Limit.minimum = 37;
AnnaBridge 189:f392fc9709a3 182 * user_config->runBit4Limit.maximum = 75;
AnnaBridge 189:f392fc9709a3 183 * user_config->runBit4Limit.minimum = 11;
AnnaBridge 189:f392fc9709a3 184 * user_config->runBit5Limit.maximum = 47;
AnnaBridge 189:f392fc9709a3 185 * user_config->runBit5Limit.minimum = 1;
AnnaBridge 189:f392fc9709a3 186 * user_config->runBit6PlusLimit.maximum = 47;
AnnaBridge 189:f392fc9709a3 187 * user_config->runBit6PlusLimit.minimum = 1;
AnnaBridge 189:f392fc9709a3 188 * user_config->pokerLimit.maximum = 26912;
AnnaBridge 189:f392fc9709a3 189 * user_config->pokerLimit.minimum = 24445;
AnnaBridge 189:f392fc9709a3 190 * user_config->frequencyCountLimit.maximum = 25600;
AnnaBridge 189:f392fc9709a3 191 * user_config->frequencyCountLimit.minimum = 1600;
AnnaBridge 189:f392fc9709a3 192 * @endcode
AnnaBridge 189:f392fc9709a3 193 *
AnnaBridge 189:f392fc9709a3 194 * @param user_config User configuration structure.
AnnaBridge 189:f392fc9709a3 195 * @return If successful, returns the kStatus_TRNG_Success. Otherwise, it returns an error.
AnnaBridge 189:f392fc9709a3 196 */
AnnaBridge 189:f392fc9709a3 197 status_t TRNG_GetDefaultConfig(trng_config_t *userConfig);
AnnaBridge 189:f392fc9709a3 198
AnnaBridge 189:f392fc9709a3 199 /*!
AnnaBridge 189:f392fc9709a3 200 * @brief Initializes the TRNG.
AnnaBridge 189:f392fc9709a3 201 *
AnnaBridge 189:f392fc9709a3 202 * This function initializes the TRNG.
AnnaBridge 189:f392fc9709a3 203 * When called, the TRNG entropy generation starts immediately.
AnnaBridge 189:f392fc9709a3 204 *
AnnaBridge 189:f392fc9709a3 205 * @param base TRNG base address
AnnaBridge 189:f392fc9709a3 206 * @param userConfig Pointer to the initialization configuration structure.
AnnaBridge 189:f392fc9709a3 207 * @return If successful, returns the kStatus_TRNG_Success. Otherwise, it returns an error.
AnnaBridge 189:f392fc9709a3 208 */
AnnaBridge 189:f392fc9709a3 209 status_t TRNG_Init(TRNG_Type *base, const trng_config_t *userConfig);
AnnaBridge 189:f392fc9709a3 210
AnnaBridge 189:f392fc9709a3 211 /*!
AnnaBridge 189:f392fc9709a3 212 * @brief Shuts down the TRNG.
AnnaBridge 189:f392fc9709a3 213 *
AnnaBridge 189:f392fc9709a3 214 * This function shuts down the TRNG.
AnnaBridge 189:f392fc9709a3 215 *
AnnaBridge 189:f392fc9709a3 216 * @param base TRNG base address.
AnnaBridge 189:f392fc9709a3 217 */
AnnaBridge 189:f392fc9709a3 218 void TRNG_Deinit(TRNG_Type *base);
AnnaBridge 189:f392fc9709a3 219
AnnaBridge 189:f392fc9709a3 220 /*!
AnnaBridge 189:f392fc9709a3 221 * @brief Gets random data.
AnnaBridge 189:f392fc9709a3 222 *
AnnaBridge 189:f392fc9709a3 223 * This function gets random data from the TRNG.
AnnaBridge 189:f392fc9709a3 224 *
AnnaBridge 189:f392fc9709a3 225 * @param base TRNG base address.
AnnaBridge 189:f392fc9709a3 226 * @param data Pointer address used to store random data.
AnnaBridge 189:f392fc9709a3 227 * @param dataSize Size of the buffer pointed by the data parameter.
AnnaBridge 189:f392fc9709a3 228 * @return random data
AnnaBridge 189:f392fc9709a3 229 */
AnnaBridge 189:f392fc9709a3 230 status_t TRNG_GetRandomData(TRNG_Type *base, void *data, size_t dataSize);
AnnaBridge 189:f392fc9709a3 231
AnnaBridge 189:f392fc9709a3 232 #if defined(__cplusplus)
AnnaBridge 189:f392fc9709a3 233 }
AnnaBridge 189:f392fc9709a3 234 #endif
AnnaBridge 189:f392fc9709a3 235
AnnaBridge 189:f392fc9709a3 236 /*! @}*/
AnnaBridge 189:f392fc9709a3 237
AnnaBridge 189:f392fc9709a3 238 #endif /* FSL_FEATURE_SOC_TRNG_COUNT */
AnnaBridge 189:f392fc9709a3 239 #endif /*_FSL_TRNG_H_*/