This driver for Atmel® | SMART ARM®-based microcontrollers provides an interface for the configuration and management of the device's peripheral event resources and users within the device, including enabling and disabling of peripheral source selection and synchronization of clock domains between various modules.

The following API modes is covered by this manual:

Polled API
Interrupt hook API

The following peripheral is used by this module:

EVSYS (Event System Management)

The following devices can use this module:

Atmel | SMART SAM D20/D21
Atmel | SMART SAM R21
Atmel | SMART SAM D09/D10/D11
Atmel | SMART SAM L21/L22
Atmel | SMART SAM DA1
Atmel | SMART SAM C20/C21
Atmel | SMART SAM HA1
Atmel | SMART SAM R30
Atmel | SMART SAM R34/R35

The outline of this documentation is as follows:

Prerequisites

There are no prerequisites for this module.

Module Overview

Peripherals within the SAM devices are capable of generating two types of actions in response to given stimulus; set a register flag for later intervention by the CPU (using interrupt or polling methods), or generate event signals, which can be internally routed directly to other peripherals within the device. The use of events allows for direct actions to be performed in one peripheral in response to a stimulus in another without CPU intervention. This can lower the overall power consumption of the system if the CPU is able to remain in sleep modes for longer periods (SleepWalking), and lowers the latency of the system response.

The event system is comprised of a number of freely configurable Event resources, plus a number of fixed Event Users. Each Event resource can be configured to select the input peripheral that will generate the events signal, as well as the synchronization path and edge detection mode. The fixed-function Event Users, connected to peripherals within the device, can then subscribe to an Event resource in a one-to-many relationship in order to receive events as they are generated. An overview of the event system chain is shown in the figure below.

There are many different events that can be routed in the device, which can then trigger many different actions. For example, an Analog Comparator module could be configured to generate an event when the input signal rises above the compare threshold, which then triggers a Timer Counter module to capture the current count value for later use.

Event Channels

The Event module in each device consists of several channels, which can be freely linked to an event generator (i.e. a peripheral within the device that is capable of generating events). Each channel can be individually configured to select the generator peripheral, signal path, and edge detection applied to the input event signal, before being passed to any event user(s).

Event channels can support multiple users within the device in a standardized manner. When an Event User is linked to an Event Channel, the channel will automatically handshake with all attached users to ensure that all modules correctly receive and acknowledge the event.

Event Users

Event Users are able to subscribe to an Event Channel, once it has been configured. Each Event User consists of a fixed connection to one of the peripherals within the device (for example, an ADC module, or Timer module) and is capable of being connected to a single Event Channel.

Edge Detection

For asynchronous events, edge detection on the event input is not possible, and the event signal must be passed directly between the event generator and event user. For synchronous and re-synchronous events, the input signal from the event generator must pass through an edge detection unit, so that only the rising, falling, or both edges of the event signal triggers an action in the event user.

Path Selection

The event system in the SAM devices supports three signal path types from the event generator to Event Users: asynchronous, synchronous, and re-synchronous events.

Asynchronous Paths

Asynchronous event paths allow for an asynchronous connection between the event generator and Event Users, when the source and destination peripherals share the same Generic Clock channel. In this mode the event is propagated between the source and destination directly to reduce the event latency, thus no edge detection is possible. The asynchronous event chain is shown in the figure below.

Note: Identically shaped borders in the diagram indicate a shared generic clock channel.

Synchronous Paths

The Synchronous event path should be used when edge detection or interrupts from the event channel are required, and the source event generator and the event channel shares the same Generic Clock channel. The synchronous event chain is shown in the figure below.

Not all peripherals support Synchronous event paths; refer to the device datasheet.

Note: Identically shaped borders in the diagram indicate a shared generic clock channel.

Re-synchronous Paths

Re-synchronous event paths are a special form of synchronous events, where when edge detection or interrupts from the event channel are required, but the event generator and the event channel use different Generic Clock channels. The re-synchronous path allows the Event System to synchronize the incoming event signal from the Event Generator to the clock of the Event System module to avoid missed events, at the cost of a higher latency due to the re-synchronization process. The re-synchronous event chain is shown in the figure below.

Not all peripherals support re-synchronous event paths; refer to the device datasheet.

Note: Identically shaped borders in the diagram indicate a shared generic clock channel.

Physical Connection

The diagram below shows how this module is interconnected within the device.

Configuring Events

