sam4l external interrupt controller (eic)...

SMART ARM-based Microcontrollers

AT07901: SAM4L External Interrupt Controller(EIC) Driver

APPLICATION NOTE

Introduction

This driver for Atmel® | SMART ARM®-based microcontrollers provides aninterface for the configuration and management of the device's on-chipExternal Interrupt Controller (EIC).

Devices from the following series can use this module:• Atmel | SMART SAM4L

The outline of this documentation is as follows:• Prerequisites• Module Overview• Special Considerations• Extra Information• Examples• API Overview

Atmel-42278B-SAM4L-External-Interrupt-Controller-EIC-Driver_AT07901_Application Note-07/2015

Table of Contents

Introduction......................................................................................................................1

1. Software License....................................................................................................... 4

2. Module Overview.......................................................................................................5

3. Special Considerations..............................................................................................6

4. Prerequisites..............................................................................................................7

5. Extra Information....................................................................................................... 8

6. Examples...................................................................................................................9

7. API Overview...........................................................................................................107.1. Variable and Type Definitions.....................................................................................................10

7.1.1. Type eic_callback_t..................................................................................................... 107.2. Structure Definitions................................................................................................................... 10

7.2.1. Struct eic_line_config...................................................................................................107.3. Macro Definitions........................................................................................................................10

7.3.1. External Interrupt lines.................................................................................................107.3.2. Mode Trigger Options.................................................................................................. 117.3.3. Edge level Options.......................................................................................................117.3.4. Level Options...............................................................................................................127.3.5. Filter Options............................................................................................................... 127.3.6. Synch Mode Options................................................................................................... 12

7.4. Function Definitions....................................................................................................................137.4.1. Function eic_disable()..................................................................................................137.4.2. Function eic_enable().................................................................................................. 137.4.3. Function eic_line_clear_interrupt().............................................................................. 137.4.4. Function eic_line_disable().......................................................................................... 137.4.5. Function eic_line_disable_interrupt()...........................................................................147.4.6. Function eic_line_enable()...........................................................................................147.4.7. Function eic_line_enable_interrupt()........................................................................... 147.4.8. Function eic_line_interrupt_is_enabled().....................................................................157.4.9. Function eic_line_interrupt_is_pending().....................................................................157.4.10. Function eic_line_is_enabled().................................................................................... 157.4.11. Function eic_line_set_callback()..................................................................................167.4.12. Function eic_line_set_config()..................................................................................... 16

8. Extra Information for EIC......................................................................................... 188.1. Acronyms....................................................................................................................................188.2. Dependencies.............................................................................................................................188.3. Errata..........................................................................................................................................188.4. Module History............................................................................................................................18

Atmel AT07901: SAM4L External Interrupt Controller (EIC) Driver [APPLICATION NOTE]Atmel-42278B-SAM4L-External-Interrupt-Controller-EIC-Driver_AT07901_Application Note-07/2015

2

9. Quickstart guide for SAM EIC driver........................................................................199.1. Basic Use Case..........................................................................................................................19

9.1.1. Prerequisites................................................................................................................199.2. Setup Steps................................................................................................................................19

9.2.1. Example Code............................................................................................................. 199.2.2. Workflow...................................................................................................................... 20

10. Document Revision History..................................................................................... 21


3

1. Software LicenseRedistribution and use in source and binary forms, with or without modification, are permitted providedthat the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and thefollowing disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and thefollowing 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 withoutspecific 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, FITNESSFOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT ARE EXPRESSLY AND SPECIFICALLYDISCLAIMED. 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; ORBUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHERIN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISINGIN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OFSUCH DAMAGE.


4

2. Module OverviewThe External Interrupt Controller (EIC) allows pins to be configured as external interrupts. Each externalinterrupt has its own interrupt request and can be individually masked. Each external interrupt cangenerate an interrupt on rising or falling edge, or high or low level. Every interrupt input has a configurablefilter to remove spikes from the interrupt source. Every interrupt pin can also be configured to beasynchronous, in order to wake-up the part from sleep modes where the CLK_SYNC clock has beendisabled.

