Microchip® Advanced Software Framework

 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
SAM True Random Number Generator (TRNG) Driver

This driver for Atmel® | SMART ARM®-based microcontrollers provides an interface for the configuration and management of the device's True Random Number Generator functionality.

The following driver API modes are covered by this manual:

The following peripheral is used by this module:

The following devices can use this module:

The outline of this documentation is as follows:

Prerequisites

There are no prerequisites for this module.

Module Overview

This driver provides an interface for the TRNG functions on the device.

As soon as the TRNG is enabled, the module provides a new 32-bit random data, for every 84 CLK_TRNG_APB clock cycles.

Special Considerations

There are no special considerations for this module.

Extra Information

For extra information, see Extra Information for TRNG Driver. This includes:

Examples

For a list of examples related to this driver, see Examples for TRNG Driver.

API Overview

Data Structures

struct  trng_config
 TRNG module configuration structure. More...
 
struct  trng_events
 TRNG event enable/disable structure. More...
 
struct  trng_module
 TRNG software device instance structure. More...
 

Typedefs

typedef void(* trng_callback_t )(struct trng_module *const module_inst)
 Type definition for a TRNG module callback function. More...
 

Enumerations

enum  trng_callback { TRNG_CALLBACK_READ_BUFFER = 0 }
 Enum for possible callback types for the TRNG module. More...
 
enum  trng_job_type { TRNG_JOB_READ_BUFFER }
 Enum for the possible types of TRNG asynchronous jobs that may be issued to the driver. More...
 

Variables

struct trng_module_trng_instance
 

Driver Initialization and Configuration

enum status_code trng_init (struct trng_module *const module_inst, Trng *const hw, struct trng_config *const config)
 Initializes a hardware TRNG module instance. More...
 
static void trng_get_config_defaults (struct trng_config *const config)
 Initializes all members of a TRNG configuration structure to safe defaults. More...
 
static void trng_enable (struct trng_module *const module_inst)
 Enables a TRNG that was previously configured. More...
 
static void trng_disable (struct trng_module *const module_inst)
 Disables a TRNG that was previously enabled. More...
 
static void trng_enable_events (struct trng_module *const module_inst, struct trng_events *const events)
 Enables a TRNG event output. More...
 
static void trng_disable_events (struct trng_module *const module_inst, struct trng_events *const events)
 Disables a TRNG event output. More...
 

Read TRNG Result

static enum status_code trng_read (struct trng_module *const module_inst, uint32_t *result)
 Read the random data result. More...
 

Callback Management

enum status_code trng_register_callback (struct trng_module *const module, trng_callback_t callback_func, enum trng_callback callback_type)
 Registers a callback. More...
 
enum status_code trng_unregister_callback (struct trng_module *module, enum trng_callback callback_type)
 Unregisters a callback. More...
 
static void trng_enable_callback (struct trng_module *const module, enum trng_callback callback_type)
 Enables callback. More...
 
static void trng_disable_callback (struct trng_module *const module, enum trng_callback callback_type)
 Disables callback. More...
 

Job Management

enum status_code trng_read_buffer_job (struct trng_module *const module_inst, uint32_t *buffer, uint32_t number)
 Read multiple random data from TRNG. More...
 
enum status_code trng_get_job_status (struct trng_module *module_inst, enum trng_job_type type)
 Gets the status of a job. More...
 
void trng_abort_job (struct trng_module *module_inst, enum trng_job_type type)
 Aborts an ongoing job. More...
 

typedef void(* trng_callback_t)(struct trng_module *const module_inst)

Type definition for a TRNG module callback function.

Enum for possible callback types for the TRNG module.

Enumerator
TRNG_CALLBACK_READ_BUFFER 

Callback for specific number of random data ready.

Enum for the possible types of TRNG asynchronous jobs that may be issued to the driver.

Enumerator
TRNG_JOB_READ_BUFFER 

Asynchronous TRNG read into a user provided buffer.

void trng_abort_job ( struct trng_module module_inst,
enum trng_job_type  type 
)

Aborts an ongoing job.

Parameters
[in]module_instPointer to the TRNG software instance struct
[in]typeType of job to abort

References Assert, STATUS_ABORTED, and TRNG_JOB_READ_BUFFER.

static void trng_disable ( struct trng_module *const  module_inst)
inlinestatic

Disables a TRNG that was previously enabled.

Disables True Random Number Generator that was previously started via a call to trng_enable().

Parameters
[in]module_instSoftware instance for the True Random Number Generator peripheral

References Assert.

Referenced by run_trng_callback_read_test().

static void trng_disable_callback ( struct trng_module *const  module,
enum trng_callback  callback_type 
)
inlinestatic

Disables callback.

Disables the callback function registered by the trng_register_callback.

Parameters
[in]modulePointer to TRNG software instance struct
[in]callback_typeCallback type given by an enum

References Assert, and TRNG_CALLBACK_READ_BUFFER.

Referenced by run_trng_callback_read_test().

static void trng_disable_events ( struct trng_module *const  module_inst,
struct trng_events *const  events 
)
inlinestatic

Disables a TRNG event output.

Disables output events from the True Random Number Generator module. See Section Struct trng_events for a list of events this module supports.

Note
Events cannot be altered while the module is enabled.
Parameters
[in]module_instSoftware instance for the TRNG peripheral
[in]eventsStruct containing flags of events to disable

