1 //***************************************************************************** 2 // 3 //! @file am_hal_reset.h 4 //! 5 //! @brief Hardware abstraction layer for the Reset Generator module. 6 //! 7 //! @addtogroup rstgen3p Reset - Reset Generator (RSTGEN) 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_RSTGEN_H 48 #define AM_HAL_RSTGEN_H 49 50 #ifdef __cplusplus 51 extern "C" 52 { 53 #endif 54 55 //***************************************************************************** 56 // 57 // RESET specific definitions. 58 // 59 //***************************************************************************** 60 //************************************** 61 //! Reset Generator configuration values 62 //************************************** 63 typedef enum 64 { 65 AM_HAL_RESET_BROWNOUT_HIGH_ENABLE, 66 AM_HAL_RESET_WDT_RESET_ENABLE, 67 AM_HAL_RESET_BROWNOUT_HIGH_DISABLE, 68 AM_HAL_RESET_WDT_RESET_DISABLE 69 } am_hal_reset_configure_e; 70 71 //************************************** 72 //! Reset Generator control operations 73 //************************************** 74 typedef enum 75 { 76 AM_HAL_RESET_CONTROL_SWPOR, 77 AM_HAL_RESET_CONTROL_SWPOI, 78 AM_HAL_RESET_CONTROL_STATUSCLEAR, 79 AM_HAL_RESET_CONTROL_TPIU_RESET 80 } am_hal_reset_control_e; 81 82 //************************************** 83 //! Reset Generator status bits 84 //************************************** 85 typedef enum 86 { 87 AM_HAL_RESET_STATUS_EXTERNAL = RSTGEN_STAT_EXRSTAT_Msk, 88 AM_HAL_RESET_STATUS_POR = RSTGEN_STAT_PORSTAT_Msk, 89 AM_HAL_RESET_STATUS_BOD = RSTGEN_STAT_BORSTAT_Msk, 90 AM_HAL_RESET_STATUS_SWPOR = RSTGEN_STAT_SWRSTAT_Msk, 91 AM_HAL_RESET_STATUS_SWPOI = RSTGEN_STAT_POIRSTAT_Msk, 92 AM_HAL_RESET_STATUS_DEBUGGER = RSTGEN_STAT_DBGRSTAT_Msk, 93 AM_HAL_RESET_STATUS_WDT = RSTGEN_STAT_WDRSTAT_Msk, 94 AM_HAL_RESET_STATUS_BOUNREG = RSTGEN_STAT_BOUSTAT_Msk, 95 AM_HAL_RESET_STATUS_BOCORE = RSTGEN_STAT_BOCSTAT_Msk, 96 AM_HAL_RESET_STATUS_BOMEM = RSTGEN_STAT_BOFSTAT_Msk, 97 AM_HAL_RESET_STATUS_BOBLE = RSTGEN_STAT_BOBSTAT_Msk 98 } am_hal_reset_status_e; 99 100 //************************************** 101 //! RESET status structure 102 //************************************** 103 typedef struct 104 { 105 am_hal_reset_status_e 106 eStatus; // Return all status bits from RSTGEN.STAT 107 bool bEXTStat; // External reset 108 bool bPORStat; // Power-On reset 109 bool bBODStat; // Brown-Out reset 110 bool bSWPORStat; // SW Power-On reset or AIRCR reset 111 bool bSWPOIStat; // SW Power On Initialization reset 112 bool bDBGRStat; // Debugger reset 113 bool bWDTStat; // Watch Dog Timer reset 114 bool bBOUnregStat; // Unregulated Supply Brownout event 115 bool bBOCOREStat; // Core Regulator Brownout event 116 bool bBOMEMStat; // Memory Regulator Brownout event 117 bool bBOBLEStat; // BLE/Burst Regulator Brownout event 118 } am_hal_reset_status_t; 119 120 // 121 //! Define interrupt bit(s) 122 // 123 #define AM_HAL_RESET_INTERRUPT_BODH RSTGEN_INTEN_BODH_Msk 124 125 //! Global variable used to capture the reset status 126 extern uint32_t gAmHalResetStatus; 127 128 //***************************************************************************** 129 // 130 //! @brief Enable and configure the Reset controller. 131 //! 132 //! @details This function will configure the specified reset conditions. 133 //! 134 //! @param eConfigure - One of configuration enumerations. 135 //! - AM_HAL_RESET_BROWNOUT_HIGH_ENABLE 136 //! - AM_HAL_RESET_WDT_RESET_ENABLE 137 //! - AM_HAL_RESET_BROWNOUT_HIGH_DISABLE 138 //! - AM_HAL_RESET_WDT_RESET_DISABLE 139 //! 140 //! @return status - generic or interface specific status. 141 // 142 //***************************************************************************** 143 extern uint32_t am_hal_reset_configure(am_hal_reset_configure_e eConfigure); 144 145 //***************************************************************************** 146 // 147 //! @brief Reset generator functions. 148 //! 149 //! @details This function will perform various reset functions including assertion 150 //! of software resets. 151 //! 152 //! @param eControl - One of the control enumerations. 153 //! - AM_HAL_RESET_CONTROL_SWPOR\n 154 //! - power on reset, which results in a reset of 155 //! all blocks except for registers in clock gen, RTC, stimer, PMU. 156 //! - Equivalent to the reset state obtained by a hardware reset, use of 157 //! the ARM AIRCR (Application Interrupt and Reset Control Register) 158 //! core register, debugger reset, watchdog timer expiration, or 159 //! brown-out event. 160 //! - AM_HAL_RESET_CONTROL_SWPOI 161 //! - Power on initialization, which results in a 162 //! reset of all blocks except for registers in clock gen, RTC, stimer. 163 //! - The POI reset level is required in order to enable configuration 164 //! changes such as memory protection. 165 //! - AM_HAL_RESET_CONTROL_STATUSCLEAR 166 //! - Clear the entire STATUS register. 167 //! - All reset status register bits are cleared. 168 //! - AM_HAL_RESET_CONTROL_TPIU 169 //! - Reset the TPIU. 170 //! @param pArgs - pArgs 171 //! 172 //! @return status - generic or interface specific status. 173 //! 174 //! @note When resetting the chip (SWPOR or SWPOI), the function will obviously 175 //! not return to the caller. 176 // 177 //***************************************************************************** 178 extern uint32_t am_hal_reset_control(am_hal_reset_control_e eControl, 179 void *pArgs); 180 181 //***************************************************************************** 182 // 183 //! @brief Return status of the reset generator. 184 //! 185 //! This function will get the status bits from the reset generator.\n 186 //! The status value shows the type of reset(s) that have occurred since power 187 //! on 188 //! 189 //! @note Application MUST call this API at least once before going to deepsleep 190 //! Otherwise this API will not provide correct reset status 191 //! 192 //! @param psStatus 193 //! Pointer to a data structure to receive the status 194 //! information.\n 195 //! Most members of the structure are booleans that receive 196 //! the status of a particular bit. 197 //! 198 //! The eStatus member, however, returns a bitmask of one or more of the 199 //! following values: 200 //! - AM_HAL_RESET_STATUS_EXTERNAL 201 //! - AM_HAL_RESET_STATUS_POR 202 //! - AM_HAL_RESET_STATUS_BOD 203 //! - AM_HAL_RESET_STATUS_SWPOR 204 //! - AM_HAL_RESET_STATUS_SWPOI 205 //! - AM_HAL_RESET_STATUS_DEBUGGER 206 //! - AM_HAL_RESET_STATUS_WDT 207 //! - AM_HAL_RESET_STATUS_BOUNREG 208 //! - AM_HAL_RESET_STATUS_BOCORE 209 //! - AM_HAL_RESET_STATUS_BOMEM 210 //! - AM_HAL_RESET_STATUS_BOBLE 211 //! 212 //! @return Status.\n 213 //! If the API was never called before a valid reset status 214 //! could be captured, AM_HAL_STATUS_FAIL is returned.\n 215 //! Otherwise AM_HAL_STATUS_SUCCESS implies valid reset status returned 216 // 217 //***************************************************************************** 218 extern uint32_t am_hal_reset_status_get(am_hal_reset_status_t *psStatus); 219 220 //***************************************************************************** 221 // 222 //! @brief Static reset of the TPIU. 223 //! 224 //! Use this function to reset the TPIU. 225 //! 226 //! @return status - generic or interface specific status. 227 // 228 //***************************************************************************** 229 extern uint32_t am_hal_reset_tpiu_reset(void); 230 231 //***************************************************************************** 232 // 233 //! @brief Enable selected RSTGEN Interrupts. 234 //! 235 //! Use this function to enable the interrupts. 236 //! 237 //! @param ui32IntMask - One or more of the following bits, any of which can 238 //! be ORed together. 239 //! - AM_HAL_RESET_INTERRUPT_BODH 240 //! 241 //! @return status - generic or interface specific status. 242 // 243 //***************************************************************************** 244 extern uint32_t am_hal_reset_interrupt_enable(uint32_t ui32IntMask); 245 246 //***************************************************************************** 247 // 248 //! @brief Disable selected RSTGEN Interrupts. 249 //! 250 //! Use this function to disable the RSTGEN interrupts. 251 //! 252 //! @param ui32IntMask One or more of the following bits, any of which can 253 //! be ORed together. 254 //! - AM_HAL_RESET_INTERRUPT_BODH 255 //! 256 //! @return status - generic or interface specific status. 257 // 258 //***************************************************************************** 259 extern uint32_t am_hal_reset_interrupt_disable(uint32_t ui32IntMask); 260 261 //***************************************************************************** 262 // 263 //! @brief Reset generator interrupt clear 264 //! 265 //! This function clears the reset generator interrupts. 266 //! 267 //! @param ui32IntMask Interrupt mask 268 //! One or more of the following bits, any of which can 269 //! be ORed together. 270 //! - AM_HAL_RESET_INTERRUPT_BODH 271 //! 272 //! @return status - generic or interface specific status. 273 // 274 //***************************************************************************** 275 extern uint32_t am_hal_reset_interrupt_clear(uint32_t ui32IntMask); 276 277 //***************************************************************************** 278 // 279 //! @brief Get interrupt status of reset generator. 280 //! 281 //! This function returns the interrupt status for the reset generator. 282 //! 283 //! @param bEnabledOnly only return the enabled interrupts 284 //! @param pui32IntStatus ptr to uint32_t to return the interrupt status. 285 //! 286 //! The following are valid status bits. 287 //! - AM_HAL_RESET_INTERRUPT_BODH 288 //! 289 //! @return status - generic or interface specific status. 290 // 291 //***************************************************************************** 292 extern uint32_t am_hal_reset_interrupt_status_get(bool bEnabledOnly, 293 uint32_t *pui32IntStatus); 294 295 296 297 #ifdef __cplusplus 298 } 299 #endif 300 301 #endif // AM_HAL_RSTGEN_H 302 303 //***************************************************************************** 304 // 305 // End Doxygen group. 306 //! @} 307 // 308 //***************************************************************************** 309
