[trng.h] 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 in the dynamic interrupt table. More...
static void	TRNGIntUnregister (void)
	Unregisters an interrupt handler for a TRNG interrupt in the dynamic interrupt table. 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

{
    uint32_t ui32Val;

    // Make sure the TRNG is disabled.
    ui32Val = HWREG(TRNG_BASE + TRNG_O_CTL) & ~TRNG_CTL_TRNG_EN;
    HWREG(TRNG_BASE + TRNG_O_CTL) = ui32Val;

    // Configure the startup number of samples.
    ui32Val &= ~TRNG_CTL_STARTUP_CYCLES_M;
    ui32Val |= ((( ui32MaxSamplesPerCycle >> 8 ) << TRNG_CTL_STARTUP_CYCLES_S ) & TRNG_CTL_STARTUP_CYCLES_M );
    HWREG(TRNG_BASE + TRNG_O_CTL) = ui32Val;

    // Configure the minimum and maximum number of samples pr generated number
    // and the number of clocks per sample.
    HWREG(TRNG_BASE + TRNG_O_CFG0) = (
        ((( ui32MaxSamplesPerCycle >> 8 ) << TRNG_CFG0_MAX_REFILL_CYCLES_S ) & TRNG_CFG0_MAX_REFILL_CYCLES_M ) |
        ((( ui32ClocksPerSample         ) << TRNG_CFG0_SMPL_DIV_S          ) & TRNG_CFG0_SMPL_DIV_M          ) |
        ((( ui32MinSamplesPerCycle >> 6 ) << TRNG_CFG0_MIN_REFILL_CYCLES_S ) & TRNG_CFG0_MIN_REFILL_CYCLES_M )   );
}

static void TRNGDisable ( void  )

inlinestatic

Disable the TRNG module.

Returns

None

{
    // Enable the TRNG
    HWREGBITW(TRNG_BASE + TRNG_O_CTL, TRNG_CTL_TRNG_EN_BITN) = 0;
}

static void TRNGEnable ( void  )

inlinestatic

Enable the TRNG.

Enable the TRNG to start preparing a random number.

Returns

None

{
    // Enable the TRNG.
    HWREGBITW(TRNG_BASE + TRNG_O_CTL, TRNG_CTL_TRNG_EN_BITN) = 1;
}

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

{
    // Check the arguments.
    ASSERT((ui32IntFlags & TRNG_NUMBER_READY) ||
           (ui32IntFlags & TRNG_FRO_SHUTDOWN));

    // Clear the requested interrupt sources.
    HWREG(TRNG_BASE + TRNG_O_IRQFLAGCLR) = ui32IntFlags;
}

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

{
    // Check the arguments.
    ASSERT((ui32IntFlags & TRNG_NUMBER_READY) ||
           (ui32IntFlags & TRNG_FRO_SHUTDOWN));

    // Disable the specified interrupts.
    HWREG(TRNG_BASE + TRNG_O_IRQFLAGMASK) &= ~ui32IntFlags;
}

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

{
    // Check the arguments.
    ASSERT((ui32IntFlags & TRNG_NUMBER_READY) ||
           (ui32IntFlags & TRNG_FRO_SHUTDOWN));

    // Enable the specified interrupts.
    HWREG(TRNG_BASE + TRNG_O_IRQFLAGMASK) |= ui32IntFlags;
}

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

inlinestatic

Registers an interrupt handler for a TRNG interrupt in the dynamic interrupt table.

Note

Only use this function if you want to use the dynamic vector table (in SRAM)!

This function registers a function as the interrupt handler for a specific interrupt and enables the corresponding interrupt in the interrupt controller.

Specific TRNG 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 TRNG interrupt occurs.

Returns

None

See also

IntRegister() for important information about registering interrupt handlers.

{
    // Register the interrupt handler.
    IntRegister(INT_TRNG_IRQ, pfnHandler);

    // Enable the TRNG interrupt.
    IntEnable(INT_TRNG_IRQ);
}

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

{
    uint32_t ui32Mask;

    // Return either the interrupt status or the raw interrupt status as
    // requested.
    if(bMasked)
    {
        ui32Mask = HWREG(TRNG_BASE + TRNG_O_IRQFLAGMASK);
        return(ui32Mask & HWREG(TRNG_BASE + TRNG_O_IRQFLAGSTAT));
    }
    else
    {
        return(HWREG(TRNG_BASE + TRNG_O_IRQFLAGSTAT) & 0x00000003);
    }
}

static void TRNGIntUnregister ( void  )

inlinestatic

Unregisters an interrupt handler for a TRNG interrupt in the dynamic interrupt table.

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.

{
    // Disable the interrupt.
    IntDisable(INT_TRNG_IRQ);

    // Unregister the interrupt handler.
    IntUnregister(INT_TRNG_IRQ);
}

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.

{
    uint32_t ui32RandomNumber;

    // Check the arguments.
    ASSERT((ui32Word == TRNG_HI_WORD) ||
           (ui32Word == TRNG_LOW_WORD));

    // Return the right requested part of the generated number.
    if(ui32Word == TRNG_HI_WORD)
    {
        ui32RandomNumber = HWREG(TRNG_BASE + TRNG_O_OUT1);
    }
    else
    {
        ui32RandomNumber = HWREG(TRNG_BASE + TRNG_O_OUT0);
    }

    // Initiate generation of new number.
    HWREG(TRNG_BASE + TRNG_O_IRQFLAGCLR) = 0x1;

    // Return the random number.
    return ui32RandomNumber;
}

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

{
    // Reset the TRNG.
    HWREG(TRNG_BASE + TRNG_O_SWRESET) = 1;
}

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

{
    // Return the status.
    return (HWREG(TRNG_BASE + TRNG_O_IRQFLAGSTAT));
}

Macro Definition Documentation

#define TRNG_FRO_SHUTDOWN   0x00000002

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

#define TRNG_HI_WORD   0x00000001

Referenced by TRNGNumberGet().

#define TRNG_LOW_WORD   0x00000002

Referenced by TRNGNumberGet().

#define TRNG_NEED_CLOCK   0x80000000

#define TRNG_NUMBER_READY   0x00000001

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