Microchip® Advanced Software Framework

 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
SAM System Interrupt (SYSTEM INTERRUPT) Driver

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:

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

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.

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]vectorInterrupt vector number to clear
Returns
A status code identifying if the interrupt pending state was successfully cleared.
Return values
STATUS_OKIf no error was detected
STATUS_INVALID_ARGIf 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]vectorInterrupt 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]vectorInterrupt 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]vectorInterrupt 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]vectorInterrupt vector number to check
Returns
A variable identifying if the requested interrupt vector is enabled.
Return values
trueSpecified interrupt vector is currently enabled
falseSpecified 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
trueGlobal interrupts are currently enabled
falseGlobal 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]vectorInterrupt vector number to check
Returns
A boolean identifying if the requested interrupt vector is pending.
Return values
trueSpecified interrupt vector is pending
falseSpecified 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]vectorInterrupt vector number which is set as pending
Returns
Status code identifying if the vector was successfully set as pending.
Return values
STATUS_OKIf no error was detected
STATUS_INVALID_ARGIf 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]vectorInterrupt vector to change
[in]priority_levelNew vector priority level to set
Returns
Status code indicating if the priority level of the interrupt was successfully set.
Return values
STATUS_OKIf no error was detected
STATUS_INVALID_ARGIf an unsupported interrupt vector number was given

References Assert, STATUS_ERR_INVALID_ARG, STATUS_OK, and SYSTEM_INTERRUPT_SYSTICK.