Overview

The MCUXpresso SDK provides a peripheral driver for the True Random Number Generator (TRNG) module of MCUXpresso SDK devices.

The True Random Number Generator is a hardware accelerator module that generates a 512-bit entropy as needed by an entropy consuming module or by other post processing functions. A typical entropy consumer is a pseudo random number generator (PRNG) which can be implemented to achieve both true randomness and cryptographic strength random numbers using the TRNG output as its entropy seed. The entropy generated by a TRNG is intended for direct use by functions that generate secret keys, per-message secrets, random challenges, and other similar quantities used in cryptographic algorithms.

TRNG Initialization

Define the TRNG user configuration structure. Use TRNG_InitUserConfigDefault() function to set it to default TRNG configuration values.
Initialize the TRNG module, call the TRNG_Init() function, and pass the user configuration structure. This function automatically enables the TRNG module and its clock. After that, the TRNG is enabled and the entropy generation starts working.
To disable the TRNG module, call the TRNG_Deinit() function.

Get random data from TRNG

TRNG_GetRandomData() function gets random data from the TRNG module.

This example code shows how to initialize and get random data from the TRNG driver.

Refer to the driver examples codes located at <SDK_ROOT>/boards/<BOARD>/driver_examples/trng

Data Structures
struct	_trng_statistical_check_limit
	Data structure for definition of statistical check limits. More...

struct	_trng_user_config
	Data structure for the TRNG initialization. More...

Typedefs
typedef enum _trng_sample_mode	trng_sample_mode_t
	TRNG sample mode. More...

typedef enum _trng_clock_mode	trng_clock_mode_t
	TRNG clock mode. More...

typedef enum _trng_ring_osc_div	trng_ring_osc_div_t
	TRNG ring oscillator divide. More...

typedef struct _trng_statistical_check_limit	trng_statistical_check_limit_t
	Data structure for definition of statistical check limits. More...

typedef struct _trng_user_config	trng_config_t
	Data structure for the TRNG initialization. More...

Enumerations
enum	_trng_sample_mode { kTRNG_SampleModeVonNeumann = 0U, kTRNG_SampleModeRaw = 1U, kTRNG_SampleModeVonNeumannRaw }
	TRNG sample mode. More...

enum	_trng_clock_mode { kTRNG_ClockModeRingOscillator = 0U, kTRNG_ClockModeSystem = 1U }
	TRNG clock mode. More...

enum	_trng_ring_osc_div { kTRNG_RingOscDiv0 = 0U, kTRNG_RingOscDiv2 = 1U, kTRNG_RingOscDiv4 = 2U, kTRNG_RingOscDiv8 = 3U }
	TRNG ring oscillator divide. More...

Functions
status_t	TRNG_GetDefaultConfig (trng_config_t *userConfig)
	Initializes the user configuration structure to default values. More...

status_t	TRNG_Init (TRNG_Type base, const trng_config_t userConfig)
	Initializes the TRNG. More...

void	TRNG_Deinit (TRNG_Type *base)
	Shuts down the TRNG. More...

status_t	TRNG_GetRandomData (TRNG_Type base, void data, size_t dataSize)
	Gets random data. More...

Driver version
#define	FSL_TRNG_DRIVER_VERSION (MAKE_VERSION(2, 0, 16))
	TRNG driver version 2.0.16. More...

Data Structure Documentation

struct _trng_statistical_check_limit

Used by trng_config_t.

Data Fields
uint32_t	maximum
	Maximum limit. More...

uint32_t	minimum
	Minimum limit. More...

Field Documentation

uint32_t _trng_statistical_check_limit::maximum

uint32_t _trng_statistical_check_limit::minimum

struct _trng_user_config

This structure initializes the TRNG by calling the TRNG_Init() function. It contains all TRNG configurations.

Data Fields
bool	lock
	Disable programmability of TRNG registers. More...

trng_clock_mode_t	clockMode
	Clock mode used to operate TRNG. More...

trng_ring_osc_div_t	ringOscDiv
	Ring oscillator divide used by TRNG. More...

trng_sample_mode_t	sampleMode
	Sample mode of the TRNG ring oscillator. More...