For SAM devices, several steps are required to properly configure an event chain, so that hardware peripherals can respond to events generated by each other, as listed below.

Source Peripheral

The source peripheral (that will generate events) must be configured and enabled.
The source peripheral (that will generate events) must have an output event enabled.

Event System

An event system channel must be allocated and configured with the correct source peripheral selected as the channel's event generator.
The event system user must be configured and enabled, and attached to
event channel previously allocated.

Destination Peripheral

The destination peripheral (that will receive events) must be configured and enabled.
The destination peripheral (that will receive events) must have an input event enabled.

Special Considerations

There are no special considerations for this module.

Extra Information

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

Examples

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

API Overview

Modules
	Related Project(s)
	In this section you can find all the projects related to the SAM Event System (EVENTS) Driver.

Data Structures
struct	events_config
	Events configuration struct. More...

struct	events_hook
	Event hook. More...

struct	events_resource
	Event channel resource. More...

Macros
#define	EVSYS_ID_GEN_NONE 0
	No event generator definition. More...

Typedefs
typedef void(*	events_interrupt_hook )(struct events_resource *resource)

Enumerations
enum	events_edge_detect { EVENTS_EDGE_DETECT_NONE, EVENTS_EDGE_DETECT_RISING, EVENTS_EDGE_DETECT_FALLING, EVENTS_EDGE_DETECT_BOTH }
	Edge detect enum. More...

enum	events_interrupt_source { EVENTS_INTERRUPT_OVERRUN, EVENTS_INTERRUPT_DETECT }
	Interrupt source enumerator. More...

enum	events_path_selection { EVENTS_PATH_SYNCHRONOUS, EVENTS_PATH_RESYNCHRONIZED, EVENTS_PATH_ASYNCHRONOUS }
	Path selection enum. More...

Functions
enum status_code	events_ack_interrupt (struct events_resource *resource, enum events_interrupt_source source)
	Acknowledge an interrupt source. More...

enum status_code	events_add_hook (struct events_resource resource, struct events_hook hook)
	Insert hook into the event drivers interrupt hook queue. More...

enum status_code	events_allocate (struct events_resource resource, struct events_config config)
	Allocate an event channel and set configuration. More...

enum status_code	events_attach_user (struct events_resource *resource, uint8_t user_id)
	Attach user to the event channel. More...

enum status_code	events_create_hook (struct events_hook *hook, events_interrupt_hook hook_func)
	Initializes an interrupt hook for insertion in the event interrupt hook queue. More...

enum status_code	events_del_hook (struct events_resource resource, struct events_hook hook)
	Remove hook from the event drivers interrupt hook queue. More...

enum status_code	events_detach_user (struct events_resource *resource, uint8_t user_id)
	Detach a user peripheral from the event channel. More...

enum status_code	events_disable_interrupt_source (struct events_resource *resource, enum events_interrupt_source source)
	Disable interrupt source. More...

enum status_code	events_enable_interrupt_source (struct events_resource *resource, enum events_interrupt_source source)
	Enable interrupt source. More...

void	events_get_config_defaults (struct events_config *config)
	Initializes an event configurations struct to defaults. More...

uint8_t	events_get_free_channels (void)
	Get the number of free channels. More...

bool	events_is_busy (struct events_resource *resource)
	Check if a channel is busy. More...

bool	events_is_detected (struct events_resource *resource)
	Check if an event is detected on the event channel. More...

bool	events_is_interrupt_set (struct events_resource *resource, enum events_interrupt_source source)
	Check if interrupt source is set. More...

bool	events_is_overrun (struct events_resource *resource)
	Check if there has been an overrun situation on this channel. More...

bool	events_is_users_ready (struct events_resource *resource)
	Check if all users connected to the channel are ready. More...

enum status_code	events_release (struct events_resource *resource)
	Release allocated channel back the the resource pool. More...

enum status_code	events_trigger (struct events_resource *resource)
	Trigger software event. More...

#define EVSYS_ID_GEN_NONE 0

No event generator definition.

Use this to disable any peripheral event input to a channel. This can be useful if you only want to use a channel for software generated events. Definition for no generator selection.

Referenced by events_get_config_defaults().

typedef void(* events_interrupt_hook)(struct events_resource *resource)

enum events_edge_detect

Edge detect enum.

Event channel edge detect setting.

Enumerator
EVENTS_EDGE_DETECT_NONE	No event output.
EVENTS_EDGE_DETECT_RISING	Event on rising edge.
EVENTS_EDGE_DETECT_FALLING	Event on falling edge.
EVENTS_EDGE_DETECT_BOTH	Event on both edges.

enum events_interrupt_source

Interrupt source enumerator.

Interrupt source selector definitions.

Enumerator
EVENTS_INTERRUPT_OVERRUN	Overrun in event channel detected interrupt.
EVENTS_INTERRUPT_DETECT	Event signal propagation in event channel detected interrupt.

enum events_path_selection

Path selection enum.

Event channel path selection.

Enumerator
EVENTS_PATH_SYNCHRONOUS	Select the synchronous path for this event channel.
EVENTS_PATH_RESYNCHRONIZED	Select the resynchronizer path for this event channel.
EVENTS_PATH_ASYNCHRONOUS	Select the asynchronous path for this event channel.

enum status_code events_ack_interrupt	(	struct events_resource *	resource,
		enum events_interrupt_source	source
	)

Acknowledge an interrupt source.

Acknowledge an interrupt source so the interrupt state is cleared in hardware.

Parameters

[in]	resource	Pointer to an events_resource struct instance
[in]	source	One of the members in the events_interrupt_source enumerator

Returns: Status of the interrupt source.

Return values

STATUS_OK Interrupt source was acknowledged successfully

References _events_find_bit_position(), _events_inst, Assert, EVENTS_INTERRUPT_DETECT, EVENTS_INTERRUPT_OVERRUN, _events_module::interrupt_flag_ack_buffer, STATUS_ERR_INVALID_ARG, and STATUS_OK.

Referenced by event_counter().

enum status_code events_add_hook	(	struct events_resource *	resource,
		struct events_hook *	hook
	)

Insert hook into the event drivers interrupt hook queue.

Inserts a hook into the event drivers interrupt hook queue.

Parameters

[in]	resource	Pointer to an events_resource struct instance
[in]	hook	Pointer to an events_hook struct instance

Returns: Status of the insertion procedure.

Return values

STATUS_OK Insertion of hook went successful

References _events_inst, _events_module::hook_list, events_hook::next, NULL, events_hook::resource, STATUS_OK, system_interrupt_enable(), system_interrupt_is_enabled(), and SYSTEM_INTERRUPT_MODULE_EVSYS.

Referenced by configure_event_interrupt().

enum status_code events_allocate	(	struct events_resource *	resource,
		struct events_config *	config
	)

Allocate an event channel and set configuration.

Allocates an event channel from the event channel pool and sets the channel configuration.

Parameters

[out]	resource	Pointer to a events_resource struct instance
[in]	config	Pointer to a events_config struct

Returns: Status of the configuration procedure.

Return values

STATUS_OK	Allocation and configuration went successful
STATUS_ERR_NOT_FOUND	No free event channel found

References _events_find_first_free_channel_and_allocate(), Assert, events_config::clock_source, events_config::edge_detect, EVENTS_INVALID_CHANNEL, EVENTS_PATH_ASYNCHRONOUS, events_config::generator, events_config::path, system_gclk_chan_config::source_generator, STATUS_ERR_NOT_FOUND, STATUS_OK, system_gclk_chan_enable(), system_gclk_chan_get_config_defaults(), and system_gclk_chan_set_config().

Referenced by configure_event(), configure_event_channel(), configure_event_resource(), event_setup(), run_16bit_capture_and_compare_test(), run_capture_and_compare_test(), run_faultn_test(), run_faultx_test(), setup_asynchronous_event_test(), setup_resynchronous_event_test(), and setup_synchronous_event_test().

enum status_code events_attach_user	(	struct events_resource *	resource,
		uint8_t	user_id
	)

Attach user to the event channel.

Attach a user peripheral to the event channel to receive events.

Parameters

[in]	resource	Pointer to an events_resource struct instance
[in]	user_id	A number identifying the user peripheral found in the device header file

Returns: Status of the user attach procedure.

Return values

STATUS_OK No errors detected when attaching the event user

References Assert, and STATUS_OK.

Referenced by configure_event(), configure_event_resource(), configure_event_user(), event_setup(), run_16bit_capture_and_compare_test(), run_capture_and_compare_test(), run_faultn_test(), run_faultx_test(), setup_asynchronous_event_test(), setup_resynchronous_event_test(), and setup_synchronous_event_test().

enum status_code events_create_hook	(	struct events_hook *	hook,
		events_interrupt_hook	hook_func
	)

Initializes an interrupt hook for insertion in the event interrupt hook queue.

Initializes a hook structure so it is ready for insertion in the interrupt hook queue.

Parameters

[out]	hook	Pointer to an events_hook struct instance
[in]	hook_func	Pointer to a function containing the interrupt hook code

Returns: Status of the hook creation procedure.

Return values

STATUS_OK Creation and initialization of interrupt hook went successful

References events_hook::hook_func, events_hook::next, NULL, events_hook::resource, and STATUS_OK.

Referenced by configure_event_interrupt().

enum status_code events_del_hook	(	struct events_resource *	resource,
		struct events_hook *	hook
	)

Remove hook from the event drivers interrupt hook queue.

Removes a hook from the event drivers interrupt hook queue.

Parameters

[in]	resource	Pointer to an events_resource struct instance
[in]	hook	Pointer to an events_hook struct instance

Returns: Status of the removal procedure.

Return values

STATUS_OK	Removal of hook went successful
STATUS_ERR_NO_MEMORY	There are no hooks instances in the event driver interrupt hook list
STATUS_ERR_NOT_FOUND	Interrupt hook not found in the event drivers interrupt hook list

References _events_inst, _events_module::hook_list, events_hook::next, NULL, STATUS_ERR_NO_MEMORY, STATUS_ERR_NOT_FOUND, and STATUS_OK.

enum status_code events_detach_user	(	struct events_resource *	resource,
		uint8_t	user_id
	)

Detach a user peripheral from the event channel.

Deattach a user peripheral from the event channels so it does not receive any more events.

Parameters

[in]	resource	Pointer to an event_resource struct instance
[in]	user_id	A number identifying the user peripheral found in the device header file

Returns: Status of the user detach procedure.

Return values

STATUS_OK No errors detected when detaching the event user

References Assert, and STATUS_OK.

enum status_code events_disable_interrupt_source	(	struct events_resource *	resource,
		enum events_interrupt_source	source
	)

Disable interrupt source.

Disable an interrupt source so can trigger execution of an interrupt hook.

Parameters

[in]	resource	Pointer to an events_resource struct instance
[in]	source	One of the members in the events_interrupt_source enumerator

Returns: Status of the interrupt source enable procedure.

Return values

STATUS_OK	Enabling of the interrupt source went successful
STATUS_ERR_INVALID_ARG	Interrupt source does not exist

References _events_find_bit_position(), Assert, EVENTS_INTERRUPT_DETECT, EVENTS_INTERRUPT_OVERRUN, STATUS_ERR_INVALID_ARG, and STATUS_OK.

enum status_code events_enable_interrupt_source	(	struct events_resource *	resource,
		enum events_interrupt_source	source
	)

Enable interrupt source.

Enable an interrupt source so can trigger execution of an interrupt hook.

Parameters

[in]	resource	Pointer to an events_resource struct instance
[in]	source	One of the members in the events_interrupt_source enumerator

Returns: Status of the interrupt source enable procedure.

Return values

STATUS_OK	Enabling of the interrupt source was successful
STATUS_ERR_INVALID_ARG	Interrupt source does not exist

References _events_find_bit_position(), Assert, EVENTS_INTERRUPT_DETECT, EVENTS_INTERRUPT_OVERRUN, STATUS_ERR_INVALID_ARG, and STATUS_OK.

Referenced by configure_event_interrupt().

void events_get_config_defaults ( struct events_config * config )

Initializes an event configurations struct to defaults.

Initailizes an event configuration struct to predefined safe default settings.

Parameters

[in] config Pointer to an instance of struct events_config

References Assert, events_config::clock_source, events_config::edge_detect, EVENTS_EDGE_DETECT_RISING, EVENTS_PATH_SYNCHRONOUS, EVSYS_ID_GEN_NONE, GCLK_GENERATOR_0, events_config::generator, and events_config::path.

Referenced by configure_event(), configure_event_channel(), configure_event_resource(), event_setup(), run_16bit_capture_and_compare_test(), run_capture_and_compare_test(), run_faultn_test(), run_faultx_test(), setup_asynchronous_event_test(), setup_resynchronous_event_test(), and setup_synchronous_event_test().

uint8_t events_get_free_channels ( void )

Get the number of free channels.

Get the number of allocatable channels in the events system resource pool.

Returns: The number of free channels in the event system.

References _events_module::free_channels.

bool events_is_busy ( struct events_resource * resource )

Check if a channel is busy.

Check if a channel is busy, a channel stays busy until all users connected to the channel has handled an event.

Parameters

[in] resource Pointer to a events_resource struct instance

Returns: Status of the channels busy state.

Return values

true	One or more users connected to the channel has not handled the last event
false	All users are ready to handle new events

References _events_find_bit_position(), and Assert.

Referenced by events_release(), main(), run_resynchronous_event_test(), and run_synchronous_event_test().

bool events_is_detected ( struct events_resource * resource )

Check if an event is detected on the event channel.

Check if an event has been detected on the channel.

Note: This function will clear the event detected interrupt flag.

Parameters

[in] resource Pointer to an events_resource struct

Returns: Status of the event detection interrupt flag.

Return values

true	Event has been detected
false	Event has not been detected

References _events_find_bit_position(), and Assert.

bool events_is_interrupt_set	(	struct events_resource *	resource,
		enum events_interrupt_source	source
	)

Check if interrupt source is set.

Check if an interrupt source is set and should be processed.

Parameters

[in]	resource	Pointer to an events_resource struct instance
[in]	source	One of the members in the events_interrupt_source enumerator

Returns: Status of the interrupt source.

Return values

true	Interrupt source is set
false	Interrupt source is not set

References _events_find_bit_position(), _events_inst, Assert, EVENTS_INTERRUPT_DETECT, EVENTS_INTERRUPT_OVERRUN, and _events_module::interrupt_flag_buffer.

Referenced by event_counter().

bool events_is_overrun ( struct events_resource * resource )

Check if there has been an overrun situation on this channel.

Note: This function will clear the event overrun detected interrupt flag.

Parameters

[in] resource Pointer to an events_resource struct

Returns: Status of the event overrun interrupt flag.

Return values

true	Event overrun has been detected
false	Event overrun has not been detected

References _events_find_bit_position(), and Assert.

bool events_is_users_ready ( struct events_resource * resource )

Check if all users connected to the channel are ready.

Check if all users connected to the channel are ready to handle incoming events.

Parameters

[in] resource Pointer to an events_resource struct

Returns: The ready status of users connected to an event channel.

Return values

true	All the users connected to the event channel are ready to handle incoming events
false	One or more users connected to the event channel are not ready to handle incoming events

References _events_find_bit_position(), and Assert.

Referenced by run_resynchronous_event_test(), and run_synchronous_event_test().

enum status_code events_release ( struct events_resource * resource )

Release allocated channel back the the resource pool.

Release an allocated channel back to the resource pool to make it available for other purposes.

Parameters

[in] resource Pointer to an events_resource struct

Returns: Status of the channel release procedure.

Return values

STATUS_OK	No error was detected when the channel was released
STATUS_BUSY	One or more event users have not processed the last event
STATUS_ERR_NOT_INITIALIZED	Channel not allocated, and can therefore not be released

References _events_release_channel(), _events_module::allocated_channels, Assert, events_is_busy(), STATUS_BUSY, STATUS_ERR_NOT_INITIALIZED, and STATUS_OK.

Referenced by cleanup_asynchronous_event_test(), cleanup_resynchronous_event_test(), and cleanup_synchronous_event_test().

enum status_code events_trigger ( struct events_resource * resource )

Trigger software event.

Trigger an event by software.

Note: Software event works on either a synchronous path or resynchronized path, and edge detection must be configured to rising-edge detection.

Parameters

[in] resource Pointer to an events_resource struct

Returns: Status of the event software procedure.

Return values

STATUS_OK	No error was detected when the software tigger signal was issued
STATUS_ERR_UNSUPPORTED_DEV	If the channel path is asynchronous and/or the edge detection is not set to RISING

References Assert, EVENTS_EDGE_DETECT_RISING, EVENTS_PATH_ASYNCHRONOUS, STATUS_ERR_UNSUPPORTED_DEV, STATUS_OK, system_interrupt_enter_critical_section(), and system_interrupt_leave_critical_section().

Referenced by main().

Microchip® Advanced Software Framework

Prerequisites

Module Overview

Event Channels

Event Users

Edge Detection

Path Selection

Asynchronous Paths

Synchronous Paths

Re-synchronous Paths

Physical Connection

Configuring Events

Source Peripheral

Event System

event channel previously allocated.

Destination Peripheral

Special Considerations

Extra Information

Examples

API Overview

Modules

Data Structures

Macros

Typedefs

Enumerations

Functions