1 //***************************************************************************** 2 // 3 //! @file am_hal_sysctrl.h 4 //! 5 //! @brief Functions for interfacing with the M4F system control registers 6 //! 7 //! @addtogroup sysctrl3p SYSCTRL - System Control 8 //! @ingroup apollo3p_hal 9 //! @{ 10 // 11 //***************************************************************************** 12 13 //***************************************************************************** 14 // 15 // Copyright (c) 2024, Ambiq Micro, Inc. 16 // All rights reserved. 17 // 18 // Redistribution and use in source and binary forms, with or without 19 // modification, are permitted provided that the following conditions are met: 20 // 21 // 1. Redistributions of source code must retain the above copyright notice, 22 // this list of conditions and the following disclaimer. 23 // 24 // 2. Redistributions in binary form must reproduce the above copyright 25 // notice, this list of conditions and the following disclaimer in the 26 // documentation and/or other materials provided with the distribution. 27 // 28 // 3. Neither the name of the copyright holder nor the names of its 29 // contributors may be used to endorse or promote products derived from this 30 // software without specific prior written permission. 31 // 32 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 33 // AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 34 // IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 35 // ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE 36 // LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 37 // CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 38 // SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 39 // INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 40 // CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 41 // ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 42 // POSSIBILITY OF SUCH DAMAGE. 43 // 44 // This is part of revision release_sdk_3_2_0-dd5f40c14b of the AmbiqSuite Development Package. 45 // 46 //***************************************************************************** 47 #ifndef AM_HAL_SYSCTRL_H 48 #define AM_HAL_SYSCTRL_H 49 50 #ifdef __cplusplus 51 extern "C" 52 { 53 #endif 54 55 56 //***************************************************************************** 57 // 58 //! @brief Option to Enable Deepsleep Minimum Power 59 //! 60 //! This workaround is required to achieve best deepsleep performance with 61 //! Apollo3 Plus. Please note that at 3V operation or higher, with temperatures 62 //! at or below 0C, a small subset of devices will experience increased current 63 //! draw, up to 15uA in deepsleep, with this workaround enabled. 64 //! 65 //! For Apollo3 Plus devices manufactured before 01/28/2021, the 66 //! am3p_patch_ota_FLASHCACHEPGCTRL_CV.bin patch must be installed. Please 67 //! reference the following Knowledgebase Article for more details: 68 //! https://support.ambiq.com/hc/en-us/articles/4410288947213 69 //! 70 //! AM_HAL_SYSCTRL_DEEPSLEEP_WA: 71 //! Default: Undefined 72 // 73 //***************************************************************************** 74 //#define AM_HAL_SYSCTRL_DEEPSLEEP_WA 75 76 //***************************************************************************** 77 // 78 // !Definitions for sleep mode parameter 79 // 80 //***************************************************************************** 81 #define AM_HAL_SYSCTRL_SLEEP_DEEP true 82 #define AM_HAL_SYSCTRL_SLEEP_NORMAL false 83 84 //***************************************************************************** 85 // 86 // !Special registers. 87 // 88 //***************************************************************************** 89 #define PATCHVER2 0x50023828 90 91 //***************************************************************************** 92 // 93 //! Control operations for SysCtrl 94 // 95 //***************************************************************************** 96 typedef enum 97 { 98 AM_HAL_SYSCTRL_CONTROL_DEEPSLEEP_MINPWR_DIS, 99 AM_HAL_SYSCTRL_CONTROL_DEEPSLEEP_MINPWR_EN, 100 } am_hal_sysctrl_control_e; 101 102 //***************************************************************************** 103 // 104 //! Definition of Global Power State enumeration 105 // 106 //***************************************************************************** 107 typedef enum 108 { 109 AM_HAL_SYSCTRL_WAKE, 110 AM_HAL_SYSCTRL_NORMALSLEEP, 111 AM_HAL_SYSCTRL_DEEPSLEEP 112 } am_hal_sysctrl_power_state_e; 113 114 //***************************************************************************** 115 // 116 // !Write flush - This function will hold the bus until all queued write 117 // !operations have completed, thereby guaranteeing that all writes have 118 // !been flushed. 119 // 120 //***************************************************************************** 121 #define SYNC_READ 0x5FFF0000 122 #define am_hal_sysctrl_bus_write_flush() AM_REGVAL(SYNC_READ) 123 124 //****************************************************************************** 125 // 126 // External Globals. 127 // 128 //****************************************************************************** 129 extern uint32_t g_am_hal_sysctrl_sleep_count; 130 131 //***************************************************************************** 132 // 133 // External function definitions 134 // 135 //***************************************************************************** 136 137 //***************************************************************************** 138 //! @brief Apply various specific commands/controls on the SYSCTRL module 139 //! 140 //! @param eControl 141 //! @param pArgs 142 //! @return uint32_t 143 //***************************************************************************** 144 extern uint32_t am_hal_sysctrl_control(am_hal_sysctrl_control_e eControl, void *pArgs); 145 146 //***************************************************************************** 147 // 148 //! @brief Place the core into sleep or deepsleep. 149 //! 150 //! This function puts the MCU to sleep or deepsleep depending on bSleepDeep. 151 //! 152 //! @param bSleepDeep - False for Normal, or True for Deep sleep. 153 //! Valid values for bSleepDeep are: 154 //! - AM_HAL_SYSCTRL_SLEEP_NORMAL 155 //! - AM_HAL_SYSCTRL_SLEEP_DEEP 156 // 157 //***************************************************************************** 158 extern void am_hal_sysctrl_sleep(bool bSleepDeep); 159 160 //***************************************************************************** 161 // 162 //! @brief Enable the floating point module. 163 //! 164 //! Call this function to enable the ARM hardware floating point module. 165 // 166 //***************************************************************************** 167 extern void am_hal_sysctrl_fpu_enable(void); 168 169 //***************************************************************************** 170 // 171 //! @brief Disable the floating point module. 172 //! 173 //! Call this function to disable the ARM hardware floating point module. 174 // 175 //***************************************************************************** 176 extern void am_hal_sysctrl_fpu_disable(void); 177 178 //***************************************************************************** 179 // 180 //! @brief Enable stacking of FPU registers on exception entry. 181 //! 182 //! @param bLazy - Set to "true" to enable "lazy stacking". 183 //! 184 //! This function allows the core to save floating-point information to the 185 //! stack on exception entry. Setting the bLazy option enables "lazy stacking" 186 //! for interrupt handlers. Normally, mixing floating-point code and interrupt 187 //! driven routines causes increased interrupt latency, because the core must 188 //! save extra information to the stack upon exception entry. With the lazy 189 //! stacking option enabled, the core will skip the saving of floating-point 190 //! registers when possible, reducing average interrupt latency. 191 //! 192 //! @note At reset of the Cortex M4, the ASPEN and LSPEN bits are set to 1, 193 //! enabling Lazy mode by default. Therefore this function will generally 194 //! only have an effect when setting for full-context save (or when switching 195 //! from full-context to lazy mode). 196 //! @par 197 //! @note See also: 198 //! infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.dai0298a/DAFGGBJD.html/n 199 //! https://developer.arm.com/documentation/dai0298/a/?lang=en 200 //! @par 201 //! @note Three valid FPU context saving modes are possible. 202 //! 1. Lazy ASPEN=1 LSPEN=1 am_hal_sysctrl_fpu_stacking_enable(true) 203 //! and default. 204 //! 2. Full-context ASPEN=1 LSPEN=0 am_hal_sysctrl_fpu_stacking_enable(false) 205 //! 3. No FPU state ASPEN=0 LSPEN=0 am_hal_sysctrl_fpu_stacking_disable() 206 //! 4. Invalid ASPEN=0 LSPEN=1 207 // 208 //***************************************************************************** 209 extern void am_hal_sysctrl_fpu_stacking_enable(bool bLazy); 210 211 //***************************************************************************** 212 // 213 //! @brief Disable FPU register stacking on exception entry. 214 //! 215 //! This function disables all stacking of floating point registers for 216 //! interrupt handlers. This mode should only be used when it is absolutely 217 //! known that no FPU instructions will be executed in an ISR. 218 // 219 //***************************************************************************** 220 extern void am_hal_sysctrl_fpu_stacking_disable(void); 221 222 //***************************************************************************** 223 // 224 //! @brief Issue a system wide reset using the AIRCR bit in the M4 system ctrl. 225 //! 226 //! This function issues a system wide reset (Apollo POR level reset). 227 // 228 //***************************************************************************** 229 extern void am_hal_sysctrl_aircr_reset(void); 230 #ifdef __cplusplus 231 } 232 #endif 233 234 #endif // AM_HAL_SYSCTRL_H 235 236 //***************************************************************************** 237 // 238 // End Doxygen group. 239 //! @} 240 // 241 //***************************************************************************** 242 243
