This driver for Atmel® | SMART ARM®-based microcontrollers provides an interface for the configuration and management of external interrupts generated by the physical device pins, including edge detection.
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.
The External Interrupt (EXTINT) module provides a method of asynchronously detecting rising edge, falling edge, or specific level detection on individual I/O pins of a device. This detection can then be used to trigger a software interrupt or event, or polled for later use if required. External interrupts can also optionally be used to automatically wake up the device from sleep mode, allowing the device to conserve power while still being able to react to an external stimulus in a timely manner.
The External Interrupt module contains a number of logical channels, each of which is capable of being individually configured for a given pin routing, detection mode, and filtering/wake up characteristics.
Each individual logical external interrupt channel may be routed to a single physical device I/O pin in order to detect a particular edge or level of the incoming signal.
One or more Non Maskable Interrupt (NMI) channels are provided within each physical External Interrupt Controller module, allowing a single physical pin of the device to fire a single NMI interrupt in response to a particular edge or level stimulus. An NMI cannot, as the name suggests, be disabled in firmware and will take precedence over any in-progress interrupt sources.
NMIs can be used to implement critical device features such as forced software reset or other functionality where the action should be executed in preference to all other running code with a minimum amount of latency.
To reduce the possibility of noise or other transient signals causing unwanted device wake-ups, interrupts, and/or events via an external interrupt channel. A hardware signal filter can be enabled on individual channels. This filter provides a Majority-of-Three voter filter on the incoming signal, so that the input state is considered to be the majority vote of three subsequent samples of the pin input buffer. The possible sampled input and resulting filtered output when the filter is enabled is shown in the table below.
Input Sample 1 | Input Sample 2 | Input Sample 3 | Filtered Output |
---|---|---|---|
0 | 0 | 0 | 0 |
0 | 0 | 1 | 0 |
0 | 1 | 0 | 0 |
0 | 1 | 1 | 1 |
1 | 0 | 0 | 0 |
1 | 0 | 1 | 1 |
1 | 1 | 0 | 1 |
1 | 1 | 1 | 1 |
Channel detection states may be polled inside the application for synchronous detection, or events and interrupts may be used for asynchronous behavior. Each channel can be configured to give an asynchronous hardware event (which may in turn trigger actions in other hardware modules) or an asynchronous software interrupt.
The diagram below shows how this module is interconnected within the device.
Not all devices support disabling of the NMI channel(s) detection mode - see your device datasheet.
For extra information, see Extra Information for EXTINT Driver. This includes:
For a list of examples related to this driver, see Examples for EXTINT Driver.
Data Structures | |
struct | extint_chan_conf |
External Interrupt Controller channel configuration structure. More... | |
struct | extint_events |
External Interrupt event enable/disable structure. More... | |
struct | extint_nmi_conf |
External Interrupt Controller NMI configuration structure. More... | |
Macros | |
#define | EIC_NUMBER_OF_INTERRUPTS 16 |
#define | EXTINT_CLK_GCLK 0 |
The EIC is clocked by GCLK_EIC. More... | |
#define | EXTINT_CLK_ULP32K 1 |
The EIC is clocked by CLK_ULP32K. More... | |
Typedefs | |
typedef void(* | extint_callback_t )(void) |
Type definition for an EXTINT module callback function. More... | |
Enumerations | |
enum | extint_detect { EXTINT_DETECT_NONE = 0, EXTINT_DETECT_RISING = 1, EXTINT_DETECT_FALLING = 2, EXTINT_DETECT_BOTH = 3, EXTINT_DETECT_HIGH = 4, EXTINT_DETECT_LOW = 5 } |
External interrupt edge detection configuration enum. More... | |
enum | extint_pull { EXTINT_PULL_UP = SYSTEM_PINMUX_PIN_PULL_UP, EXTINT_PULL_DOWN = SYSTEM_PINMUX_PIN_PULL_DOWN, EXTINT_PULL_NONE = SYSTEM_PINMUX_PIN_PULL_NONE } |
External interrupt internal pull configuration enum. More... | |
Event Management | |
void | extint_enable_events (struct extint_events *const events) |
Enables an External Interrupt event output. More... | |
void | extint_disable_events (struct extint_events *const events) |
Disables an External Interrupt event output. More... | |
Configuration and Initialization (Channel) | |
void | extint_chan_get_config_defaults (struct extint_chan_conf *const config) |
Initializes an External Interrupt channel configuration structure to defaults. More... | |
void | extint_chan_set_config (const uint8_t channel, const struct extint_chan_conf *const config) |
Writes an External Interrupt channel configuration to the hardware module. More... | |
Configuration and Initialization (NMI) | |
static void | extint_nmi_get_config_defaults (struct extint_nmi_conf *const config) |
Initializes an External Interrupt NMI channel configuration structure to defaults. More... | |
enum status_code | extint_nmi_set_config (const uint8_t nmi_channel, const struct extint_nmi_conf *const config) |
Writes an External Interrupt NMI channel configuration to the hardware module. More... | |
Detection testing and clearing (channel) | |
static bool | extint_chan_is_detected (const uint8_t channel) |
Retrieves the edge detection state of a configured channel. More... | |
static void | extint_chan_clear_detected (const uint8_t channel) |
Clears the edge detection state of a configured channel. More... | |
Detection Testing and Clearing (NMI) | |
static bool | extint_nmi_is_detected (const uint8_t nmi_channel) |
Retrieves the edge detection state of a configured NMI channel. More... | |
static void | extint_nmi_clear_detected (const uint8_t nmi_channel) |
Clears the edge detection state of a configured NMI channel. More... | |
Callback Configuration and Initialization | |
enum | extint_callback_type { EXTINT_CALLBACK_TYPE_DETECT } |
Enum for the possible callback types for the EXTINT module. More... | |
enum status_code | extint_register_callback (const extint_callback_t callback, const uint8_t channel, const enum extint_callback_type type) |
Registers an asynchronous callback function with the driver. More... | |
enum status_code | extint_unregister_callback (const extint_callback_t callback, const uint8_t channel, const enum extint_callback_type type) |
Unregisters an asynchronous callback function with the driver. More... | |
uint8_t | extint_get_current_channel (void) |
Find what channel caused the callback. More... | |
Callback Enabling and Disabling (Channel) | |
enum status_code | extint_chan_enable_callback (const uint8_t channel, const enum extint_callback_type type) |
Enables asynchronous callback generation for a given channel and type. More... | |
enum status_code | extint_chan_disable_callback (const uint8_t channel, const enum extint_callback_type type) |
Disables asynchronous callback generation for a given channel and type. More... | |
#define EIC_NUMBER_OF_INTERRUPTS 16 |
Referenced by _system_extint_init(), and EIC_Handler().
#define EXTINT_CLK_GCLK 0 |
The EIC is clocked by GCLK_EIC.
Referenced by _system_extint_init(), and extint_nmi_set_config().
#define EXTINT_CLK_ULP32K 1 |
The EIC is clocked by CLK_ULP32K.
Referenced by _system_extint_init(), and extint_nmi_set_config().
typedef void(* extint_callback_t)(void) |
Type definition for an EXTINT module callback function.
enum extint_callback_type |
enum extint_detect |
External interrupt edge detection configuration enum.
Enum for the possible signal edge detection modes of the External Interrupt Controller module.
enum extint_pull |
External interrupt internal pull configuration enum.
Enum for the possible pin internal pull configurations.
|
inlinestatic |
Clears the edge detection state of a configured channel.
Clears the current state of a configured channel, readying it for the next level or edge detection.
[in] | channel | External Interrupt channel index to check |
Referenced by EIC_Handler().
enum status_code extint_chan_disable_callback | ( | const uint8_t | channel, |
const enum extint_callback_type | type | ||
) |
Disables asynchronous callback generation for a given channel and type.
Disables asynchronous callbacks for a given logical external interrupt channel and type.
[in] | channel | Logical channel to disable callback generation for |
[in] | type | Type of callback function callbacks to disable |
STATUS_OK | The callback was disabled successfully |
STATUS_ERR_INVALID_ARG | If an invalid callback type was supplied |
References Assert, EXTINT_CALLBACK_TYPE_DETECT, STATUS_ERR_INVALID_ARG, and STATUS_OK.
enum status_code extint_chan_enable_callback | ( | const uint8_t | channel, |
const enum extint_callback_type | type | ||
) |
Enables asynchronous callback generation for a given channel and type.
Enables asynchronous callbacks for a given logical external interrupt channel and type. This must be called before an external interrupt channel will generate callback events.
[in] | channel | Logical channel to enable callback generation for |
[in] | type | Type of callback function callbacks to enable |
STATUS_OK | The callback was enabled successfully |
STATUS_ERR_INVALID_ARG | If an invalid callback type was supplied |
References Assert, EXTINT_CALLBACK_TYPE_DETECT, STATUS_ERR_INVALID_ARG, and STATUS_OK.
Referenced by configure_eic_callback().
void extint_chan_get_config_defaults | ( | struct extint_chan_conf *const | config | ) |
Initializes an External Interrupt channel configuration structure to defaults.
Initializes a given External Interrupt channel configuration structure to a set of 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, extint_chan_conf::detection_criteria, EXTINT_DETECT_FALLING, EXTINT_PULL_UP, extint_chan_conf::filter_input_signal, extint_chan_conf::gpio_pin, extint_chan_conf::gpio_pin_mux, and extint_chan_conf::gpio_pin_pull.
Referenced by configure_extint().
|
inlinestatic |
Retrieves the edge detection state of a configured channel.
Reads the current state of a configured channel, and determines if the detection criteria of the channel has been met.
[in] | channel | External Interrupt channel index to check |
true | If the channel's edge/level detection criteria was met |
false | If the channel has not detected its configured criteria |
Referenced by EIC_Handler().
void extint_chan_set_config | ( | const uint8_t | channel, |
const struct extint_chan_conf *const | config | ||
) |
Writes an External Interrupt channel configuration to the hardware module.
Writes out a given configuration of an External Interrupt channel configuration to the hardware module. If the channel is already configured, the new configuration will replace the existing one.
[in] | channel | External Interrupt channel to configure |
[in] | config | Configuration settings for the channel |
References _extint_disable(), _extint_enable(), _extint_is_gclk_required, Assert, extint_chan_conf::detection_criteria, system_pinmux_config::direction, EXTINT_CLOCK_SOURCE, extint_chan_conf::filter_input_signal, extint_chan_conf::gpio_pin, extint_chan_conf::gpio_pin_mux, extint_chan_conf::gpio_pin_pull, system_pinmux_config::input_pull, system_pinmux_config::mux_position, system_gclk_gen_is_enabled(), system_pinmux_get_config_defaults(), SYSTEM_PINMUX_PIN_DIR_INPUT, and system_pinmux_pin_set_config().
Referenced by configure_extint().
void extint_disable_events | ( | struct extint_events *const | events | ) |
Disables an External Interrupt event output.
Disables one or more output events from the External Interrupt module. See here for a list of events this module supports.
[in] | events | Struct containing flags of events to disable |
References _extint_disable(), _extint_enable(), Assert, and extint_events::generate_event_on_detect.
void extint_enable_events | ( | struct extint_events *const | events | ) |
Enables an External Interrupt event output.
Enables one or more output events from the External Interrupt module. See here for a list of events this module supports.
[in] | events | Struct containing flags of events to enable |
References _extint_disable(), _extint_enable(), Assert, and extint_events::generate_event_on_detect.
uint8_t extint_get_current_channel | ( | void | ) |
Find what channel caused the callback.
Can be used in an EXTINT callback function to find what channel caused the callback in case the same callback is used by multiple channels.
References _current_channel.
|
inlinestatic |
Clears the edge detection state of a configured NMI channel.
Clears the current state of a configured NMI channel, readying it for the next level or edge detection.
[in] | nmi_channel | External Interrupt NMI channel index to check |
|
inlinestatic |
Initializes an External Interrupt NMI channel configuration structure to defaults.
Initializes a given External Interrupt NMI channel configuration structure to a set of 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, extint_nmi_conf::detection_criteria, EXTINT_DETECT_FALLING, EXTINT_PULL_UP, extint_nmi_conf::filter_input_signal, extint_nmi_conf::gpio_pin, extint_nmi_conf::gpio_pin_mux, and extint_nmi_conf::gpio_pin_pull.
|
inlinestatic |
Retrieves the edge detection state of a configured NMI channel.
Reads the current state of a configured NMI channel, and determines if the detection criteria of the NMI channel has been met.
[in] | nmi_channel | External Interrupt NMI channel index to check |
true | If the NMI channel's edge/level detection criteria was met |
false | If the NMI channel has not detected its configured criteria |
enum status_code extint_nmi_set_config | ( | const uint8_t | nmi_channel, |
const struct extint_nmi_conf *const | config | ||
) |
Writes an External Interrupt NMI channel configuration to the hardware module.
Writes out a given configuration of an External Interrupt NMI channel configuration to the hardware module. If the channel is already configured, the new configuration will replace the existing one.
[in] | nmi_channel | External Interrupt NMI channel to configure |
[in] | config | Configuration settings for the channel |
STATUS_OK | Configuration succeeded |
STATUS_ERR_PIN_MUX_INVALID | An invalid pin mux value was supplied |
STATUS_ERR_BAD_FORMAT | An invalid detection mode was requested |
References _extint_disable(), _extint_enable(), _extint_is_gclk_required, Assert, extint_nmi_conf::detection_criteria, system_pinmux_config::direction, EXTINT_CLK_GCLK, EXTINT_CLK_ULP32K, EXTINT_CLOCK_SOURCE, extint_nmi_conf::filter_input_signal, extint_nmi_conf::gpio_pin, extint_nmi_conf::gpio_pin_mux, extint_nmi_conf::gpio_pin_pull, system_pinmux_config::input_pull, system_pinmux_config::mux_position, STATUS_OK, system_gclk_chan_disable(), system_gclk_chan_enable(), system_gclk_gen_is_enabled(), system_pinmux_get_config_defaults(), SYSTEM_PINMUX_PIN_DIR_INPUT, SYSTEM_PINMUX_PIN_PULL_UP, and system_pinmux_pin_set_config().
enum status_code extint_register_callback | ( | const extint_callback_t | callback, |
const uint8_t | channel, | ||
const enum extint_callback_type | type | ||
) |
Registers an asynchronous callback function with the driver.
Registers an asynchronous callback with the EXTINT driver, fired when a channel detects the configured channel detection criteria (e.g. edge or level). Callbacks are fired once for each detected channel.
[in] | callback | Pointer to the callback function to register |
[in] | channel | Logical channel to register callback for |
[in] | type | Type of callback function to register |
STATUS_OK | The callback was registered successfully |
STATUS_ERR_INVALID_ARG | If an invalid callback type was supplied |
STATUS_ERR_ALREADY_INITIALIZED | Callback function has been registered, need unregister first |
References _extint_dev, Assert, EXTINT_CALLBACK_TYPE_DETECT, STATUS_ERR_ALREADY_INITIALIZED, STATUS_ERR_INVALID_ARG, and STATUS_OK.
Referenced by configure_eic_callback().
enum status_code extint_unregister_callback | ( | const extint_callback_t | callback, |
const uint8_t | channel, | ||
const enum extint_callback_type | type | ||
) |
Unregisters an asynchronous callback function with the driver.
Unregisters an asynchronous callback with the EXTINT driver, removing it from the internal callback registration table.
[in] | callback | Pointer to the callback function to unregister |
[in] | channel | Logical channel to unregister callback for |
[in] | type | Type of callback function to unregister |
STATUS_OK | The callback was unregistered successfully |
STATUS_ERR_INVALID_ARG | If an invalid callback type was supplied |
STATUS_ERR_BAD_ADDRESS | No matching entry was found in the registration table |
References _extint_dev, Assert, EXTINT_CALLBACK_TYPE_DETECT, STATUS_ERR_BAD_ADDRESS, STATUS_ERR_INVALID_ARG, and STATUS_OK.