1 /******************************************************************************
2 *  Filename:       interrupt_doc.h
3 *  Revised:        2017-11-14 15:26:03 +0100 (Tue, 14 Nov 2017)
4 *  Revision:       50272
5 *
6 *  Copyright (c) 2015 - 2020, Texas Instruments Incorporated
7 *  All rights reserved.
8 *
9 *  Redistribution and use in source and binary forms, with or without
10 *  modification, are permitted provided that the following conditions are met:
11 *
12 *  1) Redistributions of source code must retain the above copyright notice,
13 *     this list of conditions and the following disclaimer.
14 *
15 *  2) Redistributions in binary form must reproduce the above copyright notice,
16 *     this list of conditions and the following disclaimer in the documentation
17 *     and/or other materials provided with the distribution.
18 *
19 *  3) Neither the name of the ORGANIZATION nor the names of its contributors may
20 *     be used to endorse or promote products derived from this software without
21 *     specific prior written permission.
22 *
23 *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
24 *  AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
25 *  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
26 *  ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
27 *  LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
28 *  CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
29 *  SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
30 *  INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
31 *  CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
32 *  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
33 *  POSSIBILITY OF SUCH DAMAGE.
34 *
35 ******************************************************************************/
36 //! \addtogroup interrupt_api
37 //! @{
38 //! \section sec_interrupt Introduction
39 //!
40 //! The interrupt controller API provides a set of functions for dealing with the
41 //! Nested Vectored Interrupt Controller (NVIC). Functions are provided to enable
42 //! and disable interrupts, register interrupt handlers, and set the priority of
43 //! interrupts.
44 //!
45 //! The event sources that trigger the interrupt lines in the NVIC are controlled by
46 //! the MCU event fabric. All event sources are statically connected to the NVIC interrupt lines
47 //! except one which is programmable. For more information about the MCU event fabric, see the
48 //! [MCU event fabric API](\ref event_api).
49 //!
50 //! \section sec_interrupt_api API
51 //!
52 //! Interrupts and system exceptions must be individually enabled and disabled through:
53 //! - \ref IntEnable()
54 //! - \ref IntDisable()
55 //!
56 //! The global CPU interrupt can be enabled and disabled with the following functions:
57 //! - \ref IntMasterEnable()
58 //! - \ref IntMasterDisable()
59 //!
60 //! This does not affect the individual interrupt enable states. Masking of the CPU
61 //! interrupt can be used as a simple critical section (only an NMI can interrupt the
62 //! CPU while the CPU interrupt is disabled), although masking the CPU
63 //! interrupt can increase the interrupt response time.
64 //!
65 //! It is possible to access the NVIC to see if any interrupts are pending and manually
66 //! clear pending interrupts which have not yet been serviced or set a specific interrupt as
67 //! pending to be handled based on its priority. Pending interrupts are cleared automatically
68 //! when the interrupt is accepted and executed. However, the event source which caused the
69 //! interrupt might need to be cleared manually to avoid re-triggering the corresponding interrupt.
70 //! The functions to read, clear, and set pending interrupts are:
71 //! - \ref IntPendGet()
72 //! - \ref IntPendClear()
73 //! - \ref IntPendSet()
74 //!
75 //! The interrupt prioritization in the NVIC allows handling of higher priority interrupts
76 //! before lower priority interrupts, as well as allowing preemption of lower priority interrupt
77 //! handlers by higher priority interrupts.
78 //! The device supports eight priority levels from 0 to 7 with 0 being the highest priority.
79 //! The priority of each interrupt source can be set and examined using:
80 //! - \ref IntPrioritySet()
81 //! - \ref IntPriorityGet()
82 //!
83 //! Interrupts can be masked based on their priority such that interrupts with the same or lower
84 //! priority than the mask are effectively disabled. This can be configured with:
85 //! - \ref IntPriorityMaskSet()
86 //! - \ref IntPriorityMaskGet()
87 //!
88 //! Subprioritization is also possible. Instead of having three bits of preemptable
89 //! prioritization (eight levels), the NVIC can be configured for 3 - M bits of
90 //! preemptable prioritization and M bits of subpriority. In this scheme, two
91 //! interrupts with the same preemptable prioritization but different subpriorities
92 //! do not cause a preemption. Instead, tail chaining is used to process
93 //! the two interrupts back-to-back.
94 //! If two interrupts with the same priority (and subpriority if so configured) are
95 //! asserted at the same time, the one with the lower interrupt number is
96 //! processed first.
97 //! Subprioritization is handled by:
98 //! - \ref IntPriorityGroupingSet()
99 //! - \ref IntPriorityGroupingGet()
100 //!
101 //! \section sec_interrupt_table Interrupt Vector Table
102 //!
103 //! The interrupt vector table can be configured in one of two ways:
104 //! - Statically (at compile time): Vector table is placed in Flash and each entry has a fixed
105 //!   pointer to an interrupt handler (ISR).
106 //! - Dynamically (at runtime): Vector table is placed in SRAM and each entry can be changed
107 //!   (registered or unregistered) at runtime. This allows a single interrupt to trigger different
108 //!   interrupt handlers (ISRs) depending on which interrupt handler is registered at the time the
109 //!   System CPU responds to the interrupt.
110 //!
111 //! When configured, the interrupts must be explicitly enabled in the NVIC through \ref IntEnable()
112 //! before the CPU can respond to the interrupt (in addition to any interrupt enabling required
113 //! within the peripheral).
114 //!
115 //! \subsection sec_interrupt_table_static Static Vector Table
116 //!
117 //! Static registration of interrupt handlers is accomplished by editing the interrupt handler
118 //! table in the startup code of the application. Texas Instruments provides startup files for
119 //! each supported compiler ( \ti_code{startup_<compiler>.c} ) and these startup files include
120 //! a default static interrupt vector table.
121 //! All entries, except ResetISR, are declared as \c extern with weak assignment to a default
122 //! interrupt handler. This allows the user to declare and define a function (in the user's code)
123 //! with the same name as an entry in the vector table. At compile time, the linker then replaces
124 //! the pointer to the default interrupt handler in the vector table with the pointer to the
125 //! interrupt handler defined by the user.
126 //!
127 //! Statically configuring the interrupt table provides the fastest interrupt response time
128 //! because the stacking operation (a write to SRAM on the data bus) is performed in parallel
129 //! with the interrupt handler table fetch (a read from Flash on the instruction bus), as well
130 //! as the prefetch of the interrupt handler (assuming it is also in Flash).
131 //!
132 //! \subsection sec_interrupt_table_dynamic Dynamic Vector Table
133 //!
134 //! Alternatively, interrupts can be registered in the vector table at runtime, thus dynamically.
135 //! The dynamic vector table is placed in SRAM and the code can then modify the pointers to
136 //! interrupt handlers throughout the application.
137 //!
138 //! DriverLib uses these two functions to modify the dynamic vector table:
139 //! - \ref IntRegister() : Write a pointer to an interrupt handler into the vector table.
140 //! - \ref IntUnregister() : Write pointer to default interrupt handler into the vector table.
141 //!
142 //! \note First call to \ref IntRegister() initializes the vector table in SRAM by copying the
143 //! static vector table from Flash and forcing the NVIC to use the dynamic vector table from
144 //! this point forward. If using the dynamic vector table it is highly recommended to
145 //! initialize it during the setup phase of the application. The NVIC uses the static vector
146 //! table in Flash until the application initializes the dynamic vector table in SRAM.
147 //!
148 //! Runtime configuration of interrupts adds a small latency to the interrupt response time
149 //! because the stacking operation (a write to SRAM on the data bus) and the interrupt handler
150 //! fetch from the vector table (a read from SRAM on the instruction bus) must be performed
151 //! sequentially.
152 //!
153 //! The dynamic vector table, \ref g_pfnRAMVectors, is placed in SRAM in the section called
154 //! \c vtable_ram which is a section defined in the linker file. By default the linker file
155 //! places this section at the start of the SRAM but this is configurable by the user.
156 //!
157 //! \warning Runtime configuration of interrupt handlers requires that the interrupt
158 //! handler table is placed on a 256-byte boundary in SRAM (typically, this is
159 //! at the beginning of SRAM). Failure to do so results in an incorrect vector
160 //! address being fetched in response to an interrupt.
161 //!
162 //! @}
163