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:

Polled APIs
Callback APIs

The following peripheral is used by this module:

EIC (External Interrupt Controller)

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 R34/R35

The outline of this documentation is as follows:

Prerequisites

There are no prerequisites for this module.

Module Overview

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.

Logical Channels

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.

NMI Channels

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.

Input Filtering and Detection

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.

Sampled Input and Resulting Filtered Output
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

Events and Interrupts

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.

Note: The connection of events between modules requires the use of the SAM Event System Driver (EVENTS) to route output event of one module to the input event of another. For more information on event routing, refer to the event driver documentation.

Physical Connection

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

Special Considerations

Not all devices support disabling of the NMI channel(s) detection mode - see your device datasheet.

Extra Information

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

Examples

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

API Overview

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.

#define EXTINT_CLK_ULP32K 1

The EIC is clocked by CLK_ULP32K.

typedef void(* extint_callback_t)(void)

Type definition for an EXTINT module callback function.

enum extint_callback_type

Enum for the possible callback types for the EXTINT module.

Enumerator

EXTINT_CALLBACK_TYPE_DETECT

Callback type for when an external interrupt detects the configured channel criteria (i.e.

edge or level detection)

enum extint_detect

External interrupt edge detection configuration enum.

Enum for the possible signal edge detection modes of the External Interrupt Controller module.

Enumerator
EXTINT_DETECT_NONE	No edge detection. Not allowed as a NMI detection mode on some devices.
EXTINT_DETECT_RISING	Detect rising signal edges.
EXTINT_DETECT_FALLING	Detect falling signal edges.
EXTINT_DETECT_BOTH	Detect both signal edges.
EXTINT_DETECT_HIGH	Detect high signal levels.
EXTINT_DETECT_LOW	Detect low signal levels.

enum extint_pull

External interrupt internal pull configuration enum.

Enum for the possible pin internal pull configurations.

Note: Disabling the internal pull resistor is not recommended if the driver is used in interrupt (callback) mode, due the possibility of floating inputs generating continuous interrupts.

Enumerator
EXTINT_PULL_UP	Internal pull-up resistor is enabled on the pin.
EXTINT_PULL_DOWN	Internal pull-down resistor is enabled on the pin.
EXTINT_PULL_NONE	Internal pull resistor is disconnected from the pin.

static void extint_chan_clear_detected ( const uint8_t channel )

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.

Parameters

[in] channel External Interrupt channel index to check

Referenced by EIC_Handler(), and ui_enable_asynchronous_interrupt().

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.

Parameters

[in]	channel	Logical channel to disable callback generation for
[in]	type	Type of callback function callbacks to disable

Returns: Status of the callback disable operation.

Return values

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.

Referenced by uhd_disable(), ui_disable_asynchronous_interrupt(), and usb_dual_disable().

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.

Parameters

[in]	channel	Logical channel to enable callback generation for
[in]	type	Type of callback function callbacks to enable

Returns: Status of the callback enable operation.

Return values

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 ui_enable_asynchronous_interrupt().

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:

Wake the device if an edge detection occurs whilst in sleep
Input filtering disabled
Internal pull-up enabled
Detect falling edges of a signal

Parameters

[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, extint_chan_conf::gpio_pin_pull, and extint_chan_conf::wake_if_sleeping.

Referenced by ui_enable_asynchronous_interrupt().

static bool extint_chan_is_detected ( const uint8_t channel )

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.

Parameters

[in] channel External Interrupt channel index to check

Returns: Status of the requested channel's edge detection state.

Return values

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.

Parameters

[in]	channel	External Interrupt channel to configure
[in]	config	Configuration settings for the channel

References _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, system_pinmux_pin_set_config(), and extint_chan_conf::wake_if_sleeping.

Referenced by ui_enable_asynchronous_interrupt().

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.

Note: Events cannot be altered while the module is enabled.

Parameters

[in] events Struct containing flags of events to disable

References 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.

Note: Events cannot be altered while the module is enabled.

Parameters

[in] events Struct containing flags of events to enable

References 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.

Returns: Channel number.

References _current_channel.

static void extint_nmi_clear_detected ( const uint8_t nmi_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.

Parameters

[in] nmi_channel External Interrupt NMI channel index to check

static void extint_nmi_get_config_defaults ( struct extint_nmi_conf *const config )

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:

Input filtering disabled
Detect falling edges of a signal
Asynchronous edge detection is disabled

Parameters

[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.

static bool extint_nmi_is_detected ( const uint8_t nmi_channel )

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.

Parameters

[in] nmi_channel External Interrupt NMI channel index to check

Returns: Status of the requested NMI channel's edge detection state.

Return values

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.

Parameters

[in]	nmi_channel	External Interrupt NMI channel to configure
[in]	config	Configuration settings for the channel

Returns: Status code indicating the success or failure of the request.

Return values

STATUS_OK	Configuration succeeded
STATUS_ERR_PIN_MUX_INVALID	An invalid pinmux 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_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.

Note: NMI channel callbacks cannot be registered via this function; the device's NMI interrupt should be hooked directly in the user application and the NMI flags manually cleared via extint_nmi_clear_detected().

Parameters

[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

Returns: Status of the registration operation.

Return values

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 ui_enable_asynchronous_interrupt().

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.

Parameters

[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

Returns: Status of the de-registration operation.

Return values

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.

Microchip® Advanced Software Framework

Prerequisites

Module Overview

Logical Channels

NMI Channels

Input Filtering and Detection

Events and Interrupts

Physical Connection

Special Considerations

Extra Information

Examples

API Overview

Data Structures

Macros

Typedefs

Enumerations

Event Management

Configuration and Initialization (Channel)

Configuration and Initialization (NMI)

Detection testing and clearing (channel)

Detection Testing and Clearing (NMI)

Callback Configuration and Initialization

Callback Enabling and Disabling (Channel)