uint16_t	entropyDelay
	Entropy Delay. More...

uint16_t	sampleSize
	Sample Size. More...

uint16_t	sparseBitLimit
	Sparse Bit Limit which defines the maximum number of consecutive samples that may be discarded before an error is generated. More...

uint8_t	retryCount
	Retry count. More...

uint8_t	longRunMaxLimit
	Largest allowable number of consecutive samples of all 1, or all 0, that is allowed during the Entropy generation. More...

trng_statistical_check_limit_t	monobitLimit
	Maximum and minimum limits for statistical check of number of ones/zero detected during entropy generation. More...

trng_statistical_check_limit_t	runBit1Limit
	Maximum and minimum limits for statistical check of number of runs of length 1 detected during entropy generation. More...

trng_statistical_check_limit_t	runBit2Limit
	Maximum and minimum limits for statistical check of number of runs of length 2 detected during entropy generation. More...

trng_statistical_check_limit_t	runBit3Limit
	Maximum and minimum limits for statistical check of number of runs of length 3 detected during entropy generation. More...

trng_statistical_check_limit_t	runBit4Limit
	Maximum and minimum limits for statistical check of number of runs of length 4 detected during entropy generation. More...

trng_statistical_check_limit_t	runBit5Limit
	Maximum and minimum limits for statistical check of number of runs of length 5 detected during entropy generation. More...

trng_statistical_check_limit_t	runBit6PlusLimit
	Maximum and minimum limits for statistical check of number of runs of length 6 or more detected during entropy generation. More...

trng_statistical_check_limit_t	pokerLimit
	Maximum and minimum limits for statistical check of "Poker Test". More...

trng_statistical_check_limit_t	frequencyCountLimit
	Maximum and minimum limits for statistical check of entropy sample frequency count. More...

Field Documentation

bool _trng_user_config::lock

trng_clock_mode_t _trng_user_config::clockMode

trng_ring_osc_div_t _trng_user_config::ringOscDiv

trng_sample_mode_t _trng_user_config::sampleMode

uint16_t _trng_user_config::entropyDelay

Defines the length (in system clocks) of each Entropy sample taken.

uint16_t _trng_user_config::sampleSize

Defines the total number of Entropy samples that will be taken during Entropy generation.

uint16_t _trng_user_config::sparseBitLimit

This limit is used only for during von Neumann sampling (enabled by TRNG_HAL_SetSampleMode()). Samples are discarded if two consecutive raw samples are both 0 or both 1. If this discarding occurs for a long period of time, it indicates that there is insufficient Entropy.

uint8_t _trng_user_config::retryCount

It defines the number of times a statistical check may fails during the TRNG Entropy Generation before generating an error.

uint8_t _trng_user_config::longRunMaxLimit

trng_statistical_check_limit_t _trng_user_config::monobitLimit

trng_statistical_check_limit_t _trng_user_config::runBit1Limit

trng_statistical_check_limit_t _trng_user_config::runBit2Limit

trng_statistical_check_limit_t _trng_user_config::runBit3Limit

trng_statistical_check_limit_t _trng_user_config::runBit4Limit

trng_statistical_check_limit_t _trng_user_config::runBit5Limit

trng_statistical_check_limit_t _trng_user_config::runBit6PlusLimit

trng_statistical_check_limit_t _trng_user_config::pokerLimit

trng_statistical_check_limit_t _trng_user_config::frequencyCountLimit

Macro Definition Documentation

#define FSL_TRNG_DRIVER_VERSION (MAKE_VERSION(2, 0, 16))

Current version: 2.0.16

Change log:

