[trng] True Random Number Generator

Functions
void	TRNGConfigure (uint32_t ui32MinSamplesPerCycle, uint32_t ui32MaxSamplesPerCycle, uint32_t ui32ClocksPerSample)
	Configure the true random number generator. More...
static void	TRNGEnable (void)
	Enable the TRNG. More...
static void	TRNGDisable (void)
	Disable the TRNG module. More...
uint32_t	TRNGNumberGet (uint32_t ui32Word)
	Get a random number from the generator. More...
static uint32_t	TRNGStatusGet (void)
	Get the status of the TRNG. More...
static void	TRNGReset (void)
	Reset the TRNG. More...
static void	TRNGIntEnable (uint32_t ui32IntFlags)
	Enables individual TRNG interrupt sources. More...
static void	TRNGIntDisable (uint32_t ui32IntFlags)
	Disables individual TRNG interrupt sources. More...
static uint32_t	TRNGIntStatus (bool bMasked)
	Gets the current interrupt status of the TRNG module. More...
static void	TRNGIntClear (uint32_t ui32IntFlags)
	Clears TRNG interrupt sources. More...
static void	TRNGIntRegister (void(*pfnHandler)(void))
	Registers an interrupt handler for a TRNG interrupt. More...
static void	TRNGIntUnregister (void)
	Unregisters an interrupt handler for a TRNG interrupt. More...

Detailed Description

Function Documentation

void TRNGConfigure	(	uint32_t	ui32MinSamplesPerCycle,
		uint32_t	ui32MaxSamplesPerCycle,
		uint32_t	ui32ClocksPerSample
	)

Configure the true random number generator.

Use this function to set the minimum and maximum number of samples required in each generation of a new random number.

Parameters

ui32MinSamplesPerCycle	is the minimum number of samples per each generated random number. Constraints: Value must be bigger than or equal to 2^6 and less than 2^14. The 6 LSBs of the argument are truncated. If the value is zero, the number of samples is fixed to the value determined by ui32MaxSamplesPerCycle. To ensure same entropy in all generated random numbers the value 0 should be used.
ui32MaxSamplesPerCycle	is the maximum number of samples per each generated random number. Constraints: Value must be between 2^8 and 2^24 (both included). The 8 LSBs of the argument are truncated. Value 0 and 2^24 both give the highest possible value.
ui32ClocksPerSample	is the number of clock cycles for each time a new sample is generated from the FROs. 0 : Every sample. 1 : Every second sample. ... 15 : Every 16. sample.

Returns

None

Definition at line 60 of file trng.c.

static void TRNGDisable ( void  )

inlinestatic

Disable the TRNG module.

Returns

None

Definition at line 165 of file trng.h.

static void TRNGEnable ( void  )

inlinestatic

Enable the TRNG.

Enable the TRNG to start preparing a random number.

Returns

None

Definition at line 151 of file trng.h.

static void TRNGIntClear ( uint32_t  ui32IntFlags )

inlinestatic

Clears TRNG interrupt sources.

The specified TRNG interrupt sources are cleared, so that they no longer assert. This function must be called in the interrupt handler to keep the interrupt from being recognized again immediately upon exit.

Note

Due to write buffers and synchronizers in the system it may take several clock cycles from a register write clearing an event in a module and until the event is actually cleared in the NVIC of the system CPU. It is recommended to clear the event source early in the interrupt service routine (ISR) to allow the event clear to propagate to the NVIC before returning from the ISR. At the same time, an early event clear allows new events of the same type to be pended instead of ignored if the event is cleared later in the ISR. It is the responsibility of the programmer to make sure that enough time has passed before returning from the ISR to avoid false re-triggering of the cleared event. A simple, although not necessarily optimal, way of clearing an event before returning from the ISR is:

1. Write to clear event (interrupt source). (buffered write)
2. Dummy read from the event source module. (making sure the write has propagated)
3. Wait two system CPU clock cycles (user code or two NOPs). (allowing cleared event to propagate through any synchronizers)

Parameters

ui32IntFlags

is a bit mask of the interrupt sources to be cleared. The parameter is the bitwise OR of any of the following: TRNG_NUMBER_READY TRNG_FRO_SHUTDOWN

Returns

None

Definition at line 364 of file trng.h.

static void TRNGIntDisable ( uint32_t  ui32IntFlags )

inlinestatic

Disables individual TRNG interrupt sources.

This function disables the indicated TRNG interrupt sources. Only the sources that are enabled can be reflected to the processor interrupt; disabled sources have no effect on the processor.

