This driver for Atmel® | SMART ARM®-based microcontrollers provides an interface for the configuration and management of internal software and hardware interrupts/exceptions.

The following peripheral is used by this module:

NVIC (Nested Vector 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 R30
Atmel | SMART SAM R34
Atmel | SMART SAM R35

The outline of this documentation is as follows:

Prerequisites

There are no prerequisites for this module.

Module Overview

The ARM® Cortex® M0+ core contains an interrupt and exception vector table, which can be used to configure the device's interrupt handlers; individual interrupts and exceptions can be enabled and disabled, as well as configured with a variable priority.

This driver provides a set of wrappers around the core interrupt functions, to expose a simple API for the management of global and individual interrupts within the device.

Critical Sections

In some applications it is important to ensure that no interrupts may be executed by the system whilst a critical portion of code is being run; for example, a buffer may be copied from one context to another - during which interrupts must be disabled to avoid corruption of the source buffer contents until the copy has completed. This driver provides a basic API to enter and exit nested critical sections, so that global interrupts can be kept disabled for as long as necessary to complete a critical application code section.

Software Interrupts

For some applications, it may be desirable to raise a module or core interrupt via software. For this reason, a set of APIs to set an interrupt or exception as pending are provided to the user application.

Special Considerations

Interrupts from peripherals in the SAM devices are on a per-module basis; an interrupt raised from any source within a module will cause a single, module-common handler to execute. It is the user application or driver's responsibility to de-multiplex the module-common interrupt to determine the exact interrupt cause.

Extra Information

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

Examples

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

API Overview

Enumerations
enum	system_interrupt_priority_level { SYSTEM_INTERRUPT_PRIORITY_LEVEL_0 = 0, SYSTEM_INTERRUPT_PRIORITY_LEVEL_1 = 1, SYSTEM_INTERRUPT_PRIORITY_LEVEL_2 = 2, SYSTEM_INTERRUPT_PRIORITY_LEVEL_3 = 3 }
	Table of possible system interrupt/exception vector priorities. More...

enum	system_interrupt_vector_saml21 { SYSTEM_INTERRUPT_NON_MASKABLE = NonMaskableInt_IRQn, SYSTEM_INTERRUPT_HARD_FAULT = HardFault_IRQn, SYSTEM_INTERRUPT_SV_CALL = SVCall_IRQn, SYSTEM_INTERRUPT_PENDING_SV = PendSV_IRQn, SYSTEM_INTERRUPT_SYSTICK = SysTick_IRQn, SYSTEM_INTERRUPT_MODULE_SYSTEM = SYSTEM_IRQn, SYSTEM_INTERRUPT_MODULE_WDT = WDT_IRQn, SYSTEM_INTERRUPT_MODULE_RTC = RTC_IRQn, SYSTEM_INTERRUPT_MODULE_EIC = EIC_IRQn, SYSTEM_INTERRUPT_MODULE_NVMCTRL = NVMCTRL_IRQn, SYSTEM_INTERRUPT_MODULE_DMA = DMAC_IRQn, SYSTEM_INTERRUPT_MODULE_USB = USB_IRQn, SYSTEM_INTERRUPT_MODULE_EVSYS = EVSYS_IRQn, SYSTEM_INTERRUPT_MODULE_SERCOMn = SERCOMn_IRQn, SYSTEM_INTERRUPT_MODULE_TCCn = TCCn_IRQn, SYSTEM_INTERRUPT_MODULE_TCn = TCn_IRQn, SYSTEM_INTERRUPT_MODULE_AC = AC_IRQn, SYSTEM_INTERRUPT_MODULE_ADC = ADC_IRQn, SYSTEM_INTERRUPT_MODULE_DAC = DAC_IRQn, SYSTEM_INTERRUPT_MODULE_PTC = PTC_IRQn, SYSTEM_INTERRUPT_MODULE_AES = AES_IRQn, SYSTEM_INTERRUPT_MODULE_TRNG = TRNG_IRQn }
	Table of possible system interrupt/exception vector numbers. More...

Critical Section Management
static void	system_interrupt_enter_critical_section (void)
	Enters a critical section. More...

static void	system_interrupt_leave_critical_section (void)
	Leaves a critical section. More...

Interrupt Enabling/Disabling
static bool	system_interrupt_is_global_enabled (void)
	Check if global interrupts are enabled. More...

static void	system_interrupt_enable_global (void)
	Enables global interrupts. More...

static void	system_interrupt_disable_global (void)
	Disables global interrupts. More...

static bool	system_interrupt_is_enabled (const enum system_interrupt_vector vector)
	Checks if an interrupt vector is enabled or not. More...

static void	system_interrupt_enable (const enum system_interrupt_vector vector)
	Enable interrupt vector. More...

static void	system_interrupt_disable (const enum system_interrupt_vector vector)
	Disable interrupt vector. More...

Interrupt State Management
static enum system_interrupt_vector	system_interrupt_get_active (void)
	Get active interrupt (if any). More...

bool	system_interrupt_is_pending (const enum system_interrupt_vector vector)
	Check if a interrupt line is pending. More...

enum status_code	system_interrupt_set_pending (const enum system_interrupt_vector vector)
	Set a interrupt vector as pending. More...

enum status_code	system_interrupt_clear_pending (const enum system_interrupt_vector vector)
	Clear pending interrupt vector. More...

Interrupt Priority Management
enum status_code	system_interrupt_set_priority (const enum system_interrupt_vector vector, const enum system_interrupt_priority_level priority_level)
	Set interrupt vector priority level. More...

enum system_interrupt_priority_level	system_interrupt_get_priority (const enum system_interrupt_vector vector)
	Get interrupt vector priority level. More...

enum system_interrupt_priority_level

Table of possible system interrupt/exception vector priorities.

Table of all possible interrupt and exception vector priorities within the device.

Enumerator
SYSTEM_INTERRUPT_PRIORITY_LEVEL_0	Priority level 0, the highest possible interrupt priority.
SYSTEM_INTERRUPT_PRIORITY_LEVEL_1	Priority level 1.
SYSTEM_INTERRUPT_PRIORITY_LEVEL_2	Priority level 2.
SYSTEM_INTERRUPT_PRIORITY_LEVEL_3	Priority level 3, the lowest possible interrupt priority.

enum system_interrupt_vector_saml21

Table of possible system interrupt/exception vector numbers.

Table of all possible interrupt and exception vector indexes within the SAM L21 device.

Note: The actual enumeration name is "system_interrupt_vector".

Enumerator
SYSTEM_INTERRUPT_NON_MASKABLE	Interrupt vector index for a NMI interrupt.
SYSTEM_INTERRUPT_HARD_FAULT	Interrupt vector index for a Hard Fault memory access exception.
SYSTEM_INTERRUPT_SV_CALL	Interrupt vector index for a Supervisor Call exception.
SYSTEM_INTERRUPT_PENDING_SV	Interrupt vector index for a Pending Supervisor interrupt.
SYSTEM_INTERRUPT_SYSTICK	Interrupt vector index for a System Tick interrupt.
SYSTEM_INTERRUPT_MODULE_SYSTEM	Interrupt vector index for MCLK, OSCCTRL, OSC32KCTRL, PAC, PM, SUPC, TAL peripheral interrupt.
SYSTEM_INTERRUPT_MODULE_WDT	Interrupt vector index for a Watch Dog peripheral interrupt.
SYSTEM_INTERRUPT_MODULE_RTC	Interrupt vector index for a Real Time Clock peripheral interrupt.
SYSTEM_INTERRUPT_MODULE_EIC	Interrupt vector index for an External Interrupt peripheral interrupt.
SYSTEM_INTERRUPT_MODULE_NVMCTRL	Interrupt vector index for a Non Volatile Memory Controller interrupt.
SYSTEM_INTERRUPT_MODULE_DMA	Interrupt vector index for a Direct Memory Access interrupt.
SYSTEM_INTERRUPT_MODULE_USB	Interrupt vector index for a Universal Serial Bus interrupt.
SYSTEM_INTERRUPT_MODULE_EVSYS	Interrupt vector index for an Event System interrupt.
SYSTEM_INTERRUPT_MODULE_SERCOMn	Interrupt vector index for a SERCOM peripheral interrupt. Each specific device may contain several SERCOM peripherals; each module instance will have its own entry in the table, with the instance number substituted for "n" in the entry name (e.g. `SYSTEM_INTERRUPT_MODULE_SERCOM0`).
SYSTEM_INTERRUPT_MODULE_TCCn	Interrupt vector index for a Timer/Counter Control peripheral interrupt. Each specific device may contain several TCC peripherals; each module instance will have its own entry in the table, with the instance number substituted for "n" in the entry name (e.g. `SYSTEM_INTERRUPT_MODULE_TCC0`).
SYSTEM_INTERRUPT_MODULE_TCn	Interrupt vector index for a Timer/Counter peripheral interrupt. Each specific device may contain several TC peripherals; each module instance will have its own entry in the table, with the instance number substituted for "n" in the entry name (e.g. `SYSTEM_INTERRUPT_MODULE_TC3`).
SYSTEM_INTERRUPT_MODULE_AC	Interrupt vector index for an Analog Comparator peripheral interrupt.
SYSTEM_INTERRUPT_MODULE_ADC	Interrupt vector index for an Analog-to-Digital peripheral interrupt.
SYSTEM_INTERRUPT_MODULE_DAC	Interrupt vector index for a Digital-to-Analog peripheral interrupt.
SYSTEM_INTERRUPT_MODULE_PTC	Interrupt vector index for a Peripheral Touch Controller peripheral interrupt.
SYSTEM_INTERRUPT_MODULE_AES	Interrupt vector index for a AES peripheral interrupt.
SYSTEM_INTERRUPT_MODULE_TRNG	Interrupt vector index for a TRNG peripheral interrupt.

enum status_code system_interrupt_clear_pending ( const enum system_interrupt_vector vector )

Clear pending interrupt vector.

Clear a pending interrupt vector, so the software handler is not executed.

Parameters

[in] vector Interrupt vector number to clear

Returns: A status code identifying if the interrupt pending state was successfully cleared.

Return values

STATUS_OK	If no error was detected
STATUS_INVALID_ARG	If an unsupported interrupt vector number was given

References Assert, STATUS_ERR_INVALID_ARG, STATUS_OK, SYSTEM_INTERRUPT_NON_MASKABLE, and SYSTEM_INTERRUPT_SYSTICK.

static void system_interrupt_disable ( const enum system_interrupt_vector vector )

inlinestatic

Disable interrupt vector.

Disables execution of the software handler for the requested interrupt vector.

Parameters

[in] vector Interrupt vector to disable

Referenced by usart_disable().

static void system_interrupt_disable_global ( void )

inlinestatic

Disables global interrupts.

Disabled global interrupts in the device, preventing any enabled interrupt handlers from executing.

References cpu_irq_disable.

static void system_interrupt_enable ( const enum system_interrupt_vector vector )

inlinestatic

Enable interrupt vector.

Enables execution of the software handler for the requested interrupt vector.

Parameters

[in] vector Interrupt vector to enable

Referenced by _system_extint_init(), events_add_hook(), tc_enable_callback(), and usart_enable().

static void system_interrupt_enable_global ( void )

inlinestatic

Enables global interrupts.

Enables global interrupts in the device to fire any enabled interrupt handlers.

References cpu_irq_enable.

static void system_interrupt_enter_critical_section ( void )

inlinestatic

Enters a critical section.

Disables global interrupts. To support nested critical sections, an internal count of the critical section nesting will be kept, so that global interrupts are only re-enabled upon leaving the outermost nested critical section.

References cpu_irq_enter_critical().

Referenced by _events_find_first_free_channel_and_allocate(), _events_release_channel(), _usart_read_buffer(), _usart_write_buffer(), events_trigger(), system_gclk_chan_disable(), system_gclk_chan_enable(), system_gclk_chan_get_hz(), system_gclk_chan_is_enabled(), system_gclk_chan_is_locked(), system_gclk_chan_lock(), system_gclk_gen_disable(), system_gclk_gen_enable(), system_gclk_gen_get_hz(), system_gclk_gen_is_enabled(), system_gclk_gen_set_config(), and usart_lock().

static enum system_interrupt_vector system_interrupt_get_active ( void )

inlinestatic

Get active interrupt (if any).

Return the vector number for the current executing software handler, if any.

Returns: Interrupt number that is currently executing.

enum system_interrupt_priority_level system_interrupt_get_priority ( const enum system_interrupt_vector vector )

Get interrupt vector priority level.

Retrieves the priority level of the requested external interrupt or exception.

Parameters

[in] vector Interrupt vector of which the priority level will be read

Returns: Currently configured interrupt priority level of the given interrupt vector.

References SYSTEM_INTERRUPT_PRIORITY_LEVEL_0, and SYSTEM_INTERRUPT_SYSTICK.

static bool system_interrupt_is_enabled ( const enum system_interrupt_vector vector )

inlinestatic

Checks if an interrupt vector is enabled or not.

Checks if a specific interrupt vector is currently enabled.

Parameters

[in] vector Interrupt vector number to check

Returns: A variable identifying if the requested interrupt vector is enabled.

Return values

true	Specified interrupt vector is currently enabled
false	Specified interrupt vector is currently disabled

Referenced by events_add_hook().

static bool system_interrupt_is_global_enabled ( void )

inlinestatic

Check if global interrupts are enabled.

Checks if global interrupts are currently enabled.

Returns: A boolean that identifies if the global interrupts are enabled or not.

Return values

true	Global interrupts are currently enabled
false	Global interrupts are currently disabled

References cpu_irq_is_enabled.

bool system_interrupt_is_pending ( const enum system_interrupt_vector vector )

Check if a interrupt line is pending.

Checks if the requested interrupt vector is pending.

Parameters

[in] vector Interrupt vector number to check

Returns: A boolean identifying if the requested interrupt vector is pending.

Return values

true	Specified interrupt vector is pending
false	Specified interrupt vector is not pending

References Assert, and SYSTEM_INTERRUPT_SYSTICK.

static void system_interrupt_leave_critical_section ( void )

inlinestatic

Leaves a critical section.

Enables global interrupts. To support nested critical sections, an internal count of the critical section nesting will be kept, so that global interrupts are only re-enabled upon leaving the outermost nested critical section.

References cpu_irq_leave_critical().

Referenced by _events_find_first_free_channel_and_allocate(), _events_release_channel(), _usart_read_buffer(), _usart_write_buffer(), events_trigger(), system_gclk_chan_disable(), system_gclk_chan_enable(), system_gclk_chan_get_hz(), system_gclk_chan_is_enabled(), system_gclk_chan_is_locked(), system_gclk_chan_lock(), system_gclk_gen_disable(), system_gclk_gen_enable(), system_gclk_gen_get_hz(), system_gclk_gen_is_enabled(), system_gclk_gen_set_config(), and usart_lock().

enum status_code system_interrupt_set_pending ( const enum system_interrupt_vector vector )

Set a interrupt vector as pending.

Set the requested interrupt vector as pending (i.e. issues a software interrupt request for the specified vector). The software handler will be handled (if enabled) in a priority order based on vector number and configured priority settings.

Parameters

[in] vector Interrupt vector number which is set as pending

Returns: Status code identifying if the vector was successfully set as pending.

Return values

STATUS_OK	If no error was detected
STATUS_INVALID_ARG	If an unsupported interrupt vector number was given

References Assert, STATUS_ERR_INVALID_ARG, STATUS_OK, SYSTEM_INTERRUPT_NON_MASKABLE, and SYSTEM_INTERRUPT_SYSTICK.

enum status_code system_interrupt_set_priority	(	const enum system_interrupt_vector	vector,
		const enum system_interrupt_priority_level	priority_level
	)

Set interrupt vector priority level.

Set the priority level of an external interrupt or exception.

Parameters

[in]	vector	Interrupt vector to change
[in]	priority_level	New vector priority level to set

Returns: Status code indicating if the priority level of the interrupt was successfully set.

Return values

STATUS_OK	If no error was detected
STATUS_INVALID_ARG	If an unsupported interrupt vector number was given

References Assert, STATUS_ERR_INVALID_ARG, STATUS_OK, and SYSTEM_INTERRUPT_SYSTICK.

Microchip® Advanced Software Framework

Prerequisites

Module Overview

Critical Sections

Software Interrupts

Special Considerations

Extra Information

Examples

API Overview

Enumerations

Critical Section Management

Interrupt Enabling/Disabling

Interrupt State Management

Interrupt Priority Management