TRNG Peripheral Driver

Overview

This section describes the programming interface of the TRNG Peripheral driver. The TRNG driver provides an easy way to initialize and configure the TRNG.

TRNG Initialization

1. Define the TRNG user configuration structure. Use TRNG_DRV_InitUserConfigDefault() function to set it to default TRNG configuration values.
2. Initialize the TRNG module, call the TRNG_DRV_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.
3. To disable the TRNG module, call the TRNG_DRV_Deinit() function.

Get random data from TRNG

1. TRNG_DRV_GetRandomData() function gets random data from the TRNG module.

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

{
    trng_user_config_t  trngConfig;
    trng_status_t       status;
    uint32_t            data;

    /* Initialize TRNG configuration structure.
    TRNG_DRV_InitUserConfigDefault(&trngConfig);

    /* Initialize TRNG 
    status = TRNG_DRV_Init(0, &trngConfig);

    if (status == kStatus_TRNG_Success)
    {
        /* Read Random data
        if((status = TRNG_DRV_GetRandomData(0, data, sizeof(data))) == kStatus_TRNG_Success)
        {
            /* Print data
            PRINTF("Random = 0x%X\r\n", i, data );

            PRINTF("Succeed.\r\n");
        }
        else
        {
            PRINTF("TRNG GetRandomData failed! (0x%x)\r\n", status);
        }

        /* Deinitialize TRNG
        TRNG_DRV_Deinit(0);
    }
    else
    {
        PRINTF("TRNG initialization failed!\r\n");
    }
}

TRNG interrupt

The TRNG interrupt is used only when the TRNG_DRV_RTOS_SLEEP configuration parameter is set to 1. It allows putting the calling RTOS task to "sleep" during the TRNG blocking entropy generation. The TRNG asserts an interrupt either when generated a Frequency Count Fail, Entropy Valid or Error Interrupt. By default it is enabled for RTOS and disabled for Bare Metal. It is optional and may be disabled.

1. Enable the TRNG interrupt with the TRNG_DRV_RTOS_SLEEP set to 1.
2. Configure the TRNG interrupt priority using NVIC_SetPriority(g_trngIrqId[0], <priority>).
3. Define the TRNG IRQ function, adding fsl_trng_irq.c file to the application project using the TRNG driver.

   Note

   If MQX RTOS is used, it requires a special installation of interrupt handlers. Add the following MQX RTOS interrupt handler installation to an application before the RTNG initialization:

   OSA_InstallIntHandler(g_trngIrqId[0], MQX_TRNG0_IRQHandler);  

Data Structures
struct	trng_user_config_t
	Data structure for the TRNG initialization. More...

Macros
#define	TRNG_DRV_RTOS_MULTI_THREAD   (USE_RTOS)
	Enables/disables multi-thread support in TRNG driver. More...
#define	TRNG_DRV_RTOS_SLEEP   (USE_RTOS)
	Enables/disables putting the calling task to "sleep" during the TRNG blocking entropy generation. More...

Functions
trng_status_t	TRNG_DRV_Init (uint32_t instance, const trng_user_config_t *user_config)
	Initializes the TRNG. More...
trng_status_t	TRNG_DRV_Deinit (uint32_t instance)
	Shuts down the TRNG. More...
trng_status_t	TRNG_DRV_InitUserConfigDefault (trng_user_config_t *user_config)
	Initializes the user configuration structure to default values. More...
trng_status_t	TRNG_DRV_GetRandomData (uint32_t instance, void *data, uint32_t data_size)
	Gets random data. More...
void	TRNG_DRV_IRQHandler (uint32_t instance)
	TRNG interrupt handler. More...

Variables
TRNG_Type *const	g_trngBase []
	Table of base addresses for TRNG instances. More...
const IRQn_Type	g_trngIrqId []
	Table to save TRNG IRQ enumeration numbers defined in the CMSIS header file. More...

---

Data Structure Documentation

struct trng_user_config_t

This structure initializes the TRNG by calling the the TRNG_DRV_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_t::lock

Default is 0.

trng_clock_mode_t trng_user_config_t::clockMode

Default is kTRNGClockModeRingOscillator.

trng_ring_osc_div_t trng_user_config_t::ringOscDiv

Default is kTRNGRingOscDiv0.

trng_sample_mode_t trng_user_config_t::sampleMode

Default is kTRNGSampleModeRaw.

uint16_t trng_user_config_t::entropyDelay

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

uint16_t trng_user_config_t::sampleSize

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

uint16_t trng_user_config_t::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. Default is 63.

uint8_t trng_user_config_t::retryCount

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

uint8_t trng_user_config_t::longRunMaxLimit

Default is 34.

trng_statistical_check_limit_t trng_user_config_t::monobitLimit

trng_statistical_check_limit_t trng_user_config_t::runBit1Limit

trng_statistical_check_limit_t trng_user_config_t::runBit2Limit

trng_statistical_check_limit_t trng_user_config_t::runBit3Limit

trng_statistical_check_limit_t trng_user_config_t::runBit4Limit

trng_statistical_check_limit_t trng_user_config_t::runBit5Limit

trng_statistical_check_limit_t trng_user_config_t::runBit6PlusLimit

trng_statistical_check_limit_t trng_user_config_t::pokerLimit

trng_statistical_check_limit_t trng_user_config_t::frequencyCountLimit

Macro Definition Documentation

#define TRNG_DRV_RTOS_MULTI_THREAD   (USE_RTOS)

It is achieved by mutex locking of critical sections. and is enabled by default for RTOS. It is optional and may be disabled if TRNG is used only by one RTOS task.

#define TRNG_DRV_RTOS_SLEEP   (USE_RTOS)

If enabled, it requires using of TRNG IRQ handler. and is enabled by default for RTOS. It is optional and may be disabled.

Function Documentation

trng_status_t TRNG_DRV_Init	(	uint32_t	instance,
		const trng_user_config_t *	user_config
	)

This function initializes the TRNG. When called, the TRNG runs immediately according to the specifications in the configuration.

Parameters

instance	TRNG instance ID.
user_config	Pointer to initialize configuration structure.

Returns

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

trng_status_t TRNG_DRV_Deinit

(

uint32_t

instance

)

This function shuts down the TRNG.

Parameters

instance

TRNG instance ID

Returns

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

trng_status_t TRNG_DRV_InitUserConfigDefault

(

trng_user_config_t *

user_config

)

This function fills the user configuration structure with default TRNG settings.

Parameters

user_config

User configuration structure.

Returns

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

trng_status_t TRNG_DRV_GetRandomData	(	uint32_t	instance,
		void *	data,
		uint32_t	data_size
	)

This function gets random data from the TRNG.

Parameters

instance	TRNG instance ID
data	Pointer address used to store random data
data_size	Size of the buffer pointed by the data parameter

Returns

random data

void TRNG_DRV_IRQHandler

(

uint32_t

instance

)

This function handles the TRNG interrupt.

Parameters

instance

TRNG instance ID

Variable Documentation

TRNG_Type* const g_trngBase[]

const IRQn_Type g_trngIrqId[]