TRNG driver implementation for a CC26XX device. More...

Modules
	TRNG_STATUS

Files
file	TRNGCC26XX.h
	TRNG driver implementation for a CC26XX device.

Data Structures
struct	TRNGCC26XX_Config
	TRNGCC26XX Global Configuration. More...

struct	TRNGCC26XX_HWAttrs
	TRNGCC26XX Hardware Attributes. More...

struct	TRNGCC26XX_Object
	TRNGCC26XX Object. More...

struct	TRNGCC26XX_Params
	TRNGCC26XX Parameters. More...

Macros
#define	TRNGCC26XX_CLOCKS_PER_SAMPLES_MAX 15

#define	TRNGCC26XX_ILLEGAL_PARAM_RETURN_VALUE 0

#define	TRNGCC26XX_MAX_SAMPLES_MAX 16777216

#define	TRNGCC26XX_MAX_SAMPLES_MIN 256

#define	TRNGCC26XX_MIN_SAMPLES_MAX 16384

#define	TRNGCC26XX_MIN_SAMPLES_MIN 64

Typedefs
typedef struct TRNGCC26XX_Config	TRNGCC26XX_Config
	TRNGCC26XX Global Configuration.

typedef struct TRNGCC26XX_Config *	TRNGCC26XX_Handle
	A handle that is returned from a TRNGCC26XX_open() call.

typedef struct TRNGCC26XX_HWAttrs	TRNGCC26XX_HWAttrs
	TRNGCC26XX Hardware Attributes. More...

typedef struct TRNGCC26XX_Object	TRNGCC26XX_Object
	TRNGCC26XX Object. More...

typedef struct TRNGCC26XX_Params	TRNGCC26XX_Params
	TRNGCC26XX Parameters. More...

Functions
void	TRNGCC26XX_close (TRNGCC26XX_Handle handle)
	Close the TRNG driver. More...

uint32_t	TRNGCC26XX_getNumber (TRNGCC26XX_Handle handle, TRNGCC26XX_Params params, int8_t status)
	This routine returns a 32 bit TRNG number. More...

void	TRNGCC26XX_init (void)
	TRNG Driver initialization. More...

int8_t	TRNGCC26XX_isParamValid (TRNGCC26XX_Params *params)
	Check that the parameters used are valid configurations. More...

TRNGCC26XX_Handle	TRNGCC26XX_open (uint8_t index)
	Open the TRNGCC26XX peripheral specified by the index value. This peripheral will be configured as specified by pParams. Alternatively, if pParams is NULL, default values will be used. More...

int8_t	TRNGCC26XX_Params_init (TRNGCC26XX_Params *params)
	Initialize TRNG configuration parameters to their defaults. More...

Detailed Description

TRNG driver implementation for a CC26XX device.

============================================================================

Driver Include

The TRNG header file should be included in an application as follows:

#include <ti/drivers/trng/TRNGCC26XX.h>

Overview

The TRNGCC26XX driver provides reentrant access to the TRNG module within the CC26XX. Reentrant access is controlled by creating a global critical section when requesting a random number. This critical section disables all Hwi's from running.

General Behavior

For code examples, see the use cases below.

Initialing the TRNGCC26XX Driver

TRNGCC26XX_init must be called prior to calling any other TRNGCC26xx API.
This function need only be called once per reset, but may be called multiple times without affect.

Opening the TRNGCC26XX Driver

TRNGCC26XX_open is used to open the driver prior to requesting a number.
This function powers on the TRNG peripheral.
Calling this function is optional, but will increase the latency of the first call to TRNGCC26XX_getNumber().
This function need only be called once per reset, but may be called multiple times without affect.

// Open the driver

TRNGCC26XX_open(Board_TRNG);

Initializing client parameters

Client parameters are optional. The Driver may be called with a NULL pointer to the client parameters, in which case it will use the default parameters. The default parameters configure the TRNG to produce 256 samples per cycle at 1 clock per sample. a call to TRNGCC26XX_getNumber with default values has a latency of 14us. Increasing any of the configuration parameters will result in an increase in latency.
The application initializes its parameters by calling TRNGCC26XX_Params_init() and passing a pointer to a TRNGCC26XX_Params variable as an argument to it.
This function can be called once or more to each initialization of parameters.
This function can be called once or more with the same TRNGCC26XX_Params variable.
The client parameter are initialized to valid default values, but may be changed by the client after this function returns. See trng.h for full details.

