SMART ARM-based Microcontrollers
AT03246: SAM D/R/L/C External Interrupt (EXTINT)
Driver
APPLICATION NOTE
Introduction
®
®
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
The outline of this documentation is as follows:
•
Prerequisites
•
Module Overview
•
Special Considerations
•
Extra Information
•
Examples
•
API Overview
Atmel-42112E-SAM-External-Interrupt-Driver-Extint_AT03246_Application Note-12/2015
Table of Contents
Introduction......................................................................................................................1
1. Software License....................................................................................................... 4
2. Prerequisites..............................................................................................................5
3. Module Overview....................................................................................................... 6
3.1.
3.2.
3.3.
3.4.
3.5.
Logical Channels..........................................................................................................................6
NMI Channels...............................................................................................................................6
Input Filtering and Detection.........................................................................................................6
Events and Interrupts................................................................................................................... 7
Physical Connection.....................................................................................................................7
4. Special Considerations.............................................................................................. 8
5. Extra Information....................................................................................................... 9
6. Examples................................................................................................................. 10
7. API Overview........................................................................................................... 11
7.1.
7.2.
7.3.
7.4.
7.5.
Variable and Type Definitions..................................................................................................... 11
7.1.1.
Type extint_callback_t..................................................................................................11
Structure Definitions................................................................................................................... 11
7.2.1.
Struct extint_chan_conf................................................................................................11
7.2.2.
Struct extint_events......................................................................................................11
7.2.3.
Struct extint_nmi_conf..................................................................................................11
Macro Definitions........................................................................................................................12
7.3.1.
Macro EIC_NUMBER_OF_INTERRUPTS.................................................................. 12
7.3.2.
Macro EXTINT_CLK_GCLK........................................................................................ 12
7.3.3.
Macro EXTINT_CLK_ULP32K.....................................................................................12
Function Definitions....................................................................................................................12
7.4.1.
Event Management......................................................................................................12
7.4.2.
Configuration and Initialization (Channel)....................................................................13
7.4.3.
Configuration and Initialization (NMI)...........................................................................14
7.4.4.
Detection testing and clearing (channel)..................................................................... 15
7.4.5.
Detection Testing and Clearing (NMI)..........................................................................16
7.4.6.
Callback Configuration and Initialization......................................................................16
7.4.7.
Callback Enabling and Disabling (Channel)................................................................ 18
Enumeration Definitions............................................................................................................. 19
7.5.1.
Callback Configuration and Initialization......................................................................19
7.5.2.
Enum extint_detect...................................................................................................... 19
7.5.3.
Enum extint_pull.......................................................................................................... 20
8. Extra Information for EXTINT Driver........................................................................21
8.1.
8.2.
Acronyms....................................................................................................................................21
Dependencies.............................................................................................................................21
Atmel AT03246: SAM D/R/L/C External Interrupt (EXTINT) Driver [APPLICATION NOTE]
Atmel-42112E-SAM-External-Interrupt-Driver-Extint_AT03246_Application Note-12/2015
2
8.3.
Errata..........................................................................................................................................21
8.4.
Module History............................................................................................................................21
9. Examples for EXTINT Driver................................................................................... 22
9.1.
9.2.
Quick Start Guide for EXTINT - Basic........................................................................................ 22
9.1.1.
Setup........................................................................................................................... 22
9.1.2.
Use Case..................................................................................................................... 23
Quick Start Guide for EXTINT - Callback................................................................................... 24
9.2.1.
Setup........................................................................................................................... 24
9.2.2.
Use Case..................................................................................................................... 26
10. Document Revision History..................................................................................... 27
Atmel AT03246: SAM D/R/L/C External Interrupt (EXTINT) Driver [APPLICATION NOTE]
Atmel-42112E-SAM-External-Interrupt-Driver-Extint_AT03246_Application Note-12/2015
3
1.
Software License
Redistribution and use in source and binary forms, with or without modification, are permitted provided
that the following conditions are met:
1. Redistributions of source code must retain the above copyright notice, this list of conditions and the
following disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the
following disclaimer in the documentation and/or other materials provided with the distribution.
3. The name of Atmel may not be used to endorse or promote products derived from this software without
specific prior written permission.
4. This software may only be redistributed and used in connection with an Atmel microcontroller product.
THIS SOFTWARE IS PROVIDED BY ATMEL "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS
FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT ARE EXPRESSLY AND SPECIFICALLY
DISCLAIMED. IN NO EVENT SHALL ATMEL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER
IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.
Atmel AT03246: SAM D/R/L/C External Interrupt (EXTINT) Driver [APPLICATION NOTE]
Atmel-42112E-SAM-External-Interrupt-Driver-Extint_AT03246_Application Note-12/2015
4
2.
Prerequisites
There are no prerequisites for this module.
Atmel AT03246: SAM D/R/L/C External Interrupt (EXTINT) Driver [APPLICATION NOTE]
Atmel-42112E-SAM-External-Interrupt-Driver-Extint_AT03246_Application Note-12/2015
5
3.
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.
3.1.
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.
3.2.
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.
3.3.
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 Table 3-1 Sampled Input
and Resulting Filtered Output on page 6.
Table 3-1. 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
Atmel AT03246: SAM D/R/L/C External Interrupt (EXTINT) Driver [APPLICATION NOTE]
Atmel-42112E-SAM-External-Interrupt-Driver-Extint_AT03246_Application Note-12/2015
6
3.4.
Input Sample 1
Input Sample 2
Input Sample 3
Filtered Output
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.
3.5.
Physical Connection
Figure 3-1 Physical Connection on page 7 shows how this module is interconnected within the device.
Figure 3-1. Physical Connection
Port Pad
Peripheral MUX
EIC Module
Other Peripheral Modules
Atmel AT03246: SAM D/R/L/C External Interrupt (EXTINT) Driver [APPLICATION NOTE]
Atmel-42112E-SAM-External-Interrupt-Driver-Extint_AT03246_Application Note-12/2015
7
4.
Special Considerations
Not all devices support disabling of the NMI channel(s) detection mode - see your device datasheet.
Atmel AT03246: SAM D/R/L/C External Interrupt (EXTINT) Driver [APPLICATION NOTE]
Atmel-42112E-SAM-External-Interrupt-Driver-Extint_AT03246_Application Note-12/2015
8
5.
Extra Information
For extra information, see Extra Information for EXTINT Driver. This includes:
•
Acronyms
•
Dependencies
•
Errata
•
Module History
Atmel AT03246: SAM D/R/L/C External Interrupt (EXTINT) Driver [APPLICATION NOTE]
Atmel-42112E-SAM-External-Interrupt-Driver-Extint_AT03246_Application Note-12/2015
9
6.
Examples
For a list of examples related to this driver, see Examples for EXTINT Driver.
Atmel AT03246: SAM D/R/L/C External Interrupt (EXTINT) Driver [APPLICATION NOTE]
Atmel-42112E-SAM-External-Interrupt-Driver-Extint_AT03246_Application Note-12/2015
10
7.
API Overview
7.1.
Variable and Type Definitions
7.1.1.
Type extint_callback_t
typedef void(* extint_callback_t )(void)
Type definition for an EXTINT module callback function
7.2.
Structure Definitions
7.2.1.
Struct extint_chan_conf
Configuration structure for the edge detection mode of an external interrupt channel.
Table 7-1. Members
Type
Name
Description
enum extint_detect detection_criteria Edge detection mode to use
7.2.2.
bool
filter_input_signal Filter the raw input signal to prevent noise from triggering an
interrupt accidentally, using a three sample majority filter
uint32_t
gpio_pin
GPIO pin the NMI should be connected to
uint32_t
gpio_pin_mux
MUX position the GPIO pin should be configured to
enum extint_pull
gpio_pin_pull
Internal pull to enable on the input pin
bool
wake_if_sleeping Wake up the device if the channel interrupt fires during sleep
mode
Struct extint_events
Event flags for the extint_enable_events() and extint_disable_events().
Table 7-2. Members
Type Name
bool
7.2.3.
Description
generate_event_on_detect[] If true, an event will be generated when an external interrupt
channel detection state changes
Struct extint_nmi_conf
Configuration structure for the edge detection mode of an external interrupt NMI channel.
Atmel AT03246: SAM D/R/L/C External Interrupt (EXTINT) Driver [APPLICATION NOTE]
Atmel-42112E-SAM-External-Interrupt-Driver-Extint_AT03246_Application Note-12/2015
11
Table 7-3. Members
Type
Name
Description
enum extint_detect detection_criteria Edge detection mode to use. Not all devices support all possible
detection modes for NMIs.
bool
filter_input_signal Filter the raw input signal to prevent noise from triggering an
interrupt accidentally, using a three sample majority filter
uint32_t
gpio_pin
GPIO pin the NMI should be connected to
uint32_t
gpio_pin_mux
MUX position the GPIO pin should be configured to
enum extint_pull
gpio_pin_pull
Internal pull to enable on the input pin
7.3.
Macro Definitions
7.3.1.
Macro EIC_NUMBER_OF_INTERRUPTS
#define EIC_NUMBER_OF_INTERRUPTS
7.3.2.
Macro EXTINT_CLK_GCLK
#define EXTINT_CLK_GCLK
The EIC is clocked by GCLK_EIC.
7.3.3.
Macro EXTINT_CLK_ULP32K
#define EXTINT_CLK_ULP32K
The EIC is clocked by CLK_ULP32K.
7.4.
Function Definitions
7.4.1.
Event Management
7.4.1.1.
Function extint_enable_events()
Enables an External Interrupt event output.
void extint_enable_events(
struct extint_events *const events)
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.
Atmel AT03246: SAM D/R/L/C External Interrupt (EXTINT) Driver [APPLICATION NOTE]
Atmel-42112E-SAM-External-Interrupt-Driver-Extint_AT03246_Application Note-12/2015
12
Table 7-4. Parameters
7.4.1.2.
Data direction
Parameter name
Description
[in]
events
Struct containing flags of events to enable
Function extint_disable_events()
Disables an External Interrupt event output.
void extint_disable_events(
struct extint_events *const events)
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.
Table 7-5. Parameters
Data direction
Parameter name
Description
[in]
events
Struct containing flags of events to disable
7.4.2.
Configuration and Initialization (Channel)
7.4.2.1.
Function extint_chan_get_config_defaults()
Initializes an External Interrupt channel configuration structure to defaults.
void extint_chan_get_config_defaults(
struct extint_chan_conf *const config)
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
Table 7-6. Parameters
7.4.2.2.
Data direction
Parameter name
Description
[out]
config
Configuration structure to initialize to default values
Function extint_chan_set_config()
Writes an External Interrupt channel configuration to the hardware module.
void extint_chan_set_config(
const uint8_t channel,
const struct extint_chan_conf *const config)
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.
Atmel AT03246: SAM D/R/L/C External Interrupt (EXTINT) Driver [APPLICATION NOTE]
Atmel-42112E-SAM-External-Interrupt-Driver-Extint_AT03246_Application Note-12/2015
13
Table 7-7. Parameters
Data direction
Parameter name
Description
[in]
channel
External Interrupt channel to configure
[in]
config
Configuration settings for the channel
7.4.3.
Configuration and Initialization (NMI)
7.4.3.1.
Function extint_nmi_get_config_defaults()
Initializes an External Interrupt NMI channel configuration structure to defaults.
void extint_nmi_get_config_defaults(
struct extint_nmi_conf *const config)
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
Table 7-8. Parameters
7.4.3.2.
Data direction
Parameter name
Description
[out]
config
Configuration structure to initialize to default values
Function extint_nmi_set_config()
Writes an External Interrupt NMI channel configuration to the hardware module.
enum status_code extint_nmi_set_config(
const uint8_t nmi_channel,
const struct extint_nmi_conf *const config)
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.
Table 7-9. Parameters
Data direction
Parameter name
Description
[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.
Atmel AT03246: SAM D/R/L/C External Interrupt (EXTINT) Driver [APPLICATION NOTE]
Atmel-42112E-SAM-External-Interrupt-Driver-Extint_AT03246_Application Note-12/2015
14
Table 7-10. Return Values
Return value
Description
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
7.4.4.
Detection testing and clearing (channel)
7.4.4.1.
Function extint_chan_is_detected()
Retrieves the edge detection state of a configured channel.
bool extint_chan_is_detected(
const uint8_t channel)
Reads the current state of a configured channel, and determines if the detection criteria of the channel
has been met.
Table 7-11. Parameters
Data direction
Parameter name
Description
[in]
channel
External Interrupt channel index to check
Returns
Status of the requested channel's edge detection state.
Table 7-12. Return Values
7.4.4.2.
Return value
Description
true
If the channel's edge/level detection criteria was met
false
If the channel has not detected its configured criteria
Function extint_chan_clear_detected()
Clears the edge detection state of a configured channel.
void extint_chan_clear_detected(
const uint8_t channel)
Clears the current state of a configured channel, readying it for the next level or edge detection.
Table 7-13. Parameters
Data direction
Parameter name
Description
[in]
channel
External Interrupt channel index to check
Atmel AT03246: SAM D/R/L/C External Interrupt (EXTINT) Driver [APPLICATION NOTE]
Atmel-42112E-SAM-External-Interrupt-Driver-Extint_AT03246_Application Note-12/2015
15
7.4.5.
Detection Testing and Clearing (NMI)
7.4.5.1.
Function extint_nmi_is_detected()
Retrieves the edge detection state of a configured NMI channel.
bool extint_nmi_is_detected(
const uint8_t nmi_channel)
Reads the current state of a configured NMI channel, and determines if the detection criteria of the NMI
channel has been met.
Table 7-14. Parameters
Data direction
Parameter name
Description
[in]
nmi_channel
External Interrupt NMI channel index to check
Returns
Status of the requested NMI channel's edge detection state.
Table 7-15. Return Values
7.4.5.2.
Return value
Description
true
If the NMI channel's edge/level detection criteria was met
false
If the NMI channel has not detected its configured criteria
Function extint_nmi_clear_detected()
Clears the edge detection state of a configured NMI channel.
void extint_nmi_clear_detected(
const uint8_t nmi_channel)
Clears the current state of a configured NMI channel, readying it for the next level or edge detection.
Table 7-16. Parameters
Data direction
Parameter name
Description
[in]
nmi_channel
External Interrupt NMI channel index to check
7.4.6.
Callback Configuration and Initialization
7.4.6.1.
Function extint_register_callback()
Registers an asynchronous callback function with the driver.
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 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.
Atmel AT03246: SAM D/R/L/C External Interrupt (EXTINT) Driver [APPLICATION NOTE]
Atmel-42112E-SAM-External-Interrupt-Driver-Extint_AT03246_Application Note-12/2015
16
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().
Table 7-17. Parameters
Data direction
Parameter name
Description
[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.
Table 7-18. Return Values
7.4.6.2.
Return value
Description
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
Function extint_unregister_callback()
Unregisters an asynchronous callback function with the driver.
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 with the EXTINT driver, removing it from the internal callback
registration table.
Table 7-19. Parameters
Data direction
Parameter name
Description
[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.
Atmel AT03246: SAM D/R/L/C External Interrupt (EXTINT) Driver [APPLICATION NOTE]
Atmel-42112E-SAM-External-Interrupt-Driver-Extint_AT03246_Application Note-12/2015
17
Table 7-20. Return Values
7.4.6.3.
Return value
Description
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
Function extint_get_current_channel()
Find what channel caused the callback.
uint8_t extint_get_current_channel( void )
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.
7.4.7.
Callback Enabling and Disabling (Channel)
7.4.7.1.
Function extint_chan_enable_callback()
Enables asynchronous callback generation for a given channel and type.
enum status_code extint_chan_enable_callback(
const uint8_t channel,
const enum extint_callback_type 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.
Table 7-21. Parameters
Data direction
Parameter name
Description
[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.
Table 7-22. Return Values
Return value
Description
STATUS_OK
The callback was enabled successfully
STATUS_ERR_INVALID_ARG
If an invalid callback type was supplied
Atmel AT03246: SAM D/R/L/C External Interrupt (EXTINT) Driver [APPLICATION NOTE]
Atmel-42112E-SAM-External-Interrupt-Driver-Extint_AT03246_Application Note-12/2015
18
7.4.7.2.
Function extint_chan_disable_callback()
Disables asynchronous callback generation for a given channel and type.
enum status_code extint_chan_disable_callback(
const uint8_t channel,
const enum extint_callback_type type)
Disables asynchronous callbacks for a given logical external interrupt channel and type.
Table 7-23. Parameters
Data direction
Parameter name
Description
[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.
Table 7-24. Return Values
Return value
Description
STATUS_OK
The callback was disabled successfully
STATUS_ERR_INVALID_ARG
If an invalid callback type was supplied
7.5.
Enumeration Definitions
7.5.1.
Callback Configuration and Initialization
7.5.1.1.
Enum extint_callback_type
Enum for the possible callback types for the EXTINT module.
Table 7-25. Members
Enum value
Description
EXTINT_CALLBACK_TYPE_DETECT Callback type for when an external interrupt detects the
configured channel criteria (i.e. edge or level detection)
7.5.2.
Enum extint_detect
Enum for the possible signal edge detection modes of the External Interrupt Controller module.
Table 7-26. Members
Enum value
Description
EXTINT_DETECT_NONE
No edge detection. Not allowed as a NMI detection mode on some
devices.
EXTINT_DETECT_RISING
Detect rising signal edges
Atmel AT03246: SAM D/R/L/C External Interrupt (EXTINT) Driver [APPLICATION NOTE]
Atmel-42112E-SAM-External-Interrupt-Driver-Extint_AT03246_Application Note-12/2015
19
Enum value
Description
EXTINT_DETECT_FALLING Detect falling signal edges
7.5.3.
EXTINT_DETECT_BOTH
Detect both signal edges
EXTINT_DETECT_HIGH
Detect high signal levels
EXTINT_DETECT_LOW
Detect low signal levels
Enum extint_pull
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.
Table 7-27. Members
Enum value
Description
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
Atmel AT03246: SAM D/R/L/C External Interrupt (EXTINT) Driver [APPLICATION NOTE]
Atmel-42112E-SAM-External-Interrupt-Driver-Extint_AT03246_Application Note-12/2015
20
8.
Extra Information for EXTINT Driver
8.1.
Acronyms
The table below presents the acronyms used in this module:
8.2.
Acronym
Description
EIC
External Interrupt Controller
MUX
Multiplexer
NMI
Non-Maskable Interrupt
Dependencies
This driver has the following dependencies:
•
8.3.
System Pin Multiplexer Driver
Errata
There are no errata related to this driver.
8.4.
Module History
An overview of the module history is presented in the table below, with details on the enhancements and
fixes made to the module since its first release. The current version of this corresponds to the newest
version in the table.
Changelog
•
•
Driver updated to follow driver type convention
Removed extint_reset(), extint_disable() and extint_enable() functions. Added
internal function _system_extint_init().
•
•
Added configuration EXTINT_CLOCK_SOURCE in conf_extint.h
Removed configuration EXTINT_CALLBACKS_MAX in conf_extint.h, and added channel
parameter in the register functions extint_register_callback() and
extint_unregister_callback()
Updated interrupt handler to clear interrupt flag before calling callback function
Updated initialization function to also enable the digital interface clock to the module if it is disabled
Initial Release
Atmel AT03246: SAM D/R/L/C External Interrupt (EXTINT) Driver [APPLICATION NOTE]
Atmel-42112E-SAM-External-Interrupt-Driver-Extint_AT03246_Application Note-12/2015
21
9.
Examples for EXTINT Driver
This is a list of the available Quick Start guides (QSGs) and example applications for SAM External
Interrupt (EXTINT) Driver. QSGs are simple examples with step-by-step instructions to configure and use
this driver in a selection of use cases. Note that a QSG can be compiled as a standalone application or
be added to the user application.
•
•
9.1.
Quick Start Guide for EXTINT - Basic
Quick Start Guide for EXTINT - Callback
Quick Start Guide for EXTINT - Basic
The supported board list:
•
SAM D20 Xplained Pro
•
SAM D21 Xplained Pro
•
SAM R21 Xplained Pro
•
SAM L21 Xplained Pro
•
SAM L22 Xplained Pro
•
SAM DA1 Xplained Pro
•
SAM C21 Xplained Pro
In this use case, the EXTINT module is configured for:
•
External interrupt channel connected to the board LED is used
•
External interrupt channel is configured to detect both input signal edges
This use case configures a physical I/O pin of the device so that it is routed to a logical External Interrupt
Controller channel to detect rising and falling edges of the incoming signal.
When the board button is pressed, the board LED will light up. When the board button is released, the
LED will turn off.
9.1.1.
Setup
9.1.1.1.
Prerequisites
There are no special setup requirements for this use-case.
9.1.1.2.
Code
Copy-paste the following setup code to your user application:
void configure_extint_channel(void)
{
struct extint_chan_conf config_extint_chan;
extint_chan_get_config_defaults(&config_extint_chan);
}
config_extint_chan.gpio_pin
= BUTTON_0_EIC_PIN;
config_extint_chan.gpio_pin_mux
= BUTTON_0_EIC_MUX;
config_extint_chan.gpio_pin_pull
= EXTINT_PULL_UP;
config_extint_chan.detection_criteria = EXTINT_DETECT_BOTH;
extint_chan_set_config(BUTTON_0_EIC_LINE, &config_extint_chan);
Atmel AT03246: SAM D/R/L/C External Interrupt (EXTINT) Driver [APPLICATION NOTE]
Atmel-42112E-SAM-External-Interrupt-Driver-Extint_AT03246_Application Note-12/2015
22
Add to user application initialization (typically the start of main()):
configure_extint_channel();
9.1.1.3.
Workflow
1.
Create an EXTINT module channel configuration struct, which can be filled out to adjust the
configuration of a single external interrupt channel.
struct extint_chan_conf config_extint_chan;
2.
Initialize the channel configuration struct with the module's default values.
extint_chan_get_config_defaults(&config_extint_chan);
3.
Note: This should always be performed before using the configuration struct to ensure that all
values are initialized to known default settings.
Adjust the configuration struct to configure the pin MUX (to route the desired physical pin to the
logical channel) to the board button, and to configure the channel to detect both rising and falling
edges.
config_extint_chan.gpio_pin
config_extint_chan.gpio_pin_mux
config_extint_chan.gpio_pin_pull
config_extint_chan.detection_criteria
4.
=
=
=
=
BUTTON_0_EIC_PIN;
BUTTON_0_EIC_MUX;
EXTINT_PULL_UP;
EXTINT_DETECT_BOTH;
Configure external interrupt channel with the desired channel settings.
extint_chan_set_config(BUTTON_0_EIC_LINE, &config_extint_chan);
9.1.2.
Use Case
9.1.2.1.
Code
Copy-paste the following code to your user application:
while (true) {
if (extint_chan_is_detected(BUTTON_0_EIC_LINE)) {
// Do something in response to EXTINT edge detection
bool button_pin_state = port_pin_get_input_level(BUTTON_0_PIN);
port_pin_set_output_level(LED_0_PIN, button_pin_state);
}
9.1.2.2.
}
extint_chan_clear_detected(BUTTON_0_EIC_LINE);
Workflow
1.
Read in the current external interrupt channel state to see if an edge has been detected.
if (extint_chan_is_detected(BUTTON_0_EIC_LINE)) {
2.
Read in the new physical button state and mirror it on the board LED.
// Do something in response to EXTINT edge detection
bool button_pin_state = port_pin_get_input_level(BUTTON_0_PIN);
port_pin_set_output_level(LED_0_PIN, button_pin_state);
3.
Clear the detection state of the external interrupt channel so that it is ready to detect a future falling
edge.
extint_chan_clear_detected(BUTTON_0_EIC_LINE);
Atmel AT03246: SAM D/R/L/C External Interrupt (EXTINT) Driver [APPLICATION NOTE]
Atmel-42112E-SAM-External-Interrupt-Driver-Extint_AT03246_Application Note-12/2015
23
9.2.
Quick Start Guide for EXTINT - Callback
The supported board list:
•
SAM D20 Xplained Pro
•
SAM D21 Xplained Pro
•
SAM R21 Xplained Pro
•
SAM L21 Xplained Pro
•
SAM L22 Xplained Pro
•
•
SAM DA1 Xplained Pro
SAM C21 Xplained Pro
In this use case, the EXTINT module is configured for:
•
External interrupt channel connected to the board LED is used
•
External interrupt channel is configured to detect both input signal edges
•
Callbacks are used to handle detections from the External Interrupt
This use case configures a physical I/O pin of the device so that it is routed to a logical External Interrupt
Controller channel to detect rising and falling edges of the incoming signal. A callback function is used to
handle detection events from the External Interrupt module asynchronously.
When the board button is pressed, the board LED will light up. When the board button is released, the
LED will turn off.
9.2.1.
Setup
9.2.1.1.
Prerequisites
There are no special setup requirements for this use-case.
9.2.1.2.
Code
Copy-paste the following setup code to your user application:
void configure_extint_channel(void)
{
struct extint_chan_conf config_extint_chan;
extint_chan_get_config_defaults(&config_extint_chan);
}
config_extint_chan.gpio_pin
= BUTTON_0_EIC_PIN;
config_extint_chan.gpio_pin_mux
= BUTTON_0_EIC_MUX;
config_extint_chan.gpio_pin_pull
= EXTINT_PULL_UP;
config_extint_chan.detection_criteria = EXTINT_DETECT_BOTH;
extint_chan_set_config(BUTTON_0_EIC_LINE, &config_extint_chan);
void configure_extint_callbacks(void)
{
}
extint_register_callback(extint_detection_callback,
BUTTON_0_EIC_LINE,
EXTINT_CALLBACK_TYPE_DETECT);
extint_chan_enable_callback(BUTTON_0_EIC_LINE,
EXTINT_CALLBACK_TYPE_DETECT);
void extint_detection_callback(void)
{
bool pin_state = port_pin_get_input_level(BUTTON_0_PIN);
Atmel AT03246: SAM D/R/L/C External Interrupt (EXTINT) Driver [APPLICATION NOTE]
Atmel-42112E-SAM-External-Interrupt-Driver-Extint_AT03246_Application Note-12/2015
24
}
port_pin_set_output_level(LED_0_PIN, pin_state);
Add to user application initialization (typically the start of main()):
configure_extint_channel();
configure_extint_callbacks();
system_interrupt_enable_global();
9.2.1.3.
Workflow
1.
Create an EXTINT module channel configuration struct, which can be filled out to adjust the
configuration of a single external interrupt channel.
struct extint_chan_conf config_extint_chan;
2.
Initialize the channel configuration struct with the module's default values.
extint_chan_get_config_defaults(&config_extint_chan);
3.
Note: This should always be performed before using the configuration struct to ensure that all
values are initialized to known default settings.
Adjust the configuration struct to configure the pin MUX (to route the desired physical pin to the
logical channel) to the board button, and to configure the channel to detect both rising and falling
edges.
config_extint_chan.gpio_pin
config_extint_chan.gpio_pin_mux
config_extint_chan.gpio_pin_pull
config_extint_chan.detection_criteria
4.
=
=
=
=
BUTTON_0_EIC_PIN;
BUTTON_0_EIC_MUX;
EXTINT_PULL_UP;
EXTINT_DETECT_BOTH;
Configure external interrupt channel with the desired channel settings.
extint_chan_set_config(BUTTON_0_EIC_LINE, &config_extint_chan);
5.
Register a callback function extint_handler() to handle detections from the External Interrupt
controller.
extint_register_callback(extint_detection_callback,
BUTTON_0_EIC_LINE,
EXTINT_CALLBACK_TYPE_DETECT);
6.
Enable the registered callback function for the configured External Interrupt channel, so that it will
be called by the module when the channel detects an edge.
extint_chan_enable_callback(BUTTON_0_EIC_LINE,
EXTINT_CALLBACK_TYPE_DETECT);
7.
Define the EXTINT callback that will be fired when a detection event occurs. For this example, a
LED will mirror the new button state on each detection edge.
void extint_detection_callback(void)
{
}
bool pin_state = port_pin_get_input_level(BUTTON_0_PIN);
port_pin_set_output_level(LED_0_PIN, pin_state);
Atmel AT03246: SAM D/R/L/C External Interrupt (EXTINT) Driver [APPLICATION NOTE]
Atmel-42112E-SAM-External-Interrupt-Driver-Extint_AT03246_Application Note-12/2015
25
9.2.2.
Use Case
9.2.2.1.
Code
Copy-paste the following code to your user application:
while (true) {
/* Do nothing - EXTINT will fire callback asynchronously */
}
9.2.2.2.
Workflow
1.
External interrupt events from the driver are detected asynchronously; no special application
main() code is required.
Atmel AT03246: SAM D/R/L/C External Interrupt (EXTINT) Driver [APPLICATION NOTE]
Atmel-42112E-SAM-External-Interrupt-Driver-Extint_AT03246_Application Note-12/2015
26
10.
Document Revision History
Doc. Rev. Date
Comments
42112E
12/2015 Added support for SAM L21/L22, SAM C21, SAM D09, and SAM DA1
42112D
12/2014 Added support for SAM R21 and SAM D10/D11
42112C
01/2014 Added support for SAM D21
42112B
06/2013 Added additional documentation on the event system. Corrected documentation
typos.
42112A
06/2013 Initial release
Atmel AT03246: SAM D/R/L/C External Interrupt (EXTINT) Driver [APPLICATION NOTE]
Atmel-42112E-SAM-External-Interrupt-Driver-Extint_AT03246_Application Note-12/2015
27
Atmel Corporation
©
1600 Technology Drive, San Jose, CA 95110 USA
T: (+1)(408) 441.0311
F: (+1)(408) 436.4200
|
www.atmel.com
2015 Atmel Corporation. / Rev.: Atmel-42112E-SAM-External-Interrupt-Driver-Extint_AT03246_Application Note-12/2015
®
®
Atmel , Atmel logo and combinations thereof, Enabling Unlimited Possibilities , and others are registered trademarks or trademarks of Atmel Corporation in U.S. and
®
®
other countries. ARM , ARM Connected logo, and others are registered trademarks of ARM Ltd. Other terms and product names may be trademarks of others.
DISCLAIMER: The information in this document is provided in connection with Atmel products. No license, express or implied, by estoppel or otherwise, to any
intellectual property right is granted by this document or in connection with the sale of Atmel products. EXCEPT AS SET FORTH IN THE ATMEL TERMS AND
CONDITIONS OF SALES LOCATED ON THE ATMEL WEBSITE, ATMEL ASSUMES NO LIABILITY WHATSOEVER AND DISCLAIMS ANY EXPRESS, IMPLIED
OR STATUTORY WARRANTY RELATING TO ITS PRODUCTS INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTY OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL ATMEL BE LIABLE FOR ANY DIRECT, INDIRECT,
CONSEQUENTIAL, PUNITIVE, SPECIAL OR INCIDENTAL DAMAGES (INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS AND PROFITS, BUSINESS
INTERRUPTION, OR LOSS OF INFORMATION) ARISING OUT OF THE USE OR INABILITY TO USE THIS DOCUMENT, EVEN IF ATMEL HAS BEEN ADVISED
OF THE POSSIBILITY OF SUCH DAMAGES. Atmel makes no representations or warranties with respect to the accuracy or completeness of the contents of this
document and reserves the right to make changes to specifications and products descriptions at any time without notice. Atmel does not make any commitment to
update the information contained herein. Unless specifically provided otherwise, Atmel products are not suitable for, and shall not be used in, automotive
applications. Atmel products are not intended, authorized, or warranted for use as components in applications intended to support or sustain life.
SAFETY-CRITICAL, MILITARY, AND AUTOMOTIVE APPLICATIONS DISCLAIMER: Atmel products are not designed for and will not be used in connection with any
applications where the failure of such products would reasonably be expected to result in significant personal injury or death (“Safety-Critical Applications”) without
an Atmel officer's specific written consent. Safety-Critical Applications include, without limitation, life support devices and systems, equipment or systems for the
operation of nuclear facilities and weapons systems. Atmel products are not designed nor intended for use in military or aerospace applications or environments
unless specifically designated by Atmel as military-grade. Atmel products are not designed nor intended for use in automotive applications unless specifically
designated by Atmel as automotive-grade.