Microchip® Advanced Software Framework

 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
SAM External Interrupt (EXTINT) Driver

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:

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 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)

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.

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]channelExternal 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.

Parameters
[in]channelLogical channel to disable callback generation for
[in]typeType of callback function callbacks to disable
Returns
Status of the callback disable operation.
Return values
STATUS_OKThe callback was disabled successfully
STATUS_ERR_INVALID_ARGIf an invalid callback type was supplied

References Assert, EXTINT_CALLBACK_TYPE_DETECT, STATUS_ERR_INVALID_ARG, and STATUS_OK.

Referenced by _uhd_vbus_handler(), _usb_vbus_config(), ui_wakeup_disable(), usb_dual_disable(), usb_id_config(), and usb_id_handler().

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]channelLogical channel to enable callback generation for
[in]typeType of callback function callbacks to enable
Returns
Status of the callback enable operation.
Return values
STATUS_OKThe callback was enabled successfully
STATUS_ERR_INVALID_ARGIf an invalid callback type was supplied

References Assert, EXTINT_CALLBACK_TYPE_DETECT, STATUS_ERR_INVALID_ARG, and STATUS_OK.

Referenced by _uhd_vbus_handler(), _usb_vbus_config(), ui_init(), ui_wakeup_enable(), usb_id_config(), and usb_id_handler().

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]configConfiguration 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 _usb_vbus_config(), ui_init(), and usb_id_config().

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]channelExternal Interrupt channel index to check
Returns
Status of the requested channel's edge detection state.
Return values
trueIf the channel's edge/level detection criteria was met
falseIf 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]channelExternal Interrupt channel to configure
[in]configConfiguration 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 _usb_vbus_config(), ui_init(), and usb_id_config().

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]eventsStruct 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]eventsStruct 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_channelExternal 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]configConfiguration 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_channelExternal Interrupt NMI channel index to check
Returns
Status of the requested NMI channel's edge detection state.
Return values
trueIf the NMI channel's edge/level detection criteria was met
falseIf 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_channelExternal Interrupt NMI channel to configure
[in]configConfiguration settings for the channel
Returns
Status code indicating the success or failure of the request.
Return values
STATUS_OKConfiguration succeeded
STATUS_ERR_PIN_MUX_INVALIDAn invalid pinmux value was supplied
STATUS_ERR_BAD_FORMATAn 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]callbackPointer to the callback function to register
[in]channelLogical channel to register callback for
[in]typeType of callback function to register
Returns
Status of the registration operation.
Return values
STATUS_OKThe callback was registered successfully
STATUS_ERR_INVALID_ARGIf an invalid callback type was supplied
STATUS_ERR_ALREADY_INITIALIZEDCallback 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 _usb_vbus_config(), ui_init(), and usb_id_config().

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]callbackPointer to the callback function to unregister
[in]channelLogical channel to unregister callback for
[in]typeType of callback function to unregister
Returns
Status of the de-registration operation.
Return values
STATUS_OKThe callback was unregistered successfully
STATUS_ERR_INVALID_ARGIf an invalid callback type was supplied
STATUS_ERR_BAD_ADDRESSNo 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.