TRNGCC26XX_Params trngParams;
// Initialize parameters.
TRNGCC26XX_Params_init(&trngParams);
// Optionally modify trngParams
...

Validating client parameters

a client may optionally choose to validate its configuration parameters before attempting to generate a number.
when a client passes configuration parameters to TRNGCC26XX_getNumber these parameters will automatically be checked.

TRNGCC26XX_Params trngParams;
// Initialize parameters.
TRNGCC26XX_Params_init(&trngParams);
// Set client parameters.
trngParams.minSamplesPerCycle = 256;
trngParams.maxSamplesPerCycle = 256;
trngParams.clocksPerSample = 1;
// Validate parameters.
if (TRNGCC26XX_isParamValid(&trngParams) == TRNGCC26XX_STATUS_SUCCESS)
{
   // Parameters are valid.
}

Generating a random number

The TRNG may be called without client configuration parameters and pass a NULL pointer as an argument instead. This will result in the default values being used.
Using the initialized client configuration parameters, a random number can be generated.
an optional status flag pointer may be passed as an argument to check if the call successfully generated a random number.

TRNGCC26XX_Params trngParams;
uint8_t trngStatusFlag;
uint32_t trngNum1;
uint32_t trngNum2;
// Init driver.
TRNGCC26XX_init();
// Open TRNG peripheral.
TRNGCC26XX_open(Board_TRNG);
// Initialize parameters.
TRNGCC26XX_Params_init(&trngParams);
// Generate a random number.  Use optional status flag.
trngNum1 = TRNGCC26XX_getNumber(&trngParams, &trngStatusFlag);
// Check if status was okay
if (trngStatusFlag == TRNGCC26XX_STATUS_SUCCESS)
{
  // Random number was generated successfully
}
// Generate a second random number using the default values and no
// status flag.
trngNum2 = TRNGCC26XX_getNumber(NULL, NULL);

Supported transaction modes

all calls to TRNGCC26XX_getNumber are blocking until the TRNG has a new random number available.

Error handling

If an error occurs during a call to TRNGCC26XX_getNumber, the error status will be set into the status flag and the returned random number shall be 0. passing the status flag is optional.

Supported Functions

API function	Description
TRNGCC26XX_open()	Open driver (stub)
TRNGCC26XX_close()	Close driver (stub)
TRNGCC26XX_Params_init()	Initialize parameters for random number generation
TRNGCC26XX_init()	Generates a random number
TRNGCC26XX_isParamValid	Validate client configuration parameters

Macro Definition Documentation

§ TRNGCC26XX_CLOCKS_PER_SAMPLES_MAX

#define TRNGCC26XX_CLOCKS_PER_SAMPLES_MAX 15

Number of clocks cycles per sample must be between 1 (0) and 16 (15), inclusive.

§ TRNGCC26XX_ILLEGAL_PARAM_RETURN_VALUE

#define TRNGCC26XX_ILLEGAL_PARAM_RETURN_VALUE 0

Number returned from TRNGCC26XX_getNumber when invalid parameters are used.

§ TRNGCC26XX_MAX_SAMPLES_MAX

#define TRNGCC26XX_MAX_SAMPLES_MAX 16777216

Maximum samples per cycle range, maximum value

Maximum may be 0, or greater than or equal to 2^8 and less than or equal to 2^24.

§ TRNGCC26XX_MAX_SAMPLES_MIN

#define TRNGCC26XX_MAX_SAMPLES_MIN 256

Maximum samples per cycle range, minimum value

Maximum may be 0, or greater than or equal to 2^8 and less than or equal to 2^24.

§ TRNGCC26XX_MIN_SAMPLES_MAX

#define TRNGCC26XX_MIN_SAMPLES_MAX 16384

Minimum samples per cycle range, maximum value

Minimum may be 0, or greater than or equal to 2^6 and less than 2^14.

§ TRNGCC26XX_MIN_SAMPLES_MIN

#define TRNGCC26XX_MIN_SAMPLES_MIN 64

Minimum samples per cycle range, minimum value

Minimum may be 0, or greater than or equal to 2^6 and less than 2^14.

Typedef Documentation

§ TRNGCC26XX_HWAttrs

typedef struct TRNGCC26XX_HWAttrs TRNGCC26XX_HWAttrs

TRNGCC26XX Hardware Attributes.

Hardware Attribute structure for TRNG peripherals.