Parameters

ui32IntFlags

is the bit mask of the interrupt sources to be disabled. The parameter is the bitwise OR of any of the following: TRNG_NUMBER_READY TRNG_FRO_SHUTDOWN

Returns

None

Definition at line 281 of file trng.h.

static void TRNGIntEnable ( uint32_t  ui32IntFlags )

inlinestatic

Enables individual TRNG interrupt sources.

This function enables the indicated TRNG interrupt sources. Only the sources that are enabled can be reflected to the processor interrupt; disabled sources have no effect on the processor.

Parameters

ui32IntFlags

is the bit mask of the interrupt sources to be enabled. The parameter is the bitwise OR of any of the following: TRNG_NUMBER_READY TRNG_FRO_SHUTDOWN

Returns

None

Definition at line 250 of file trng.h.

static void TRNGIntRegister ( void(*)(void)  pfnHandler )

inlinestatic

Registers an interrupt handler for a TRNG interrupt.

This function does the actual registering of the interrupt handler. This function enables the global interrupt in the interrupt controller; specific UART interrupts must be enabled via TRNGIntEnable(). It is the interrupt handler's responsibility to clear the interrupt source.

Parameters

pfnHandler

is a pointer to the function to be called when the UART interrupt occurs.

Returns

None

See also

IntRegister() for important information about registering interrupt handlers.

Definition at line 397 of file trng.h.

Here is the call graph for this function:

static uint32_t TRNGIntStatus ( bool  bMasked )

inlinestatic

Gets the current interrupt status of the TRNG module.

This function returns the interrupt status for the specified TRNG. Either the raw interrupt status or the status of interrupts that are allowed to reflect to the processor can be returned.

Parameters

bMasked

selects either raw or masked interrupt status. true : Masked interrupt. false : Raw interrupt.

Returns

Returns the current interrupt status, enumerated as:

• TRNG_NUMBER_READY
• TRNG_FRO_SHUTDOWN

Definition at line 313 of file trng.h.

static void TRNGIntUnregister ( void  )

inlinestatic

Unregisters an interrupt handler for a TRNG interrupt.

This function does the actual unregistering of the interrupt handler. It clears the handler to be called when a Crypto interrupt occurs. This function also masks off the interrupt in the interrupt controller so that the interrupt handler no longer is called.

Returns

None

See also

IntRegister() for important information about registering interrupt handlers.

Definition at line 426 of file trng.h.

Here is the call graph for this function:

uint32_t TRNGNumberGet

(

uint32_t

ui32Word

)

Get a random number from the generator.

Use this function to get either the high or low part of the 64 bit generated number.

Note

Data from this register is only valid if the TRNG has produced a number. Use TRNGStatusGet() to poll the for status. After calling this function a new random number will be generated.

Parameters

ui32Word

determines if whether to return the high or low 32 bits. TRNG_HI_WORD TRNG_LOW_WORD

Returns

Return either the high or low part of the 64 bit generated random number.

Definition at line 95 of file trng.c.

static void TRNGReset ( void  )

inlinestatic

Reset the TRNG.

Use this function to reset the TRNG module. Reset will be low for approximately 5 clock cycles.

Returns

None

Definition at line 225 of file trng.h.

static uint32_t TRNGStatusGet ( void  )

inlinestatic

Get the status of the TRNG.

Use this function to retrieve the status of the TRNG.

Returns

Returns the current status of the TRNG module. The returned status is a bitwise OR'ed combination of:

• TRNG_NUMBER_READY
• TRNG_FRO_SHUTDOWN
• TRNG_NEED_CLOCK

Definition at line 206 of file trng.h.

Macro Definition Documentation

#define TRNG_FRO_SHUTDOWN   0x00000002

Definition at line 96 of file trng.h.

Referenced by TRNGIntClear(), TRNGIntDisable(), and TRNGIntEnable().

#define TRNG_HI_WORD   0x00000001

Definition at line 99 of file trng.h.

Referenced by TRNGNumberGet().

#define TRNG_LOW_WORD   0x00000002

Definition at line 100 of file trng.h.

Referenced by TRNGNumberGet().

#define TRNG_NEED_CLOCK   0x80000000

Definition at line 97 of file trng.h.

#define TRNG_NUMBER_READY   0x00000001

Definition at line 95 of file trng.h.

Referenced by TRNGIntClear(), TRNGIntDisable(), and TRNGIntEnable().