An additional Non-Maskable Interrupt (NMI) pin is also supported. This has the same properties as theother external interrupts, but is connected to the NMI request of the CPU, enabling it to interrupt any otherinterrupt mode.


5

3. Special Considerations• The external interrupt pins (EXTINTn and NMI) may be multiplexed with I/O Controller lines. The

programmer must first program the I/O Controller to assign the desired EIC pins to their peripheralfunction. If I/O lines of the EIC are not used by the application, they can be used for other purposesby the I/O Controller. It is only required to enable the EIC inputs actually in use. For example, if anapplication only requires two external interrupts, then only two I/O lines will be assigned to EICinputs.

• All interrupts are available in all sleep modes as long as the EIC module is powered. However, insleep modes where CLK_SYNC is stopped, the interrupt must be configured to asynchronousmode.

• The clock for the EIC bus interface (CLK_EIC) is generated by the Power Manager. This clock isenabled at reset, and can be disabled in the Power Manager. The filter and synchronous edge/leveldetector runs on a clock which is stopped in any of the sleep modes where the system RC oscillator(RCSYS) is not running. This clock is referred to as CLK_SYNC.

• The external interrupt request lines are connected to the NVIC. Using the external interruptsrequires the NVIC to be programmed first. Using the Non-Maskable Interrupt does not require theNVIC to be programmed.

• When an external debugger forces the CPU into debug mode, the EIC continues normal operation.If the EIC is configured in a way that requires it to be periodically serviced by the CPU throughinterrupts or similar, improper operation or data loss may result during debugging.


6

4. Prerequisites• None


7

5. Extra InformationFor extra information, see Extra Information for EIC. This includes:

• Acronyms• Dependencies• Errata• Module History


8

6. ExamplesFor a list of examples related to this driver, see

• Quickstart guide for SAM EIC driver


9

7. API Overview

7.1. Variable and Type Definitions

7.1.1. Type eic_callback_t

typedef void(* eic_callback_t )(void)

7.2. Structure Definitions

7.2.1. Struct eic_line_config

Configuration parameters of the EIC module.

Table 7-1 Members

Type Name Description

uint8_t eic_async Async: EIC_ASYNCH_MODE or EIC_SYNCH_MODE

uint8_t eic_edge Edge: EIC_EDGE_FALLING_EDGE or EIC_EDGE_RISING_EDGE

uint8_t eic_filter Filter: EIC_FILTER_DISABLED or EIC_FILTER_ENABLED

uint8_t eic_level Level: EIC_LEVEL_LOW_LEVEL or EIC_LEVEL_HIGH_LEVEL

uint8_t eic_mode Mode: EIC_MODE_EDGE_TRIGGERED or EIC_MODE_LEVEL_TRIGGERED

7.3. Macro Definitions

7.3.1. External Interrupt lines

Number of available EIC lines, device dependent.

7.3.1.1. Macro EXT_NMI

#define EXT_NMI

Non-Maskable Interrupt.

7.3.1.2. Macro EXT_INT1

#define EXT_INT1

External Interrupt 1.


#define EXT_INT2


10



#define EXT_INT3



#define EXT_INT4



#define EXT_INT5



#define EXT_INT6



#define EXT_INT7



#define EXT_INT8


7.3.2. Mode Trigger Options

7.3.2.1. Macro EIC_MODE_EDGE_TRIGGERED

#define EIC_MODE_EDGE_TRIGGERED

The interrupt is edge triggered.

7.3.2.2. Macro EIC_MODE_LEVEL_TRIGGERED

#define EIC_MODE_LEVEL_TRIGGERED

The interrupt is level triggered.

7.3.3. Edge level Options

7.3.3.1. Macro EIC_EDGE_FALLING_EDGE

#define EIC_EDGE_FALLING_EDGE


11

The interrupt triggers on falling edge.

7.3.3.2. Macro EIC_EDGE_RISING_EDGE

#define EIC_EDGE_RISING_EDGE

The interrupt triggers on rising edge.

7.3.4. Level Options

7.3.4.1. Macro EIC_LEVEL_LOW_LEVEL

#define EIC_LEVEL_LOW_LEVEL

The interrupt triggers on low level.

7.3.4.2. Macro EIC_LEVEL_HIGH_LEVEL