References Assert, and trng_events::generate_event_on_data_ready.

static void trng_enable ( struct trng_module *const  module_inst)
inlinestatic

Enables a TRNG that was previously configured.

Enables True Random Number Generator that was previously configured via a call to trng_init().

Parameters
[in]module_instSoftware instance for the True Random Number Generator peripheral

References Assert.

Referenced by run_trng_polling_read_test().

static void trng_enable_callback ( struct trng_module *const  module,
enum trng_callback  callback_type 
)
inlinestatic

Enables callback.

Enables the callback function registered by trng_register_callback. The callback function will be called from the interrupt handler when the conditions for the callback type are met.

Parameters
[in]modulePointer to TRNG software instance struct
[in]callback_typeCallback type given by an enum

References Assert.

Referenced by run_trng_callback_read_test().

static void trng_enable_events ( struct trng_module *const  module_inst,
struct trng_events *const  events 
)
inlinestatic

Enables a TRNG event output.

Enables output events from the True Random Number Generator module. See Section Struct trng_events for a list of events this module supports.

Note
Events cannot be altered while the module is enabled.
Parameters
[in]module_instSoftware instance for the TRNG peripheral
[in]eventsStruct containing flags of events to enable

References Assert, and trng_events::generate_event_on_data_ready.

static void trng_get_config_defaults ( struct trng_config *const  config)
inlinestatic

Initializes all members of a TRNG configuration structure to safe defaults.

Initializes all members of a given True Random Number Generator configuration structure to safe known default values. This function should be called on all new instances of these configuration structures before being modified by the user application.

The default configuration is as follows:

  • True Random Number Generator will not be stopped in standby sleep mode
Parameters
[out]configConfiguration structure to initialize to default values

References Assert, and trng_config::run_in_standby.

Referenced by run_trng_polling_read_test().

enum status_code trng_get_job_status ( struct trng_module module_inst,
enum trng_job_type  type 
)

Gets the status of a job.

Gets the status of an ongoing or the last job.

Parameters
[in]module_instPointer to the TRNG software instance struct
[in]typeType of job to abort
Returns
Status of the job.

References Assert, STATUS_ERR_INVALID_ARG, and TRNG_JOB_READ_BUFFER.

enum status_code trng_init ( struct trng_module *const  module_inst,
Trng *const  hw,
struct trng_config *const  config 
)

Initializes a hardware TRNG module instance.

Enables the clock and initializes the TRNG module, based on the given configuration values.

Parameters
[in,out]module_instPointer to the software module instance struct
[in]hwPointer to the TRNG hardware module
[in]configPointer to the TRNG configuration options struct
Returns
Status of the initialization procedure.
Return values
STATUS_OKThe module was initialized successfully

References _trng_instance, Assert, trng_config::run_in_standby, STATUS_OK, system_apb_clock_set_mask(), and SYSTEM_CLOCK_APB_APBC.

Referenced by run_trng_polling_read_test().

static enum status_code trng_read ( struct trng_module *const  module_inst,
uint32_t *  result 
)
inlinestatic

Read the random data result.

Reads the random data result.

Parameters
[in]module_instPointer to the TRNG software instance struct
[out]resultPointer to store the result value in
Returns
Status of the TRNG read request.
Return values
STATUS_OKThe result was retrieved successfully
STATUS_BUSYA random result was not ready

References Assert, STATUS_BUSY, and STATUS_OK.

Referenced by run_trng_polling_read_test().

enum status_code trng_read_buffer_job ( struct trng_module *const  module_inst,
uint32_t *  buffer,
uint32_t  number 
)

Read multiple random data from TRNG.

As soon as the TRNG is enabled, the module provides a new 32-bits random data for every 84 CLK_TRNG_APB clock cycles.

Parameters
[in]module_instPointer to the TRNG software instance struct
[in]numberNumber of random data to get
[out]bufferBuffer to store the random data
Returns
Status of the job start.
Return values
STATUS_OKThe read job was started successfully and is in progress
STATUS_BUSYThe TRNG is already busy with another job

References Assert, STATUS_BUSY, and STATUS_OK.

Referenced by run_trng_callback_read_test().

enum status_code trng_register_callback ( struct trng_module *const  module,
trng_callback_t  callback_func,
const enum trng_callback  callback_type 
)

Registers a callback.

Registers a callback function which is implemented by the user.

Note
The callback must be enabled by trng_enable_callback, in order for the interrupt handler to call it when the conditions for the callback type is met.
Parameters
[in]modulePointer to TC software instance struct
[in]callback_funcPointer to callback function
[in]callback_typeCallback type given by an enum
Return values
STATUS_OKThe function exited successfully

References Assert, STATUS_OK, system_interrupt_enable(), and SYSTEM_INTERRUPT_MODULE_TRNG.

Referenced by run_trng_callback_read_test().

enum status_code trng_unregister_callback ( struct trng_module *const  module,
const enum trng_callback  callback_type 
)

Unregisters a callback.

Unregisters a callback function implemented by the user. The callback should be disabled before it is unregistered.

Parameters
[in]modulePointer to TC software instance struct
[in]callback_typeCallback type given by an enum
Return values
STATUS_OKThe function exited successfully

References Assert, STATUS_OK, system_interrupt_disable(), and SYSTEM_INTERRUPT_MODULE_TRNG.

struct trng_module* _trng_instance

Referenced by TRNG_Handler(), and trng_init().