1 //***************************************************************************** 2 // 3 //! @file am_hal_mcu_interrupt.h 4 //! 5 //! @brief Helper functions supporting interrupts and NVIC operation. 6 //! 7 //! These functions may be used for NVIC-level interrupt configuration. 8 //! 9 //! @addtogroup mcu_interrupt_4p Interrupt - ARM NVIC support functions 10 //! @ingroup apollo4p_hal 11 //! @{ 12 // 13 //***************************************************************************** 14 15 //***************************************************************************** 16 // 17 // Copyright (c) 2023, Ambiq Micro, Inc. 18 // All rights reserved. 19 // 20 // Redistribution and use in source and binary forms, with or without 21 // modification, are permitted provided that the following conditions are met: 22 // 23 // 1. Redistributions of source code must retain the above copyright notice, 24 // this list of conditions and the following disclaimer. 25 // 26 // 2. Redistributions in binary form must reproduce the above copyright 27 // notice, this list of conditions and the following disclaimer in the 28 // documentation and/or other materials provided with the distribution. 29 // 30 // 3. Neither the name of the copyright holder nor the names of its 31 // contributors may be used to endorse or promote products derived from this 32 // software without specific prior written permission. 33 // 34 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 35 // AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 36 // IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 37 // ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE 38 // LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 39 // CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 40 // SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 41 // INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 42 // CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 43 // ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 44 // POSSIBILITY OF SUCH DAMAGE. 45 // 46 // This is part of revision release_sdk_4_4_0-3c5977e664 of the AmbiqSuite Development Package. 47 // 48 //***************************************************************************** 49 #ifndef AM_HAL_MCU_INTERRUPT_H 50 #define AM_HAL_MCU_INTERRUPT_H 51 52 #ifdef __cplusplus 53 extern "C" 54 { 55 #endif 56 57 // 58 //! Define the last peripheral interrupt as AM_HAL_INTERRUPT_MAX. 59 //! The total number of interrupts in the vector table is therefore 60 //! (AM_HAL_INTERRUPT_MAX + 1 + 16). 61 // 62 #define AM_HAL_INTERRUPT_MAX (MAX_IRQn - 1) 63 64 // 65 //! For Apollo4 RevB, a workaround requires masking all interrupts. 66 //! This is accomplished by setting a priority of 0, but assumes 67 //! any other IRQs have a lower priority (>0). 68 //! This will assign a default priority for IRQs. 69 // 70 #define AM_IRQ_PRIORITY_DEFAULT 4 71 72 //***************************************************************************** 73 // 74 //! @brief Globally disable interrupt service routines 75 //! 76 //! This function prevents interrupt signals from the NVIC from triggering ISR 77 //! entry in the CPU. This will effectively stop incoming interrupt sources 78 //! from triggering their corresponding ISRs. 79 //! 80 //! @note Any external interrupt signal that occurs while the master interrupt 81 //! disable is active will still reach the "pending" state in the NVIC, but it 82 //! will not be allowed to reach the "active" state or trigger the 83 //! corresponding ISR. Instead, these interrupts are essentially "queued" until 84 //! the next time the master interrupt enable instruction is executed. At that 85 //! time, the interrupt handlers will be executed in order of decreasing 86 //! priority. 87 //! 88 //! @return 1 if interrupts were previously disabled, 0 otherwise. 89 // 90 //***************************************************************************** 91 extern uint32_t am_hal_interrupt_master_disable(void); 92 93 //***************************************************************************** 94 // 95 //! @brief Globally enable interrupt service routines 96 //! 97 //! This function allows interrupt signals from the NVIC to trigger ISR entry 98 //! in the CPU. This function must be called if interrupts are to be serviced 99 //! in software. 100 //! 101 //! @return 1 if interrupts were previously disabled, 0 otherwise. 102 // 103 //***************************************************************************** 104 extern uint32_t am_hal_interrupt_master_enable(void); 105 106 //***************************************************************************** 107 // 108 //! @brief Sets the master interrupt state based on the input. 109 //! 110 //! @param ui32Level - Desired PRIMASK value. 111 //! 112 //! This function directly writes the PRIMASK register in the ARM core. A value 113 //! of 1 will disable interrupts, while a value of zero will enable them. 114 //! 115 //! @note This function may be used along with am_hal_interrupt_master_disable() to 116 //! implement a nesting critical section. To do this, call 117 //! am_hal_interrupt_master_disable() to start the critical section, and save 118 //! its ret value. To complete the critical section, call 119 //! am_hal_interrupt_master_set() using the saved return value as \e 120 //! ui32Level. This will safely restore PRIMASK to the value it 121 //! contained just before the start of the critical section. 122 // 123 // 124 //***************************************************************************** 125 extern void am_hal_interrupt_master_set(uint32_t ui32Level); 126 127 #ifdef __cplusplus 128 } 129 #endif 130 131 #endif // AM_HAL_MCU_INTERRUPT_H 132 133 //***************************************************************************** 134 // 135 // End Doxygen group. 136 //! @} 137 // 138 //***************************************************************************** 139 140