#define EIC_LEVEL_HIGH_LEVEL

The interrupt triggers on high level.

7.3.5. Filter Options

7.3.5.1. Macro EIC_FILTER_ENABLED

#define EIC_FILTER_ENABLED

The interrupt is filtered.

7.3.5.2. Macro EIC_FILTER_DISABLED

#define EIC_FILTER_DISABLED

The interrupt is not filtered.

7.3.6. Synch Mode Options

7.3.6.1. Macro EIC_SYNCH_MODE

#define EIC_SYNCH_MODE

The interrupt is synchronized to CLK_SYNC.

7.3.6.2. Macro EIC_ASYNCH_MODE

#define EIC_ASYNCH_MODE

The interrupt is asynchronous.


12

7.4. Function Definitions

7.4.1. Function eic_disable()

Disable the EIC module.

void eic_disable( Eic * eic)

Table 7-2 Parameters

Data direction Parameter name Description

[in] eic Base address of the EIC module

7.4.2. Function eic_enable()

Enable the EIC module.

void eic_enable( Eic * eic)




7.4.3. Function eic_line_clear_interrupt()

Clear the interrupt flag of specified pin. Call this function once you have handled the interrupt.

void eic_line_clear_interrupt( Eic * eic, uint8_t line_number)



[in] eic Base address of the EIC (i.e. EIC)

[in] line_number Line number to clear

7.4.4. Function eic_line_disable()

Disable the external interrupt on specified line.

void eic_line_disable( Eic * eic, uint8_t line_number)


13




[in] line_number Line number to disable

7.4.5. Function eic_line_disable_interrupt()

Disables the propagation from the EIC to the interrupt controller of the external interrupt on a specifiedline.

void eic_line_disable_interrupt( Eic * eic, uint8_t line_number)



[in] eic Base address of the EIC (i.e. EIC)

[in] line_number Line number of interrupt to disable

7.4.6. Function eic_line_enable()

Enable the external interrupt on specified line.

void eic_line_enable( Eic * eic, uint8_t line_number)




[in] line_number The line number to enable

7.4.7. Function eic_line_enable_interrupt()

Enables the propagation from the EIC to the interrupt controller of the external interrupt on a specifiedline.

void eic_line_enable_interrupt( Eic * eic, uint8_t line_number)




[in] line_number Line number of interrupt to enable


14

7.4.8. Function eic_line_interrupt_is_enabled()

Tells whether an EIC interrupt line is enabled.

bool eic_line_interrupt_is_enabled( Eic * eic, uint8_t line_number)




[in] line_number Line number to test

Table 7-10 Return Values

Return value Description

true EIC interrupt line is enabled

false EIC interrupt line is not enabled

7.4.9. Function eic_line_interrupt_is_pending()

Tells whether an EIC interrupt line is pending.

bool eic_line_interrupt_is_pending( Eic * eic, uint8_t line_number)







true EIC interrupt line is pending

false EIC interrupt line is not pending

7.4.10. Function eic_line_is_enabled()

Tells whether an EIC line is enabled.

bool eic_line_is_enabled( Eic * eic, uint8_t line_number)


15







true EIC line is enabled

false EIC line is not enabled

7.4.11. Function eic_line_set_callback()

Set callback for given EIC line.

void eic_line_set_callback( Eic * eic, uint8_t line_number, eic_callback_t callback, uint8_t irq_line, uint8_t irq_level)




[in] line_number Number of line

[in] callback Callback function pointer

[in] irq_line Interrupt line number (EIC_1_IRQn to EIC_8_IRQn)

[in] irq_level Interrupt level (the priority of the interrupt request)

7.4.12. Function eic_line_set_config()

Program the EIC hardware with the specified configuration.

void eic_line_set_config( Eic * eic, uint8_t line_number, struct eic_line_config * eic_line_conf)


16




[in] line_number Number of line to configure

[in] eic_line_conf Configuration parameters for the EIC module (see eic_line_config)


17

8. Extra Information for EIC

8.1. AcronymsBelow is a table listing the acronyms used in this module, along with their intended meanings.

Acronym Definition

EIC External Interrupt Controller

GPIO General-Purpose Input/Output

