1 //***************************************************************************** 2 // 3 //! @file am_hal_clkgen.h 4 //! 5 //! @brief Functions for Interfacing with the CLKGEN. 6 //! 7 //! @addtogroup Clkgen3p Clkgen - Clock Generator 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_CLKGEN_H 48 #define AM_HAL_CLKGEN_H 49 50 #ifdef __cplusplus 51 extern "C" 52 { 53 #endif 54 55 56 // 57 //! Designate this peripheral. 58 // 59 #define AM_APOLLO3_CLKGEN 1 60 61 //***************************************************************************** 62 // 63 //! @name System Clock max frequency 64 //! @brief Defines the maximum clock frequency for this device. 65 //! 66 //! These macros provide a definition of the maximum clock frequency. 67 //! 68 //! @{ 69 // 70 //***************************************************************************** 71 #define AM_HAL_CLKGEN_FREQ_MAX_HZ 48000000 72 #define AM_HAL_CLKGEN_FREQ_MAX_KHZ (AM_HAL_CLKGEN_FREQ_MAX_HZ / 1000) 73 #define AM_HAL_CLKGEN_FREQ_MAX_MHZ (AM_HAL_CLKGEN_FREQ_MAX_HZ / 1000000) 74 #define AM_HAL_CLKGEN_CORESEL_MAXDIV 1 75 //! @} 76 77 // 78 //! Control operations. 79 // 80 typedef enum 81 { 82 AM_HAL_CLKGEN_CONTROL_SYSCLK_MAX, 83 AM_HAL_CLKGEN_CONTROL_XTAL_START, 84 AM_HAL_CLKGEN_CONTROL_LFRC_START, 85 AM_HAL_CLKGEN_CONTROL_XTAL_STOP, 86 AM_HAL_CLKGEN_CONTROL_LFRC_STOP, 87 AM_HAL_CLKGEN_CONTROL_SYSCLK_DIV2, 88 AM_HAL_CLKGEN_CONTROL_RTC_SEL_XTAL, 89 AM_HAL_CLKGEN_CONTROL_RTC_SEL_LFRC, 90 AM_HAL_CLKGEN_CONTROL_HFADJ_ENABLE, 91 AM_HAL_CLKGEN_CONTROL_HFADJ_DISABLE, 92 } am_hal_clkgen_control_e; 93 94 // 95 //! Current RTC oscillator. 96 // 97 typedef enum 98 { 99 AM_HAL_CLKGEN_STATUS_RTCOSC_XTAL, 100 AM_HAL_CLKGEN_STATUS_RTCOSC_LFRC, 101 } am_hal_clkgen_status_rtcosc_e; 102 103 // 104 //! CLKOUT 105 // 106 typedef enum 107 { 108 AM_HAL_CLKGEN_CLKOUT_LFRC_1024 = 0x0, // LFRC 109 AM_HAL_CLKGEN_CLKOUT_XTAL_16384, // XTAL / 2 110 AM_HAL_CLKGEN_CLKOUT_XTAL_8192, // XTAL / 4 111 AM_HAL_CLKGEN_CLKOUT_XTAL_4096, // XTAL / 8 112 AM_HAL_CLKGEN_CLKOUT_XTAL_2048, // XTAL / 16 113 AM_HAL_CLKGEN_CLKOUT_XTAL_1024, // XTAL / 32 114 AM_HAL_CLKGEN_CLKOUT_RTC_1HZ = 0x10, // RTC 115 AM_HAL_CLKGEN_CLKOUT_XTAL_0_015 = 0x16, // XTAL / 2097152 = 0.015625 Hz 116 AM_HAL_CLKGEN_CLKOUT_XTAL_32768, // XTAL 117 AM_HAL_CLKGEN_CLKOUT_CG_100, // ClkGen 100Hz 118 AM_HAL_CLKGEN_CLKOUT_LFRC_512 = 0x23, // LFRC / 2 = 512 Hz 119 AM_HAL_CLKGEN_CLKOUT_LFRC_32, // LFRC / 32 = 32 Hz 120 AM_HAL_CLKGEN_CLKOUT_LFRC_2, // LFRC / 512 = 2 Hz 121 AM_HAL_CLKGEN_CLKOUT_LFRC_0_03, // LFRC / 32768 = 0.03125 Hz 122 AM_HAL_CLKGEN_CLKOUT_XTAL_128, // XTAL / 256 = 128 Hz 123 AM_HAL_CLKGEN_CLKOUT_XTAL_4, // XTAL / 8192 = 4 Hz 124 AM_HAL_CLKGEN_CLKOUT_XTAL_0_5, // XTAL / 65536 = 0.5 Hz 125 // The next 5 are Uncalibrated LFRC 126 AM_HAL_CLKGEN_CLKOUT_ULFRC_64, // ULFRC / 16 = 64 Hz (uncal LFRC) 127 AM_HAL_CLKGEN_CLKOUT_ULFRC_8, // ULFRC / 128 = 8 Hz (uncal LFRC) 128 AM_HAL_CLKGEN_CLKOUT_ULFRC_1, // ULFRC / 1024 = 1 Hz (uncal LFRC) 129 AM_HAL_CLKGEN_CLKOUT_ULFRC_0_25, // ULFRC / 4096 = 0.25 Hz (uncal LFRC) 130 AM_HAL_CLKGEN_CLKOUT_ULFRC_0_0009, // ULFRC / 1M = 0.000976 Hz (uncal LFRC) 131 // 132 AM_HAL_CLKGEN_CLKOUT_LFRC_0_0004 = 0x31, // LFRC / 2M = 0.00048828125 Hz 133 // Following are Not Autoenabled ("NE") 134 AM_HAL_CLKGEN_CLKOUT_XTALNE_32768 = 0x35, // XTALNE / 1 = 32768 Hz 135 AM_HAL_CLKGEN_CLKOUT_XTALNE_2048, // XTALNE / 16 = 2048 Hz 136 AM_HAL_CLKGEN_CLKOUT_LFRCNE_32, // LFRCNE / 32 = 32 Hz 137 AM_HAL_CLKGEN_CLKOUT_LFRCNE_1024 = 0x39 // LFRCNE / 1 = 1024 Hz 138 } am_hal_clkgen_clkout_e; 139 140 // 141 //! ClkGen Interrupts 142 // 143 typedef enum 144 { 145 AM_HAL_CLKGEN_INTERRUPT_OF = CLKGEN_INTRPTEN_OF_Msk, 146 AM_HAL_CLKGEN_INTERRUPT_ACC = CLKGEN_INTRPTEN_ACC_Msk, 147 AM_HAL_CLKGEN_INTERRUPT_ACF = CLKGEN_INTRPTEN_ACF_Msk 148 } am_hal_clkgen_interrupt_e; 149 150 // 151 //! Status structure. 152 // 153 typedef struct 154 { 155 // 156 //! Returns the current system clock frequency, in hertz. 157 // 158 uint32_t ui32SysclkFreq; 159 160 // 161 //! Returns the current RTC oscillator as one of: 162 //! - AM_HAL_CLKGEN_STATUS_RTCOSC_LFRC 163 //! - AM_HAL_CLKGEN_STATUS_RTCOSC_XTAL 164 // 165 uint32_t eRTCOSC; 166 167 // 168 //! true = XTAL has failed (is enabled but not oscillating).\n 169 //! Also if the LFRC is selected as the oscillator in OCTRL.OSEL. 170 // 171 bool bXtalFailure; 172 } am_hal_clkgen_status_t; 173 174 175 // **************************************************************************** 176 // 177 //! @brief Apply various specific commands/controls on the CLKGEN module. 178 //! 179 //! This function is used to apply various controls on CLKGEN. 180 //! 181 //! @note IMPORTANT! This function MUST be called very early in execution of 182 //! an application with the parameter AM_HAL_CLKGEN_CONTROL_SYSCLK_MAX 183 //! in order to set Apollo3 to its required operating frequency. 184 //! 185 //! @param eControl - One of the following: 186 //! - AM_HAL_CLKGEN_CONTROL_SYSCLK_MAX 187 //! - AM_HAL_CLKGEN_CONTROL_XTAL_START 188 //! - AM_HAL_CLKGEN_CONTROL_LFRC_START 189 //! - AM_HAL_CLKGEN_CONTROL_XTAL_STOP 190 //! - AM_HAL_CLKGEN_CONTROL_LFRC_STOP 191 //! - AM_HAL_CLKGEN_CONTROL_RTC_SEL_XTAL 192 //! - AM_HAL_CLKGEN_CONTROL_RTC_SEL_LFRC 193 //! - AM_HAL_CLKGEN_CONTROL_HFADJ_ENABLE 194 //! - AM_HAL_CLKGEN_CONTROL_HFADJ_DISABLE 195 //! @param pArgs - pointer to args struct 196 //! 197 //! @return status - generic or interface specific status. 198 //! 199 //! @note After starting the XTAL, a 2 second warm-up delay is required. 200 // 201 // **************************************************************************** 202 extern uint32_t am_hal_clkgen_control(am_hal_clkgen_control_e eControl, 203 void *pArgs); 204 205 // **************************************************************************** 206 // 207 //! @brief Get CLKGEN status. 208 //! 209 //! This function returns the current value of various CLKGEN statuses. 210 //! 211 //! @param psStatus - ptr to a status structure to receive the current statuses. 212 //! 213 //! @return status - generic or interface specific status. 214 //! 215 //! @note After selection of the RTC Oscillator, a 2 second delay is required 216 //! before the new oscillator takes effect. Therefore the CLKGEN.STATUS.OMODE 217 //! bit will not reflect the new status until after the 2s wait period. 218 // 219 // **************************************************************************** 220 extern uint32_t am_hal_clkgen_status_get(am_hal_clkgen_status_t *psStatus); 221 222 // **************************************************************************** 223 // 224 //! @brief Enable CLKOUT. 225 //! 226 //! This function is used to enable and select a CLKOUT frequency. 227 //! 228 //! @param bEnable: true to enable, false to disable. 229 //! @param eClkSelect - One of the following: 230 //! - AM_HAL_CLKGEN_CLKOUT_LFRC_1024 231 //! - AM_HAL_CLKGEN_CLKOUT_XTAL_16384 232 //! - AM_HAL_CLKGEN_CLKOUT_XTAL_8192 233 //! - AM_HAL_CLKGEN_CLKOUT_XTAL_4096 234 //! - AM_HAL_CLKGEN_CLKOUT_XTAL_2048 235 //! - AM_HAL_CLKGEN_CLKOUT_XTAL_1024 236 //! - AM_HAL_CLKGEN_CLKOUT_RTC_1HZ 237 //! - AM_HAL_CLKGEN_CLKOUT_XTAL_0_015 238 //! - AM_HAL_CLKGEN_CLKOUT_XTAL_32768 239 //! - AM_HAL_CLKGEN_CLKOUT_CG_100 240 //! - AM_HAL_CLKGEN_CLKOUT_LFRC_512 241 //! - AM_HAL_CLKGEN_CLKOUT_LFRC_32 242 //! - AM_HAL_CLKGEN_CLKOUT_LFRC_2 243 //! - AM_HAL_CLKGEN_CLKOUT_LFRC_03 244 //! - AM_HAL_CLKGEN_CLKOUT_XTAL_128 245 //! - AM_HAL_CLKGEN_CLKOUT_XTAL_4 246 //! - AM_HAL_CLKGEN_CLKOUT_XTAL_0_5 247 //! - ** The next 5 are Uncalibrated LFRC 248 //! - AM_HAL_CLKGEN_CLKOUT_ULFRC_64 249 //! - AM_HAL_CLKGEN_CLKOUT_ULFRC_8 250 //! - AM_HAL_CLKGEN_CLKOUT_ULFRC_1 251 //! - AM_HAL_CLKGEN_CLKOUT_ULFRC_0_25 252 //! - AM_HAL_CLKGEN_CLKOUT_ULFRC_0_0009 253 //! -AM_HAL_CLKGEN_CLKOUT_LFRC_0_0004 254 //! - ** The Following are Not Autoenabled ("NE") 255 //! - AM_HAL_CLKGEN_CLKOUT_XTALNE_32768 256 //! - AM_HAL_CLKGEN_CLKOUT_XTALNE_2048 257 //! - AM_HAL_CLKGEN_CLKOUT_LFRCNE_32 258 //! - AM_HAL_CLKGEN_CLKOUT_LFRCNE_1024 259 //! 260 //! @return status - generic or interface specific status. 261 // 262 // **************************************************************************** 263 extern uint32_t am_hal_clkgen_clkout_enable(bool bEnable, 264 am_hal_clkgen_clkout_e eClkSelect); 265 266 // **************************************************************************** 267 // 268 //! @brief Enable selected CLKGEN Interrupts. 269 //! 270 //! This function enables the interrupts. 271 //! 272 //! @param ui32IntMask - One or more of the following bitmasks. 273 //! - AM_HAL_CLKGEN_INTERRUPT_OF 274 //! - AM_HAL_CLKGEN_INTERRUPT_ACC 275 //! - AM_HAL_CLKGEN_INTERRUPT_ACF 276 //! 277 //! @return status - generic or interface specific status. 278 // 279 // **************************************************************************** 280 extern uint32_t am_hal_clkgen_interrupt_enable(am_hal_clkgen_interrupt_e ui32IntMask); 281 282 // **************************************************************************** 283 // 284 //! @brief Disable selected CLKGEN Interrupts. 285 //! 286 //! This function disables the CLKGEN interrupts. 287 //! 288 //! @param ui32IntMask - One or more of the following bitmasks. 289 //! - AM_HAL_CLKGEN_INTERRUPT_OF 290 //! - AM_HAL_CLKGEN_INTERRUPT_ACC 291 //! - AM_HAL_CLKGEN_INTERRUPT_ACF 292 //! 293 //! @return status - generic or interface specific status. 294 // 295 // **************************************************************************** 296 extern uint32_t am_hal_clkgen_interrupt_disable(am_hal_clkgen_interrupt_e ui32IntMask); 297 298 //***************************************************************************** 299 // 300 //! @brief IOM interrupt clear 301 //! 302 //! This function clears the interrupts for the given peripheral. 303 //! 304 //! @param ui32IntMask - Interface specific interrupt mask. 305 //! The following are valid clear bits, any of which can be ORed together. 306 //! - AM_HAL_CLKGEN_INTERRUPT_OF 307 //! - AM_HAL_CLKGEN_INTERRUPT_ACC 308 //! - AM_HAL_CLKGEN_INTERRUPT_ACF 309 //! 310 //! @return status - generic or interface specific status. 311 // 312 //***************************************************************************** 313 extern uint32_t am_hal_clkgen_interrupt_clear(am_hal_clkgen_interrupt_e ui32IntMask); 314 315 // **************************************************************************** 316 // 317 //! @brief Return CLKGEN interrupts. 318 //! 319 //! @note Use this function to get all CLKGEN interrupts, or only the interrupts 320 //! that are enabled. 321 //! 322 //! @param bEnabledOnly - return only interrupts that are enabled 323 //! @param pui32IntStatus - returns interrupt status here 324 //! 325 //! @return status - generic or interface specific status. 326 // 327 // **************************************************************************** 328 extern uint32_t am_hal_clkgen_interrupt_status_get(bool bEnabledOnly, 329 uint32_t *pui32IntStatus); 330 331 // **************************************************************************** 332 // 333 //! @brief Sets the interrupt status. 334 //! 335 //! This function sets the CLKGEN interrupts. 336 //! 337 //! @param ui32IntMask - One or more of the following bitmasks. 338 //! - AM_HAL_CLKGEN_INTERRUPT_OF 339 //! - AM_HAL_CLKGEN_INTERRUPT_ACC 340 //! - AM_HAL_CLKGEN_INTERRUPT_ACF 341 //! 342 //! @return None. 343 // 344 // **************************************************************************** 345 extern uint32_t am_hal_clkgen_interrupt_set(am_hal_clkgen_interrupt_e ui32IntMask); 346 347 #ifdef __cplusplus 348 } 349 #endif 350 351 #endif // AM_HAL_CLKGEN_H 352 353 //***************************************************************************** 354 // 355 // End Doxygen group. 356 //! @} 357 // 358 //***************************************************************************** 359 360
