Functions to access the Nested Vector Interrupt Controller (NVIC). More...
Macros | |
#define | CMSIS_NVIC_VIRTUAL |
Virtualization of the NVIC API. | |
#define | CMSIS_VECTAB_VIRTUAL |
Virtualization of interrupt vector table access functions. | |
Enumerations | |
enum | IRQn_Type { NonMaskableInt_IRQn = -14 , HardFault_IRQn = -13 , MemoryManagement_IRQn = -12 , BusFault_IRQn = -11 , UsageFault_IRQn = -10 , SecureFault_IRQn = -9 , SVCall_IRQn = -5 , DebugMonitor_IRQn = -4 , PendSV_IRQn = -2 , SysTick_IRQn = -1 , WWDG_STM_IRQn = 0 , PVD_STM_IRQn = 1 } |
Definition of IRQn numbers. More... | |
Functions | |
void | NVIC_ClearPendingIRQ (IRQn_Type IRQn) |
Clear a device specific interrupt from pending. | |
uint32_t | NVIC_ClearTargetState (IRQn_Type IRQn) |
Clear Interrupt Target State. | |
void | NVIC_DecodePriority (uint32_t Priority, uint32_t PriorityGroup, uint32_t *pPreemptPriority, uint32_t *pSubPriority) |
Decode the interrupt priority [not for Cortex-M0, Cortex-M0+, or SC000]. | |
void | NVIC_DisableIRQ (IRQn_Type IRQn) |
Disable a device specific interrupt. | |
void | NVIC_EnableIRQ (IRQn_Type IRQn) |
Enable a device specific interrupt. | |
uint32_t | NVIC_EncodePriority (uint32_t PriorityGroup, uint32_t PreemptPriority, uint32_t SubPriority) |
Encodes Priority [not for Cortex-M0, Cortex-M0+, or SC000]. | |
uint32_t | NVIC_GetActive (IRQn_Type IRQn) |
Get the device specific interrupt active status [not for Cortex-M0, Cortex-M0+, or SC000]. | |
uint32_t | NVIC_GetEnableIRQ (IRQn_Type IRQn) |
Get a device specific interrupt enable status. | |
uint32_t | NVIC_GetPendingIRQ (IRQn_Type IRQn) |
Get the pending device specific interrupt. | |
uint32_t | NVIC_GetPriority (IRQn_Type IRQn) |
Get the priority of an interrupt. | |
uint32_t | NVIC_GetPriorityGrouping (void) |
Read the priority grouping [not for Cortex-M0, Cortex-M0+, or SC000]. | |
uint32_t | NVIC_GetTargetState (IRQn_Type IRQn) |
Get Interrupt Target State. | |
uint32_t | NVIC_GetVector (IRQn_Type IRQn) |
Read Interrupt Vector [not for Cortex-M0, SC000]. | |
void | NVIC_SetPendingIRQ (IRQn_Type IRQn) |
Set a device specific interrupt to pending. | |
void | NVIC_SetPriority (IRQn_Type IRQn, uint32_t priority) |
Set the priority for an interrupt. | |
void | NVIC_SetPriorityGrouping (uint32_t PriorityGroup) |
Set priority grouping [not for Cortex-M0, Cortex-M0+, or SC000]. | |
uint32_t | NVIC_SetTargetState (IRQn_Type IRQn) |
Set Interrupt Target State. | |
void | NVIC_SetVector (IRQn_Type IRQn, uint32_t vector) |
Modify Interrupt Vector [not for Cortex-M0, SC000]. | |
void | NVIC_SystemReset (void) |
Reset the system. | |
Functions to access the Nested Vector Interrupt Controller (NVIC).
This section explains how to use interrupts and exceptions and access functions for the Nested Vector Interrupt Controller (NVIC).
Arm provides a template file startup_device for each supported compiler. The file must be adapted by the silicon vendor to include interrupt vectors for all device-specific interrupt handlers. Each interrupt handler is defined as a weak function to an dummy handler. These interrupt handlers can be used directly in application software without being adapted by the programmer.
The table below lists the core exception vectors of the various Cortex-M processors.
Exception Vector | Handler Function | IRQn Value | Armv6-M | Armv7-M | Armv8-M Baseline | Armv8-M Mainline | Armv8.1-M Mainline | Description |
---|---|---|---|---|---|---|---|---|
NonMaskableInt_IRQn | NMI_Handler | -14 | Non Maskable Interrupt | |||||
HardFault_IRQn | HardFault_Handler | -13 | Hard Fault Interrupt | |||||
MemoryManagement_IRQn | MemManage_Handler | -12 | Memory Management Interrupt | |||||
BusFault_IRQn | BusFault_Handler | -11 | Bus Fault Interrupt | |||||
UsageFault_IRQn | UsageFault_Handler | -10 | Usage Fault Interrupt | |||||
SecureFault_IRQn | SecureFault_Handler | -9 | Secure Fault Interrupt | |||||
SVCall_IRQn | SVC_Handler | -5 | SVC Interrupt | |||||
DebugMonitor_IRQn | DebugMon_Handler | -4 | Debug Monitor Interrupt | |||||
PendSV_IRQn | PendSV_Handler | -2 | Pend SV Interrupt | |||||
SysTick_IRQn | SysTick_Handler | -1 | System Tick Interrupt |
The Vector Table defines the entry addresses of the processor exceptions and the device specific interrupts. It is typically located at the beginning of the program memory, however Using Interrupt Vector Remap it can be relocated to RAM. The symbol __Vectors is the address of the vector table in the startup code and the register SCB->VTOR holds the start address of the vector table.
An Armv8-M implementation with TrustZone provides two vector tables:
Refer to Programmers Model with TrustZone for more information.
At the beginning of the vector table, the initial stack value and the exception vectors of the processor are defined. The vector table below shows the exception vectors of a Armv8-M Mainline processor. Other processor variants may have fewer vectors.
Following the processor exception vectors, the vector table contains also the device specific interrupt vectors.
All device specific interrupts should have a default interrupt handler function that can be overwritten in user code. Below is an example for this default handler function.
The user application may simply define an interrupt handler function by using the handler name as shown below.
The code below shows the usage of various CMSIS NVIC functions with an LPC1700 device.
The CMSIS-Core has provisions for overriding NVIC APIs as required for implementing secure systems that control access to peripherals and related interrupts. These overrides allow an operating system to control the access privileges of application code to critical interrupts.
The NVIC function virtualization is enabled with the following #define symbols:
#define CMSIS_NVIC_VIRTUAL |
Virtualization of the NVIC API.
When CMSIS_NVIC_VIRTUAL is defined, the NVIC access functions in the table below must be implemented for virtualizing NVIC access. These functions should be implemented in a separate source module. The original CMSIS-Core __NVIC functions are always available independent of CMSIS_NVIC_VIRTUAL.
NVIC Access Functions | CMSIS-Core Functions |
---|---|
NVIC_EnableIRQ | __NVIC_EnableIRQ |
NVIC_GetEnableIRQ | __NVIC_GetEnableIRQ |
NVIC_DisableIRQ | __NVIC_DisableIRQ |
NVIC_GetPendingIRQ | __NVIC_GetPendingIRQ |
NVIC_SetPendingIRQ | __NVIC_SetPendingIRQ |
NVIC_ClearPendingIRQ | __NVIC_ClearPendingIRQ |
NVIC_GetActive | __NVIC_GetActive |
NVIC_SetPriority | __NVIC_SetPriority |
NVIC_GetPriority | __NVIC_GetPriority |
NVIC_SetPriorityGrouping | __NVIC_SetPriorityGrouping |
NVIC_GetPriorityGrouping | __NVIC_GetPriorityGrouping |
#define CMSIS_VECTAB_VIRTUAL |
Virtualization of interrupt vector table access functions.
When CMSIS_NVIC_VIRTUAL is defined, the functions in the table below must be replaced to virtualize the API access functions to the interrupt vector table. The NVIC vector table API should be implemented in a separate source module. This allows, for example, alternate implementations to relocate the vector table from flash to RAM on the first vector table update.
The original CMSIS-Core functions are always available, but prefixed with __NVIC.
Interrupt Vector Table Access | CMSIS-Core Functions |
---|---|
NVIC_GetVector | __NVIC_GetVector |
NVIC_SetVector | __NVIC_SetVector |
enum IRQn_Type |
Definition of IRQn numbers.
The core exception enumeration names for IRQn values are defined in the Device Header File <Device.h>.
The table below describes the core exception names and their availability in various Cortex-M cores.
void NVIC_ClearPendingIRQ | ( | IRQn_Type | IRQn | ) |
Clear a device specific interrupt from pending.
This function removes the pending state of the specified device specific interrupt IRQn. IRQn cannot be a negative number.
[in] | IRQn | Interrupt number |
uint32_t NVIC_ClearTargetState | ( | IRQn_Type | IRQn | ) |
Clear Interrupt Target State.
Clears the interrupt target field in the non-secure NVIC when in secure state.
[in] | IRQn | External interrupt number. Value cannot be negative. |
void NVIC_DecodePriority | ( | uint32_t | Priority, |
uint32_t | PriorityGroup, | ||
uint32_t * | pPreemptPriority, | ||
uint32_t * | pSubPriority | ||
) |
Decode the interrupt priority [not for Cortex-M0, Cortex-M0+, or SC000].
This function decodes an interrupt priority value with the priority group PriorityGroup to preemptive priority value pPreemptPriority and subpriority value pSubPriority. In case of a conflict between priority grouping and available priority bits (__NVIC_PRIO_BITS) the smallest possible priority group is set.
[in] | Priority | Priority |
[in] | PriorityGroup | Priority group |
[out] | *pPreemptPriority | Preemptive priority value (starting from 0) |
[out] | *pSubPriority | Subpriority value (starting from 0) |
void NVIC_DisableIRQ | ( | IRQn_Type | IRQn | ) |
Disable a device specific interrupt.
This function disables the specified device specific interrupt IRQn. IRQn cannot be a negative value.
[in] | IRQn | Number of the external interrupt to disable |
void NVIC_EnableIRQ | ( | IRQn_Type | IRQn | ) |
Enable a device specific interrupt.
This function enables the specified device specific interrupt IRQn. IRQn cannot be a negative value.
[in] | IRQn | Interrupt number |
uint32_t NVIC_EncodePriority | ( | uint32_t | PriorityGroup, |
uint32_t | PreemptPriority, | ||
uint32_t | SubPriority | ||
) |
Encodes Priority [not for Cortex-M0, Cortex-M0+, or SC000].
This function encodes the priority for an interrupt with the priority group PriorityGroup, preemptive priority value PreemptPriority, and subpriority value SubPriority. In case of a conflict between priority grouping and available priority bits (__NVIC_PRIO_BITS) the smallest possible priority group is set.
[in] | PriorityGroup | Priority group |
[in] | PreemptPriority | Preemptive priority value (starting from 0) |
[in] | SubPriority | Subpriority value (starting from 0) |
uint32_t NVIC_GetActive | ( | IRQn_Type | IRQn | ) |
Get the device specific interrupt active status [not for Cortex-M0, Cortex-M0+, or SC000].
This function reads the Interrupt Active Register (NVIC_IABR0-NVIC_IABR7) in NVIC and returns the active bit of the interrupt IRQn.
[in] | IRQn | Interrupt number |
uint32_t NVIC_GetEnableIRQ | ( | IRQn_Type | IRQn | ) |
Get a device specific interrupt enable status.
This function returns the interrupt enable status for the specified device specific interrupt IRQn. IRQn cannot be a negative value.
[in] | IRQn | Interrupt number |
uint32_t NVIC_GetPendingIRQ | ( | IRQn_Type | IRQn | ) |
Get the pending device specific interrupt.
This function returns the pending status of the specified device specific interrupt IRQn.
[in] | IRQn | Interrupt number |
uint32_t NVIC_GetPriority | ( | IRQn_Type | IRQn | ) |
Get the priority of an interrupt.
This function reads the priority for the specified interrupt IRQn. IRQn can can specify any device specific interrupt, or processor exception.
The returned priority value is automatically aligned to the implemented priority bits of the microcontroller.
[in] | IRQn | Interrupt number |
uint32_t NVIC_GetPriorityGrouping | ( | void | ) |
Read the priority grouping [not for Cortex-M0, Cortex-M0+, or SC000].
This function returns the priority grouping (flag PRIGROUP in AIRCR[10:8]).
uint32_t NVIC_GetTargetState | ( | IRQn_Type | IRQn | ) |
Get Interrupt Target State.
Reads the interrupt target field from the non-secure NVIC when in secure state.
[in] | IRQn | External interrupt number. Value cannot be negative. |
uint32_t NVIC_GetVector | ( | IRQn_Type | IRQn | ) |
Read Interrupt Vector [not for Cortex-M0, SC000].
This function allows to read the address of an interrupt handler function.
[in] | IRQn | Interrupt number |
void NVIC_SetPendingIRQ | ( | IRQn_Type | IRQn | ) |
Set a device specific interrupt to pending.
This function sets the pending bit for the specified device specific interrupt IRQn. IRQn cannot be a negative value.
[in] | IRQn | Interrupt number |
void NVIC_SetPriority | ( | IRQn_Type | IRQn, |
uint32_t | priority | ||
) |
Set the priority for an interrupt.
Sets the priority for the interrupt specified by IRQn.IRQn can can specify any device specific interrupt, or processor exception. The priority specifies the interrupt priority value, whereby lower values indicate a higher priority. The default priority is 0 for every interrupt. This is the highest possible priority.
The priority cannot be set for every core interrupt. HardFault and NMI have a fixed (negative) priority that is higher than any configurable exception or interrupt.
[in] | IRQn | Interrupt Number |
[in] | priority | Priority to set |
void NVIC_SetPriorityGrouping | ( | uint32_t | PriorityGroup | ) |
Set priority grouping [not for Cortex-M0, Cortex-M0+, or SC000].
The function sets the priority grouping PriorityGroup using the required unlock sequence. PriorityGroup is assigned to the field PRIGROUP (register AIRCR[10:8]). This field determines the split of group priority from subpriority. Only values from 0..7 are used. In case of a conflict between priority grouping and available priority bits (__NVIC_PRIO_BITS), the smallest possible priority group is set.
[in] | PriorityGroup | Priority group |
uint32_t NVIC_SetTargetState | ( | IRQn_Type | IRQn | ) |
Set Interrupt Target State.
Sets the interrupt target field in the non-secure NVIC when in secure state.
[in] | IRQn | External interrupt number. Value cannot be negative. |
void NVIC_SetVector | ( | IRQn_Type | IRQn, |
uint32_t | vector | ||
) |
Modify Interrupt Vector [not for Cortex-M0, SC000].
This function allows to change the address of an interrupt handler function.
[in] | IRQn | Interrupt number |
[in] | vector | Address of new interrupt handler function |
void NVIC_SystemReset | ( | void | ) |
Reset the system.
This function requests a system reset by setting the SYSRESETREQ flag in the AIRCR register.