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:
There are no prerequisites for this module.
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.
There are no special considerations for this module.
For extra information, see Extra Information for TRNG Driver. This includes:
For a list of examples related to this driver, see Examples for TRNG Driver.
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 trng_callback |
enum trng_job_type |
void trng_abort_job | ( | struct trng_module * | module_inst, |
enum trng_job_type | type | ||
) |
Aborts an ongoing job.
[in] | module_inst | Pointer to the TRNG software instance struct |
[in] | type | Type of job to abort |
References Assert, STATUS_ABORTED, and TRNG_JOB_READ_BUFFER.
|
inlinestatic |
Disables a TRNG that was previously enabled.
Disables True Random Number Generator that was previously started via a call to trng_enable().
[in] | module_inst | Software instance for the True Random Number Generator peripheral |
References Assert.
|
inlinestatic |
Disables callback.
Disables the callback function registered by the trng_register_callback.
[in] | module | Pointer to TRNG software instance struct |
[in] | callback_type | Callback type given by an enum |
References Assert, and TRNG_CALLBACK_READ_BUFFER.
|
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.
[in] | module_inst | Software instance for the TRNG peripheral |
[in] | events | Struct containing flags of events to disable |
References Assert, and trng_events::generate_event_on_data_ready.
|
inlinestatic |
Enables a TRNG that was previously configured.
Enables True Random Number Generator that was previously configured via a call to trng_init().
[in] | module_inst | Software instance for the True Random Number Generator peripheral |
References Assert.
|
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.
[in] | module | Pointer to TRNG software instance struct |
[in] | callback_type | Callback type given by an enum |
References Assert.
|
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.
[in] | module_inst | Software instance for the TRNG peripheral |
[in] | events | Struct containing flags of events to enable |
References Assert, and trng_events::generate_event_on_data_ready.
|
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:
[out] | config | Configuration structure to initialize to default values |
References Assert, and trng_config::run_in_standby.
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.
[in] | module_inst | Pointer to the TRNG software instance struct |
[in] | type | Type of job to abort |
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.
[in,out] | module_inst | Pointer to the software module instance struct |
[in] | hw | Pointer to the TRNG hardware module |
[in] | config | Pointer to the TRNG configuration options struct |
STATUS_OK | The module was initialized successfully |
References _trng_instance, Assert, tcc_module::hw, trng_config::run_in_standby, STATUS_OK, system_apb_clock_set_mask(), and SYSTEM_CLOCK_APB_APBC.
|
inlinestatic |
Read the random data result.
Reads the random data result.
[in] | module_inst | Pointer to the TRNG software instance struct |
[out] | result | Pointer to store the result value in |
STATUS_OK | The result was retrieved successfully |
STATUS_BUSY | A random result was not ready |
References Assert, STATUS_BUSY, and STATUS_OK.
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.
[in] | module_inst | Pointer to the TRNG software instance struct |
[in] | number | Number of random data to get |
[out] | buffer | Buffer to store the random data |
STATUS_OK | The read job was started successfully and is in progress |
STATUS_BUSY | The TRNG is already busy with another job |
References Assert, STATUS_BUSY, and STATUS_OK.
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.
[in] | module | Pointer to TC software instance struct |
[in] | callback_func | Pointer to callback function |
[in] | callback_type | Callback type given by an enum |
STATUS_OK | The function exited successfully |
References Assert, STATUS_OK, system_interrupt_enable(), and SYSTEM_INTERRUPT_MODULE_TRNG.
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.
[in] | module | Pointer to TC software instance struct |
[in] | callback_type | Callback type given by an enum |
STATUS_OK | The 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().