§ TRNGCC26XX_Object

typedef struct TRNGCC26XX_Object TRNGCC26XX_Object

TRNGCC26XX Object.

The application must not access any member variables of this structure!

§ TRNGCC26XX_Params

typedef struct TRNGCC26XX_Params TRNGCC26XX_Params

TRNGCC26XX Parameters.

This holds the TRNG configuration parameters to be used. see the functions description of TRNGConfigure() in trng.h for more information.

Function Documentation

§ TRNGCC26XX_close()

void TRNGCC26XX_close ( TRNGCC26XX_Handle handle )

Close the TRNG driver.

Precondition: Calling context: Hwi, Swi or Task.

Parameters

handle a TRNGCC26XX_Handle returned from TRNGCC26XX_open().

§ TRNGCC26XX_getNumber()

uint32_t TRNGCC26XX_getNumber	(	TRNGCC26XX_Handle	handle,
		TRNGCC26XX_Params *	params,
		int8_t *	status
	)

This routine returns a 32 bit TRNG number.

Precondition: params must be initialized with valid configurations. Calling context: Hwi, Swi or Task.

Parameters

params	- caller's configuration parameters. input parameter.
status	- a user provided pointer to a status flag in case of failure. This parameter may be left NULL. output parameter. TRNGCC26XX_STATUS_SUCCESS if successful. TRNGCC26XX_STATUS_ILLEGAL_PARAM if params is null or configuration is illegal.
handle	a TRNGCC26XX_Handle returned from TRNGCC26XX_open

Returns: A 32 bit TRNG number.

§ TRNGCC26XX_init()

void TRNGCC26XX_init ( void )

TRNG Driver initialization.

Precondition: Calling context: Hwi, Swi or Task.

§ TRNGCC26XX_isParamValid()

int8_t TRNGCC26XX_isParamValid ( TRNGCC26XX_Params * params )

Check that the parameters used are valid configurations.

Precondition: params must be initialized with valid configurations. Calling context: Hwi, Swi or Task.

Parameters

params - caller's configuration parameters. input parameter.

Returns: TRNGCC26XX_STATUS_SUCCESS if params is a valid configuration. TRNGCC26XX_STATUS_ILLEGAL_PARAM if params is an invalid configuration.

§ TRNGCC26XX_open()

TRNGCC26XX_Handle TRNGCC26XX_open ( uint8_t index )

Open the TRNGCC26XX peripheral specified by the index value. This peripheral will be configured as specified by pParams. Alternatively, if pParams is NULL, default values will be used.

Precondition: Calling context: Hwi, Swi or Task.

Parameters

index Logical peripheral Number indexed in the HWAttrs table.

Returns: a TRNGCC26XX_Handle

§ TRNGCC26XX_Params_init()

int8_t TRNGCC26XX_Params_init ( TRNGCC26XX_Params * params )

Initialize TRNG configuration parameters to their defaults.

Precondition: Calling context: Hwi, Swi or Task.

Parameters

params - TRNG configuration parameters. input parameter.

Returns: TRNGCC26XX_STATUS_SUCCESS if successful. TRNGCC26XX_STATUS_ILLEGAL_PARAM if params is NULL.

Modules

Files

Data Structures

Macros

Typedefs

Functions

Detailed Description

Driver Include

Overview

General Behavior

Initialing the TRNGCC26XX Driver

Opening the TRNGCC26XX Driver

Initializing client parameters

Validating client parameters

Generating a random number

Supported transaction modes

Error handling

Supported Functions

Macro Definition Documentation

§ TRNGCC26XX_CLOCKS_PER_SAMPLES_MAX

§ TRNGCC26XX_ILLEGAL_PARAM_RETURN_VALUE

§ TRNGCC26XX_MAX_SAMPLES_MAX

§ TRNGCC26XX_MAX_SAMPLES_MIN

§ TRNGCC26XX_MIN_SAMPLES_MAX

§ TRNGCC26XX_MIN_SAMPLES_MIN

Typedef Documentation

§ TRNGCC26XX_HWAttrs

§ TRNGCC26XX_Object

§ TRNGCC26XX_Params

Function Documentation

§ TRNGCC26XX_close()

§ TRNGCC26XX_getNumber()

§ TRNGCC26XX_init()

§ TRNGCC26XX_isParamValid()

§ TRNGCC26XX_open()

§ TRNGCC26XX_Params_init()