NMI Non-Maskable Interrupt

NVIC Nested Vectored Interrupt Controller

QSG Quick Start Guide

8.2. Dependencies• Clocks• I/O Lines• Interrupts• Debug Operation

8.3. ErrataThere are no errata related to this driver.

8.4. Module HistoryAn overview of the module history is presented in the table below, with details on the enhancements andfixes made to the module since its first release. The current version of this corresponds to the newestversion in the table.

Changelog

Initial document release


18

9. Quickstart guide for SAM EIC driverThis is the quickstart guide for the SAM4L External Interrupt Controller (EIC) Driver, with step-by-stepinstructions on how to configure and use the driver in a selection of use cases.

The use cases contain several code fragments. The code fragments in the steps for setup can be copiedinto a custom initialization function, while the steps for usage can be copied into, e.g., the mainapplication function.

9.1. Basic Use Case

In this basic use case, the EIC module and single line are configured for:• Falling edge trigger and async mode• Interrupt-based handling• GPIO_PUSH_BUTTON_EIC_IRQ as input

9.1.1. Prerequisites

System Clock Management (Sysclock).

9.2. Setup Steps

9.2.1. Example Code

Add to application C-file:static void eic_callback(void){ /* Check if EIC push button line interrupt line is pending. */ if (eic_line_interrupt_is_pending(EIC, GPIO_PUSH_BUTTON_EIC_LINE)) { eic_line_clear_interrupt(EIC, GPIO_PUSH_BUTTON_EIC_LINE); bToggle = 1; }}

static void eic_setup(void){ eic_enable(EIC);

struct eic_line_config eic_line_conf; eic_line_conf.eic_mode = EIC_MODE_EDGE_TRIGGERED; eic_line_conf.eic_edge = EIC_EDGE_FALLING_EDGE; eic_line_conf.eic_level = EIC_LEVEL_LOW_LEVEL; eic_line_conf.eic_filter = EIC_FILTER_DISABLED; eic_line_conf.eic_async = EIC_ASYNCH_MODE;

eic_line_set_config(EIC, GPIO_PUSH_BUTTON_EIC_LINE, &eic_line_conf); eic_line_set_callback(EIC, GPIO_PUSH_BUTTON_EIC_LINE, eic_callback, GPIO_PUSH_BUTTON_EIC_IRQ, 1); eic_line_enable(EIC, GPIO_PUSH_BUTTON_EIC_LINE);}


19

9.2.2. Workflow

Define the interrupt callback function in the application:static void eic_callback(void){ /* Check if EIC push button line interrupt line is pending. */ if (eic_line_interrupt_is_pending(EIC, GPIO_PUSH_BUTTON_EIC_LINE)) { eic_line_clear_interrupt(EIC, GPIO_PUSH_BUTTON_EIC_LINE); bToggle = 1; }}

Enable EIC module:eic_enable(EIC);

Note: Including enable module clock and lock sleep mode.

Configure EIC line with specified mode:eic_line_set_config(EIC, GPIO_PUSH_BUTTON_EIC_LINE, &eic_line_conf);

Set the EIC callback function and enable EIC interrupt.eic_line_set_callback(EIC, GPIO_PUSH_BUTTON_EIC_LINE, eic_callback,GPIO_PUSH_BUTTON_EIC_IRQ, 1);

Enable EIC line:eic_line_enable(EIC, GPIO_PUSH_BUTTON_EIC_LINE);


20

10. Document Revision HistoryDoc. Rev. Date Comments

42278B 07/2015 Updated title of application note and added list of supported devices

42278A 05/2014 Initial document release


21

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-42278B-SAM4L-External-Interrupt-Controller-EIC-Driver_AT07901_Application Note-07/2015