version 2.0.16
- Added support for Dual oscillator mode.
version 2.0.15
- Changed TRNG_USER_CONFIG_DEFAULT_XXX values according to latest reccomended by design team.
version 2.0.14
- add support for RW610 and RW612
version 2.0.13
- After deepsleep it might return error, added clearing bits in TRNG_GetRandomData() and generating new entropy.
- Modified reloading entropy in TRNG_GetRandomData(), for some data length it doesn't reloading entropy correctly.
version 2.0.12
- For KW34A4_SERIES, KW35A4_SERIES, KW36A4_SERIES set TRNG_USER_CONFIG_DEFAULT_OSC_DIV to kTRNG_RingOscDiv8.
version 2.0.11
- Add clearing pending errors in TRNG_Init().
version 2.0.10
- Fixed doxygen issues.
version 2.0.9
- Fix HIS_CCM metrics issues.
version 2.0.8
- For K32L2A41A_SERIES set TRNG_USER_CONFIG_DEFAULT_OSC_DIV to kTRNG_RingOscDiv4.
version 2.0.7
- Fix MISRA 2004 issue rule 12.5.
version 2.0.6
- For KW35Z4_SERIES set TRNG_USER_CONFIG_DEFAULT_OSC_DIV to kTRNG_RingOscDiv8.
version 2.0.5
- Add possibility to define default TRNG configuration by device specific preprocessor macros for FRQMIN, FRQMAX and OSCDIV.
version 2.0.4
- Fix MISRA-2012 issues.
Version 2.0.3
- update TRNG_Init to restart entropy generation
Version 2.0.2
- fix MISRA issues
Version 2.0.1
- add support for KL8x and KL28Z
- update default OSCDIV for K81 to divide by 2

Typedef Documentation

typedef enum _trng_sample_mode trng_sample_mode_t

Used by trng_config_t.

typedef enum _trng_clock_mode trng_clock_mode_t

Used by trng_config_t.

typedef enum _trng_ring_osc_div trng_ring_osc_div_t

Used by trng_config_t.

typedef struct _trng_statistical_check_limit trng_statistical_check_limit_t

Used by trng_config_t.

typedef struct _trng_user_config trng_config_t

This structure initializes the TRNG by calling the TRNG_Init() function. It contains all TRNG configurations.

Enumeration Type Documentation

enum _trng_sample_mode

Used by trng_config_t.

Enumerator

kTRNG_SampleModeVonNeumann

Use von Neumann data in both Entropy shifter and Statistical Checker.

kTRNG_SampleModeRaw

Use raw data into both Entropy shifter and Statistical Checker.

kTRNG_SampleModeVonNeumannRaw

Use von Neumann data in Entropy shifter.

Use raw data into Statistical Checker.

enum _trng_clock_mode

Used by trng_config_t.

Enumerator

kTRNG_ClockModeRingOscillator

Ring oscillator is used to operate the TRNG (default).

kTRNG_ClockModeSystem

System clock is used to operate the TRNG.

This is for test use only, and indeterminate results may occur.

enum _trng_ring_osc_div

Used by trng_config_t.

Enumerator
kTRNG_RingOscDiv0	Ring oscillator with no divide.
kTRNG_RingOscDiv2	Ring oscillator divided-by-2.
kTRNG_RingOscDiv4	Ring oscillator divided-by-4.
kTRNG_RingOscDiv8	Ring oscillator divided-by-8.

Function Documentation

status_t TRNG_GetDefaultConfig ( trng_config_t * userConfig )

This function initializes the configuration structure to default values. The default values are platform dependent.

Parameters

userConfig User configuration structure.

Returns: If successful, returns the kStatus_TRNG_Success. Otherwise, it returns an error.

status_t TRNG_Init	(	TRNG_Type *	base,
		const trng_config_t *	userConfig
	)

This function initializes the TRNG. When called, the TRNG entropy generation starts immediately.

Parameters

base	TRNG base address
userConfig	Pointer to the initialization configuration structure.

Returns: If successful, returns the kStatus_TRNG_Success. Otherwise, it returns an error.

void TRNG_Deinit ( TRNG_Type * base )

This function shuts down the TRNG.

Parameters

base	TRNG base address.

status_t TRNG_GetRandomData	(	TRNG_Type *	base,
		void *	data,
		size_t	dataSize
	)

This function gets random data from the TRNG.

Parameters

base	TRNG base address.
data	Pointer address used to store random data.
dataSize	Size of the buffer pointed by the data parameter.

Returns: random data

Overview

TRNG Initialization

Get random data from TRNG

Data Structures

Typedefs

Enumerations

Functions

Driver version

Data Structure Documentation

Data Fields

Field Documentation

Data Fields

Field Documentation

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation