Microchip® Advanced Software Framework

 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
SAM Event System (EVENTS) Driver

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:

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

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

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

Event System

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

    event channel previously allocated.

Destination Peripheral

  1. The destination peripheral (that will receive events) must be configured and enabled.
  2. 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

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)

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.

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.

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]resourcePointer to an events_resource struct instance
[in]sourceOne of the members in the events_interrupt_source enumerator
Returns
Status of the interrupt source.
Return values
STATUS_OKInterrupt 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.

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]resourcePointer to an events_resource struct instance
[in]hookPointer to an events_hook struct instance
Returns
Status of the insertion procedure.
Return values
STATUS_OKInsertion of hook went successful

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

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]resourcePointer to a events_resource struct instance
[in]configPointer to a events_config struct
Returns
Status of the configuration procedure.
Return values
STATUS_OKAllocation and configuration went successful
STATUS_ERR_NOT_FOUNDNo 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_resource().

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]resourcePointer to an events_resource struct instance
[in]user_idA number identifying the user peripheral found in the device header file
Returns
Status of the user attach procedure.
Return values
STATUS_OKNo errors detected when attaching the event user

References Assert, and STATUS_OK.

Referenced by configure_event_resource().

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]hookPointer to an events_hook struct instance
[in]hook_funcPointer to a function containing the interrupt hook code
Returns
Status of the hook creation procedure.
Return values
STATUS_OKCreation and initialization of interrupt hook went successful

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

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]resourcePointer to an events_resource struct instance
[in]hookPointer to an events_hook struct instance
Returns
Status of the removal procedure.
Return values
STATUS_OKRemoval of hook went successful
STATUS_ERR_NO_MEMORYThere are no hooks instances in the event driver interrupt hook list
STATUS_ERR_NOT_FOUNDInterrupt hook not found in the event drivers interrupt hook list

References _events_inst, _events_module::hook_list, events_hook::next, 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]resourcePointer to an event_resource struct instance
[in]user_idA number identifying the user peripheral found in the device header file
Returns
Status of the user detach procedure.
Return values
STATUS_OKNo 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]resourcePointer to an events_resource struct instance
[in]sourceOne of the members in the events_interrupt_source enumerator
Returns
Status of the interrupt source enable procedure.
Return values
STATUS_OKEnabling of the interrupt source went successful
STATUS_ERR_INVALID_ARGInterrupt 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]resourcePointer to an events_resource struct instance
[in]sourceOne of the members in the events_interrupt_source enumerator
Returns
Status of the interrupt source enable procedure.
Return values
STATUS_OKEnabling of the interrupt source was successful
STATUS_ERR_INVALID_ARGInterrupt source does not exist

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

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]configPointer 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_resource().

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]resourcePointer to a events_resource struct instance
Returns
Status of the channels busy state.
Return values
trueOne or more users connected to the channel has not handled the last event
falseAll users are ready to handle new events

References _events_find_bit_position(), and Assert.

Referenced by events_release().

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]resourcePointer to an events_resource struct
Returns
Status of the event detection interrupt flag.
Return values
trueEvent has been detected
falseEvent 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]resourcePointer to an events_resource struct instance
[in]sourceOne of the members in the events_interrupt_source enumerator
Returns
Status of the interrupt source.
Return values
trueInterrupt source is set
falseInterrupt source is not set

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

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]resourcePointer to an events_resource struct
Returns
Status of the event overrun interrupt flag.
Return values
trueEvent overrun has been detected
falseEvent 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]resourcePointer to an events_resource struct
Returns
The ready status of users connected to an event channel.
Return values
trueAll the users connected to the event channel are ready to handle incoming events
falseOne or more users connected to the event channel are not ready to handle incoming events

References _events_find_bit_position(), and Assert.

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]resourcePointer to an events_resource struct
Returns
Status of the channel release procedure.
Return values
STATUS_OKNo error was detected when the channel was released
STATUS_BUSYOne or more event users have not processed the last event
STATUS_ERR_NOT_INITIALIZEDChannel 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.

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]resourcePointer to an events_resource struct
Returns
Status of the event software procedure.
Return values
STATUS_OKNo error was detected when the software tigger signal was issued
STATUS_ERR_UNSUPPORTED_DEVIf 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().