1 //***************************************************************************** 2 // 3 //! @file am_hal_pwrctrl.h 4 //! 5 //! @brief Functions for enabling and disabling power domains. 6 //! 7 //! @addtogroup pwrctrl3p Pwrctrl - Power 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 48 #ifndef AM_HAL_PWRCTRL_H 49 #define AM_HAL_PWRCTRL_H 50 51 // 52 //! Designate this peripheral. 53 // 54 #define AM_APOLLO3_PWRCTRL 1 55 56 // 57 //! Peripheral Type 58 // 59 typedef enum 60 { 61 AM_HAL_PWRCTRL_PERIPH_NONE, 62 AM_HAL_PWRCTRL_PERIPH_IOS, 63 AM_HAL_PWRCTRL_PERIPH_IOM0, 64 AM_HAL_PWRCTRL_PERIPH_IOM1, 65 AM_HAL_PWRCTRL_PERIPH_IOM2, 66 AM_HAL_PWRCTRL_PERIPH_IOM3, 67 AM_HAL_PWRCTRL_PERIPH_IOM4, 68 AM_HAL_PWRCTRL_PERIPH_IOM5, 69 AM_HAL_PWRCTRL_PERIPH_UART0, 70 AM_HAL_PWRCTRL_PERIPH_UART1, 71 AM_HAL_PWRCTRL_PERIPH_ADC, 72 AM_HAL_PWRCTRL_PERIPH_SCARD, 73 AM_HAL_PWRCTRL_PERIPH_MSPI0, 74 AM_HAL_PWRCTRL_PERIPH_MSPI1, 75 AM_HAL_PWRCTRL_PERIPH_MSPI2, 76 AM_HAL_PWRCTRL_PERIPH_PDM, 77 AM_HAL_PWRCTRL_PERIPH_BLEL, 78 AM_HAL_PWRCTRL_PERIPH_MAX 79 } am_hal_pwrctrl_periph_e; 80 81 // 82 //! Momory Type 83 // 84 typedef enum 85 { 86 AM_HAL_PWRCTRL_MEM_NONE, 87 AM_HAL_PWRCTRL_MEM_SRAM_8K_DTCM, 88 AM_HAL_PWRCTRL_MEM_SRAM_32K_DTCM, 89 AM_HAL_PWRCTRL_MEM_SRAM_64K_DTCM, 90 AM_HAL_PWRCTRL_MEM_SRAM_128K, 91 AM_HAL_PWRCTRL_MEM_SRAM_192K, 92 AM_HAL_PWRCTRL_MEM_SRAM_256K, 93 AM_HAL_PWRCTRL_MEM_SRAM_320K, 94 AM_HAL_PWRCTRL_MEM_SRAM_384K, 95 AM_HAL_PWRCTRL_MEM_SRAM_448K, 96 AM_HAL_PWRCTRL_MEM_SRAM_512K, 97 AM_HAL_PWRCTRL_MEM_SRAM_576K, 98 AM_HAL_PWRCTRL_MEM_SRAM_672K, 99 AM_HAL_PWRCTRL_MEM_SRAM_768K, 100 AM_HAL_PWRCTRL_MEM_FLASH_1M, 101 AM_HAL_PWRCTRL_MEM_FLASH_2M, 102 AM_HAL_PWRCTRL_MEM_CACHE, 103 AM_HAL_PWRCTRL_MEM_ALL, 104 AM_HAL_PWRCTRL_MEM_MAX 105 } am_hal_pwrctrl_mem_e; 106 107 #define AM_HAL_PWRCTRL_MEM_FLASH_MIN AM_HAL_PWRCTRL_MEM_FLASH_1M 108 #define AM_HAL_PWRCTRL_MEM_FLASH_MAX AM_HAL_PWRCTRL_MEM_FLASH_2M 109 110 #define AM_HAL_PWRCTRL_MEM_SRAM_MIN AM_HAL_PWRCTRL_MEM_SRAM_8K_DTCM 111 #define AM_HAL_PWRCTRL_MEM_SRAM_MAX AM_HAL_PWRCTRL_MEM_SRAM_768K 112 113 //***************************************************************************** 114 // 115 //! @name Macros to check whether Apollo3 bucks are enabled. 116 //! 117 //! @{ 118 // 119 //***************************************************************************** 120 #define am_hal_pwrctrl_simobuck_enabled_check() \ 121 (PWRCTRL->SUPPLYSTATUS_b.SIMOBUCKON) 122 123 #define am_hal_pwrctrl_blebuck_enabled_check() \ 124 (PWRCTRL->SUPPLYSTATUS_b.BLEBUCKON) 125 126 // 127 //! @} 128 // 129 130 //***************************************************************************** 131 // 132 //! @brief Option to Enable vddf Boost workaound for APB Hang issue 133 //! 134 //! APB bus will hang with 135 //! 136 //! AM_HAL_PWRCTRL_VDDF_BOOST_WA: 137 //! Default: Defined 138 // 139 //***************************************************************************** 140 #define AM_HAL_PWRCTRL_VDDF_BOOST_WA 141 142 #ifdef __cplusplus 143 extern "C" 144 { 145 #endif 146 147 //***************************************************************************** 148 // 149 // Function prototypes 150 // 151 //***************************************************************************** 152 //***************************************************************************** 153 // 154 //! @brief Enable power to a peripheral. 155 //! 156 //! @param ePeripheral - The peripheral to enable. 157 //! 158 //! This function enables power to the peripheral and waits for a 159 //! confirmation from the hardware. 160 //! 161 //! @return status - generic or interface specific status. 162 // 163 //***************************************************************************** 164 extern uint32_t am_hal_pwrctrl_periph_enable(am_hal_pwrctrl_periph_e ePeripheral); 165 166 //***************************************************************************** 167 // 168 //! @brief Disable power to a peripheral. 169 //! 170 //! @param ePeripheral - The peripheral to disable. 171 //! 172 //! This function disables power to the peripheral and waits for a 173 //! confirmation from the hardware. 174 //! 175 //! @return status - generic or interface specific status. 176 // 177 //***************************************************************************** 178 extern uint32_t am_hal_pwrctrl_periph_disable(am_hal_pwrctrl_periph_e ePeripheral); 179 180 //***************************************************************************** 181 // 182 //! @brief Determine whether a peripheral is currently enabled. 183 //! 184 //! @param ePeripheral - The peripheral to enable. 185 //! @param pui32Enabled - Pointer to a ui32 that will return as 1 or 0. 186 //! 187 //! This function determines to the caller whether a given peripheral is 188 //! currently enabled or disabled. 189 //! 190 //! @return status - generic or interface specific status. 191 // 192 //***************************************************************************** 193 extern uint32_t am_hal_pwrctrl_periph_enabled( 194 am_hal_pwrctrl_periph_e ePeripheral, uint32_t *pui32Enabled); 195 196 //***************************************************************************** 197 // 198 //! @brief Enable a configuration of memory. 199 //! 200 //! @param eMemConfig - The memory configuration. 201 //! 202 //! This function establishes the desired configuration of flash, SRAM, ICache, 203 //! and DCache (DTCM) according to the desired Memory Configuration mask. 204 //! 205 //! @note Only the type of memory specified is affected. Therefore separate calls 206 //! are required to affect power settings for FLASH, SRAM, or CACHE. 207 //! 208 //! @return status - generic or interface specific status. 209 // 210 //***************************************************************************** 211 extern uint32_t am_hal_pwrctrl_memory_enable(am_hal_pwrctrl_mem_e eMemConfig); 212 213 //***************************************************************************** 214 // 215 //! @brief Power down respective memory. 216 //! 217 //! @param eMemConfig - The memory power down enum. 218 //! 219 //! This function establishes the desired power down of flash, SRAM, ICache, 220 //! and DCache (DTCM) according to the desired enum. 221 //! 222 //! @note Only the type of memory specified is affected. Therefore separate calls 223 //! are required to affect power settings for FLASH, SRAM, or CACHE. 224 //! 225 //! @return status - generic or interface specific status. 226 // 227 //***************************************************************************** 228 extern uint32_t am_hal_pwrctrl_memory_deepsleep_powerdown(am_hal_pwrctrl_mem_e eMemConfig); 229 230 //***************************************************************************** 231 // 232 //! @brief Apply retention voltage to respective memory. 233 //! 234 //! @param eMemConfig - The memory power down enum. 235 //! 236 //! This function establishes the desired power retain of flash, SRAM, ICache, 237 //! and DCache (DTCM) according to the desired enum. 238 //! 239 //! @note Only the type of memory specified is affected. Therefore separate calls 240 //! are required to affect power settings for FLASH, SRAM, or CACHE. 241 //! 242 //! @return status - generic or interface specific status. 243 // 244 //***************************************************************************** 245 extern uint32_t am_hal_pwrctrl_memory_deepsleep_retain(am_hal_pwrctrl_mem_e eMemConfig); 246 247 //***************************************************************************** 248 // 249 //! @brief Initialize system for low power configuration. 250 //! 251 //! This function handles low power initialization. 252 //! 253 //! @return status - generic or interface specific status. 254 // 255 //***************************************************************************** 256 extern uint32_t am_hal_pwrctrl_low_power_init(void); 257 258 //***************************************************************************** 259 // 260 //! @brief Initialize BLE Buck Trims for Lowest Power. 261 // 262 //***************************************************************************** 263 extern void am_hal_pwrctrl_blebuck_trim(void); 264 265 #if AM_HAL_BURST_LDO_WORKAROUND 266 267 typedef enum 268 { 269 AM_HAL_BURST_VDDC, 270 AM_HAL_BURST_VDDF 271 } am_hal_burst_voltage_wa_e; 272 273 //**************************************************************************** 274 // 275 //! @brief Adjust the simobuck vddc/vddf active trim value with saturation. 276 //! based on current register setting 277 //! 278 //! @param vddx - Voltage to be trimmed: 279 //! AM_HAL_BURST_VDDC, 280 //! AM_HAL_BURST_VDDF 281 //! 282 //! @param vddx_code - Current Value to trim 283 //! 284 //! @return int32_t actual adjusted trim code 285 // 286 //**************************************************************************** 287 extern int32_t am_hal_pwrctrl_simobuck_vddx_active_trim_adj(am_hal_burst_voltage_wa_e vddx, int32_t vddx_code); 288 289 //**************************************************************************** 290 // 291 //! @brief Adjust the ldo vddc/vddf active trim values with saturation. 292 //! based on current register setting 293 //! 294 //! @param vddx - Voltage to be trimmed: 295 //! AM_HAL_BURST_VDDC, 296 //! AM_HAL_BURST_VDDF 297 //! 298 //! @return int32_t actual adjusted trim code 299 // 300 //**************************************************************************** 301 extern int32_t am_hal_pwrctrl_ldo_vddx_active_trim_adj(am_hal_burst_voltage_wa_e vddx, int32_t vddx_code); 302 303 //**************************************************************************** 304 // 305 //! @brief Adjust the simobuck vddc/vddf active trim values with saturation. 306 //! based on current register setting 307 //! 308 //! @note Requires Info1 patch5 309 //! 310 //! @param vddx - Voltage to be trimmed: 311 //! AM_HAL_BURST_VDDC, 312 //! AM_HAL_BURST_VDDF 313 //! 314 //! @return int32_t actual adjusted trim code 315 // 316 //**************************************************************************** 317 extern int32_t am_hal_pwrctrl_simobuck_vddx_active_trim_adj_default(am_hal_burst_voltage_wa_e vddx, int32_t vddx_code); 318 319 //**************************************************************************** 320 // 321 //! @brief Adjust the LDO vddc/vddf active trim values with saturation. 322 //! based on current register setting 323 //! 324 //! @note Requires Info1 patch5 325 //! 326 //! @param vddx - Voltage to be trimmed: 327 //! AM_HAL_BURST_VDDC, 328 //! AM_HAL_BURST_VDDF 329 //! 330 //! @return int32_t actual adjusted trim code 331 // 332 //**************************************************************************** 333 extern int32_t am_hal_pwrctrl_ldo_vddx_active_trim_adj_default(am_hal_burst_voltage_wa_e vddx, int32_t vddx_code); 334 335 //***************************************************************************** 336 // 337 //! @brief Boost VDDF if CV Patch applied 338 // 339 //***************************************************************************** 340 extern void am_hal_pwrctrl_wa_vddf_boost(void); 341 342 //***************************************************************************** 343 // 344 //! @brief Restore VDDF if CV Patch applied 345 // 346 //***************************************************************************** 347 extern void am_hal_pwrctrl_wa_vddf_restore(void); 348 349 #endif // AM_HAL_BURST_LDO_WORKAROUND 350 351 #ifdef __cplusplus 352 } 353 #endif 354 355 #endif // AM_HAL_PWRCTRL_H 356 357 //***************************************************************************** 358 // 359 // End Doxygen group. 360 //! @} 361 // 362 //***************************************************************************** 363