Atmel®, Atmel logo and combinations thereof, Enabling Unlimited Possibilities®, and others are registered trademarks or trademarks of Atmel Corporation in U.S. andother countries. ARM®, ARM Connected®, 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 anyintellectual property right is granted by this document or in connection with the sale of Atmel products. EXCEPT AS SET FORTH IN THE ATMEL TERMS ANDCONDITIONS OF SALES LOCATED ON THE ATMEL WEBSITE, ATMEL ASSUMES NO LIABILITY WHATSOEVER AND DISCLAIMS ANY EXPRESS, IMPLIEDOR 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, BUSINESSINTERRUPTION, OR LOSS OF INFORMATION) ARISING OUT OF THE USE OR INABILITY TO USE THIS DOCUMENT, EVEN IF ATMEL HAS BEEN ADVISEDOF THE POSSIBILITY OF SUCH DAMAGES. Atmel makes no representations or warranties with respect to the accuracy or completeness of the contents of thisdocument and reserves the right to make changes to specifications and products descriptions at any time without notice. Atmel does not make any commitment toupdate the information contained herein. Unless specifically provided otherwise, Atmel products are not suitable for, and shall not be used in, automotiveapplications. 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 anyapplications where the failure of such products would reasonably be expected to result in significant personal injury or death (“Safety-Critical Applications”) withoutan Atmel officer's specific written consent. Safety-Critical Applications include, without limitation, life support devices and systems, equipment or systems for theoperation of nuclear facilities and weapons systems. Atmel products are not designed nor intended for use in military or aerospace applications or environmentsunless specifically designated by Atmel as military-grade. Atmel products are not designed nor intended for use in automotive applications unless specificallydesignated by Atmel as automotive-grade.

https://www.facebook.com/AtmelCorporationhttps://twitter.com/Atmelhttp://www.linkedin.com/company/atmel-corporationhttps://plus.google.com/106109247591403112418/postshttp://www.youtube.com/user/AtmelCorporationhttp://en.wikipedia.org/wiki/Atmelhttp://www.atmel.com

IntroductionTable of Contents1. Software License2. Module Overview3. Special Considerations4. Prerequisites5. Extra Information6. Examples7. API Overview7.1. Variable and Type Definitions7.1.1. Type eic_callback_t

7.2. Structure Definitions7.2.1. Struct eic_line_config

7.3. Macro Definitions7.3.1. External Interrupt lines7.3.1.1. Macro EXT_NMI7.3.1.2. Macro EXT_INT17.3.1.3. Macro EXT_INT27.3.1.4. Macro EXT_INT37.3.1.5. Macro EXT_INT47.3.1.6. Macro EXT_INT57.3.1.7. Macro EXT_INT67.3.1.8. Macro EXT_INT77.3.1.9. Macro EXT_INT8

7.3.2. Mode Trigger Options7.3.2.1. Macro EIC_MODE_EDGE_TRIGGERED7.3.2.2. Macro EIC_MODE_LEVEL_TRIGGERED

7.3.3. Edge level Options7.3.3.1. Macro EIC_EDGE_FALLING_EDGE7.3.3.2. Macro EIC_EDGE_RISING_EDGE

7.3.4. Level Options7.3.4.1. Macro EIC_LEVEL_LOW_LEVEL7.3.4.2. Macro EIC_LEVEL_HIGH_LEVEL

7.3.5. Filter Options7.3.5.1. Macro EIC_FILTER_ENABLED7.3.5.2. Macro EIC_FILTER_DISABLED

7.3.6. Synch Mode Options7.3.6.1. Macro EIC_SYNCH_MODE7.3.6.2. Macro EIC_ASYNCH_MODE

7.4. Function Definitions7.4.1. Function eic_disable()7.4.2. Function eic_enable()7.4.3. Function eic_line_clear_interrupt()7.4.4. Function eic_line_disable()7.4.5. Function eic_line_disable_interrupt()7.4.6. Function eic_line_enable()7.4.7. Function eic_line_enable_interrupt()7.4.8. Function eic_line_interrupt_is_enabled()7.4.9. Function eic_line_interrupt_is_pending()7.4.10. Function eic_line_is_enabled()7.4.11. Function eic_line_set_callback()7.4.12. Function eic_line_set_config()

8. Extra Information for EIC8.1. Acronyms8.2. Dependencies8.3. Errata8.4. Module History

9. Quickstart guide for SAM EIC driver9.1. Basic Use Case9.1.1. Prerequisites

9.2. Setup Steps9.2.1. Example Code9.2.2. Workflow

10. Document Revision History

sam4l external interrupt controller (eic)...

Documents