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:

Polled APIs
Callback APIs

The following peripheral is used by this module:

TRNG (True Random Number Generator)

The following devices can use this module:

Atmel | SMART SAM L21/L22

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 trng_callback

Enum for possible callback types for the TRNG module.

Enumerator
TRNG_CALLBACK_READ_BUFFER	Callback for specific number of random data ready.

enum trng_job_type

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_inst	Pointer to the TRNG software instance struct
[in]	type	Type 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_inst Software 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]	module	Pointer to TRNG software instance struct
[in]	callback_type	Callback 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_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.

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_inst Software 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]	module	Pointer to TRNG software instance struct
[in]	callback_type	Callback 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_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.

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] config Configuration 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_inst	Pointer to the TRNG software instance struct
[in]	type	Type 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_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

Returns: Status of the initialization procedure.

Return values

STATUS_OK The 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_inst	Pointer to the TRNG software instance struct
[out]	result	Pointer to store the result value in

Returns: Status of the TRNG read request.

Return values

STATUS_OK	The result was retrieved successfully
STATUS_BUSY	A 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_inst	Pointer to the TRNG software instance struct
[in]	number	Number of random data to get
[out]	buffer	Buffer to store the random data

Returns: Status of the job start.

Return values

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.

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