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:
There are no prerequisites for this module.
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.
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 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.
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.
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 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.
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.
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.
The diagram below shows how this module is interconnected within the device.
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.
There are no special considerations for this module.
For extra information, see Extra Information for EVENTS Driver. This includes:
For a list of examples related to this driver, see Examples for 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 |
| 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.
| [in] | resource | Pointer to an events_resource struct instance |
| [in] | source | One of the members in the events_interrupt_source enumerator |
| 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.
| 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.
| [in] | resource | Pointer to an events_resource struct instance |
| [in] | hook | Pointer to an events_hook struct instance |
| STATUS_OK | Insertion 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.
| [out] | resource | Pointer to a events_resource struct instance |
| [in] | config | Pointer to a events_config struct |
| 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 event_setup().
| 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.
| [in] | resource | Pointer to an events_resource struct instance |
| [in] | user_id | A number identifying the user peripheral found in the device header file |
| STATUS_OK | No errors detected when attaching the event user |
References Assert, and STATUS_OK.
Referenced by event_setup().
| 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.
| [out] | hook | Pointer to an events_hook struct instance |
| [in] | hook_func | Pointer to a function containing the interrupt hook code |
| STATUS_OK | Creation 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.
| [in] | resource | Pointer to an events_resource struct instance |
| [in] | hook | Pointer to an events_hook struct instance |
| 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, 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.
| [in] | resource | Pointer to an event_resource struct instance |
| [in] | user_id | A number identifying the user peripheral found in the device header file |
| STATUS_OK | No errors detected when detaching the event user |
| 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.
| [in] | resource | Pointer to an events_resource struct instance |
| [in] | source | One of the members in the events_interrupt_source enumerator |
| 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.
| [in] | resource | Pointer to an events_resource struct instance |
| [in] | source | One of the members in the events_interrupt_source enumerator |
| 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.
| 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.
| [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 event_setup().
| 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.
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.
| [in] | resource | Pointer to a events_resource struct instance |
| 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().
| 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.
| [in] | resource | Pointer to an events_resource struct |
| 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.
| [in] | resource | Pointer to an events_resource struct instance |
| [in] | source | One of the members in the events_interrupt_source enumerator |
| 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.
| bool events_is_overrun | ( | struct events_resource * | resource | ) |
Check if there has been an overrun situation on this channel.
| [in] | resource | Pointer to an events_resource struct |
| 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.
| [in] | resource | Pointer to an events_resource struct |
| 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.
| 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.
| [in] | resource | Pointer to an events_resource struct |
| 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.
| enum status_code events_trigger | ( | struct events_resource * | resource | ) |
Trigger software event.
Trigger an event by software.
| [in] | resource | Pointer to an events_resource struct |
| 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().
1.8.5