1 //***************************************************************************** 2 // 3 //! @file am_hal_clkgen.h 4 //! 5 //! @brief Functions for interfacing with the CLKGEN. 6 //! 7 //! @addtogroup clkgen4_4p CLKGEN - Clock Generator 8 //! @ingroup apollo4p_hal 9 //! @{ 10 // 11 //***************************************************************************** 12 13 //***************************************************************************** 14 // 15 // Copyright (c) 2023, 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 stable-7da8bae71f 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 //! @name System Clock max frequency 58 //! @{ 59 //! Defines the maximum clock frequency for this device. 60 //! These macros provide a definition of the maximum clock frequency. 61 // 62 //***************************************************************************** 63 #define AM_HAL_CLKGEN_FREQ_MAX_HZ 96000000 64 65 #define AM_HAL_CLKGEN_FREQ_MAX_KHZ (AM_HAL_CLKGEN_FREQ_MAX_HZ / 1000) 66 #define AM_HAL_CLKGEN_FREQ_MAX_MHZ (AM_HAL_CLKGEN_FREQ_MAX_HZ / 1000000) 67 #define AM_HAL_CLKGEN_CORESEL_MAXDIV 1 68 //! @} 69 70 // 71 //! Control operations. 72 // 73 typedef enum 74 { 75 AM_HAL_CLKGEN_CONTROL_RTC_SEL_XTAL, 76 AM_HAL_CLKGEN_CONTROL_RTC_SEL_LFRC, 77 AM_HAL_CLKGEN_CONTROL_HFADJ_ENABLE, 78 AM_HAL_CLKGEN_CONTROL_HFADJ_DISABLE, 79 AM_HAL_CLKGEN_CONTROL_HF2ADJ_ENABLE, 80 AM_HAL_CLKGEN_CONTROL_HF2ADJ_DISABLE, 81 AM_HAL_CLKGEN_CONTROL_HF2ADJ_COMPUTE, 82 AM_HAL_CLKGEN_CONTROL_HFRC2_START, 83 AM_HAL_CLKGEN_CONTROL_HFRC2_STOP, 84 AM_HAL_CLKGEN_CONTROL_DCCLK_ENABLE, 85 AM_HAL_CLKGEN_CONTROL_DCCLK_DISABLE, 86 AM_HAL_CLKGEN_CONTROL_DISPCLKSEL_OFF, 87 AM_HAL_CLKGEN_CONTROL_DISPCLKSEL_HFRC48, 88 AM_HAL_CLKGEN_CONTROL_DISPCLKSEL_HFRC96, 89 AM_HAL_CLKGEN_CONTROL_DISPCLKSEL_DPHYPLL, 90 AM_HAL_CLKGEN_CONTROL_PLLCLK_ENABLE, 91 AM_HAL_CLKGEN_CONTROL_PLLCLK_DISABLE, 92 AM_HAL_CLKGEN_CONTROL_PLLCLKSEL_OFF, 93 AM_HAL_CLKGEN_CONTROL_PLLCLKSEL_HFRC12, 94 AM_HAL_CLKGEN_CONTROL_PLLCLKSEL_HFRC6, 95 AM_HAL_CLKGEN_CONTROL_PLLCLKSEL_HFXT 96 } am_hal_clkgen_control_e; 97 98 // 99 //! Current RTC oscillator. 100 // 101 typedef enum 102 { 103 AM_HAL_CLKGEN_STATUS_RTCOSC_XTAL, 104 AM_HAL_CLKGEN_STATUS_RTCOSC_LFRC, 105 } am_hal_clkgen_status_rtcosc_e; 106 107 // 108 //! Clock Generation CLKOUT 109 // 110 typedef enum 111 { 112 AM_HAL_CLKGEN_CLKOUT_XTAL_32768 = CLKGEN_CLKOUT_CKSEL_XT, // XTAL 113 AM_HAL_CLKGEN_CLKOUT_XTAL_16384 = CLKGEN_CLKOUT_CKSEL_XT_DIV2, // XTAL / 2 114 AM_HAL_CLKGEN_CLKOUT_XTAL_8192 = CLKGEN_CLKOUT_CKSEL_XT_DIV4, // XTAL / 4 115 AM_HAL_CLKGEN_CLKOUT_XTAL_4096 = CLKGEN_CLKOUT_CKSEL_XT_DIV8, // XTAL / 8 116 AM_HAL_CLKGEN_CLKOUT_XTAL_2048 = CLKGEN_CLKOUT_CKSEL_XT_DIV16, // XTAL / 16 117 AM_HAL_CLKGEN_CLKOUT_XTAL_1024 = CLKGEN_CLKOUT_CKSEL_XT_DIV32, // XTAL / 32 118 AM_HAL_CLKGEN_CLKOUT_XTAL_128 = CLKGEN_CLKOUT_CKSEL_XT_DIV256, // XTAL / 256 = 128 Hz 119 AM_HAL_CLKGEN_CLKOUT_XTAL_4 = CLKGEN_CLKOUT_CKSEL_XT_DIV8K, // XTAL / 8192 = 4 Hz 120 AM_HAL_CLKGEN_CLKOUT_XTAL_0_5 = CLKGEN_CLKOUT_CKSEL_XT_DIV64K, // XTAL / 65536 = 0.5 Hz 121 AM_HAL_CLKGEN_CLKOUT_XTAL_0_015 = CLKGEN_CLKOUT_CKSEL_XT_DIV2M, // XTAL / 2097152 = 0.015625 Hz 122 123 AM_HAL_CLKGEN_CLKOUT_LFRC = CLKGEN_CLKOUT_CKSEL_LFRC, // LFRC 124 AM_HAL_CLKGEN_CLKOUT_LFRC_512 = CLKGEN_CLKOUT_CKSEL_LFRC_DIV2, // LFRC / 2 = 512 Hz 125 AM_HAL_CLKGEN_CLKOUT_LFRC_32 = CLKGEN_CLKOUT_CKSEL_LFRC_DIV32, // LFRC / 32 = 32 Hz 126 AM_HAL_CLKGEN_CLKOUT_LFRC_2 = CLKGEN_CLKOUT_CKSEL_LFRC_DIV512, // LFRC / 512 = 2 Hz 127 AM_HAL_CLKGEN_CLKOUT_LFRC_0_03 = CLKGEN_CLKOUT_CKSEL_LFRC_DIV32K, // LFRC / 32768 = 0.03125 Hz 128 AM_HAL_CLKGEN_CLKOUT_LFRC_0_0010 = CLKGEN_CLKOUT_CKSEL_LFRC_DIV1M, // LFRC / 1M = 0.0009765625 Hz 129 130 AM_HAL_CLKGEN_CLKOUT_HFRC_48M = CLKGEN_CLKOUT_CKSEL_HFRC_DIV2, // HFRC / 2 = 48MHz 131 AM_HAL_CLKGEN_CLKOUT_HFRC_12M = CLKGEN_CLKOUT_CKSEL_HFRC_DIV8, // HFRC / 8 = 12MHz 132 AM_HAL_CLKGEN_CLKOUT_HFRC_6M = CLKGEN_CLKOUT_CKSEL_HFRC_DIV16, // HFRC / 16 = 6MHz 133 AM_HAL_CLKGEN_CLKOUT_HFRC_3M = CLKGEN_CLKOUT_CKSEL_HFRC_DIV32, // HFRC / 32 = 3MHz 134 AM_HAL_CLKGEN_CLKOUT_HFRC_750K = CLKGEN_CLKOUT_CKSEL_HFRC_DIV128, // HFRC / 128 = 750KHz 135 AM_HAL_CLKGEN_CLKOUT_HFRC_375K = CLKGEN_CLKOUT_CKSEL_HFRC_DIV256, // HFRC / 256 = 375KHz 136 AM_HAL_CLKGEN_CLKOUT_HFRC_187K = CLKGEN_CLKOUT_CKSEL_HFRC_DIV512, // HFRC / 512 = 187.5KHz 137 AM_HAL_CLKGEN_CLKOUT_HFRC_93750 = CLKGEN_CLKOUT_CKSEL_HFRC_DIV1024, // HFRC / 1024 = 93.75KHz 138 AM_HAL_CLKGEN_CLKOUT_HFRC_366 = CLKGEN_CLKOUT_CKSEL_HFRC_DIV256K, // HFRC / 262144 = 366.2Hz 139 AM_HAL_CLKGEN_CLKOUT_HFRC_1P4 = CLKGEN_CLKOUT_CKSEL_HFRC_DIV64M, // HFRC / 64M = 1.4Hz 140 141 AM_HAL_CLKGEN_CLKOUT_HFRC2_24M = CLKGEN_CLKOUT_CKSEL_HFRC2_24MHz, // HFRC2 = 24MHz 142 AM_HAL_CLKGEN_CLKOUT_HFRC2_12M = CLKGEN_CLKOUT_CKSEL_HFRC2_12MHz, // HFRC2 = 12MHz 143 AM_HAL_CLKGEN_CLKOUT_HFRC2_6M = CLKGEN_CLKOUT_CKSEL_HFRC2_6MHz, // HFRC2 = 6MHz 144 145 // Uncalibrated LFRC 146 AM_HAL_CLKGEN_CLKOUT_ULFRC_64 = CLKGEN_CLKOUT_CKSEL_ULFRC_DIV16, // ULFRC / 16 = 64 Hz (uncal LFRC) 147 AM_HAL_CLKGEN_CLKOUT_ULFRC_8 = CLKGEN_CLKOUT_CKSEL_ULFRC_DIV128, // ULFRC / 128 = 8 Hz (uncal LFRC) 148 AM_HAL_CLKGEN_CLKOUT_ULFRC_1 = CLKGEN_CLKOUT_CKSEL_ULFRC_1Hz, // ULFRC / 1024 = 1 Hz (uncal LFRC) 149 AM_HAL_CLKGEN_CLKOUT_ULFRC_0_25 = CLKGEN_CLKOUT_CKSEL_ULFRC_DIV4K, // ULFRC / 4096 = 0.25 Hz (uncal LFRC) 150 AM_HAL_CLKGEN_CLKOUT_ULFRC_0_0009 = CLKGEN_CLKOUT_CKSEL_ULFRC_DIV1M, // ULFRC / 1M = 0.000976 Hz (uncal LFRC) 151 152 // Not Autoenabled ("NE") 153 AM_HAL_CLKGEN_CLKOUT_XTALNE_32768 = CLKGEN_CLKOUT_CKSEL_XTNE, // XTALNE / 1 = 32768 Hz 154 AM_HAL_CLKGEN_CLKOUT_XTALNE_2048 = CLKGEN_CLKOUT_CKSEL_XTNE_DIV16, // XTALNE / 16 = 2048 Hz 155 AM_HAL_CLKGEN_CLKOUT_LFRCNE = CLKGEN_CLKOUT_CKSEL_LFRCNE, // LFRCNE / 32 = 32 Hz 156 AM_HAL_CLKGEN_CLKOUT_LFRCNE_32 = CLKGEN_CLKOUT_CKSEL_LFRCNE_DIV32, // LFRCNE / 32 = 32 Hz 157 AM_HAL_CLKGEN_CLKOUT_HFRCNE_96M = CLKGEN_CLKOUT_CKSEL_HFRCNE, // HFRCNE / 1 = 96MHz 158 AM_HAL_CLKGEN_CLKOUT_HFRCNE_12M = CLKGEN_CLKOUT_CKSEL_HFRCNE_DIV8, // HFRCNE / 8 = 12MHz 159 160 // Misc clocks 161 AM_HAL_CLKGEN_CLKOUT_RTC_1HZ = CLKGEN_CLKOUT_CKSEL_RTC_1Hz, // RTC 162 AM_HAL_CLKGEN_CLKOUT_CG_100 = CLKGEN_CLKOUT_CKSEL_CG_100Hz, // ClkGen 100Hz 163 AM_HAL_CLKGEN_CLKOUT_FLASHCLK = CLKGEN_CLKOUT_CKSEL_FLASH_CLK, 164 } am_hal_clkgen_clkout_e; 165 166 #define AM_HAL_CLKGEN_CLKOUT_MAX CLKGEN_CLKOUT_CKSEL_HFRC2_24MHz // Highest valid CKSEL enum value 167 168 // 169 //! enum for HFCR2 FLL computation 170 // 171 typedef enum 172 { 173 // 174 //! compute the hf2adj parameters from input and output freqs 175 // 176 AM_HAL_CLKGEN_HF2ADJ_COMP_COMP_FREQ = 1 , 177 // 178 //! use passed in values directory 179 // 180 AM_HAL_CLKGEN_HF2ADJ_COMP_DIRECT_ARG = 2, 181 // 182 //! force this enum to be sizeof 4 bytes 183 // 184 AM_HAL_CLKGEN_HF2ADJ_COMP_ALIGH = 0x70000000, 185 186 } am_hal_clockgen_hf2adj_compute_e; 187 188 // 189 //! struct used to pass data for AM_HAL_CLKGEN_CONTROL_HF2ADJ_COMPUTE 190 // 191 typedef struct 192 { 193 am_hal_clockgen_hf2adj_compute_e eHF2AdjType; 194 // 195 //! the xref oscillator frequency in hz 196 // 197 uint32_t ui32Source_freq_in_hz; 198 // 199 //! the target(output) frequency in hz 200 // 201 uint32_t ui32Target_freq_in_hz; 202 203 } am_hal_clockgen_hf2adj_compute_t; 204 205 206 // 207 //! Status structure. 208 // 209 typedef struct 210 { 211 // 212 // ui32SysclkFreq 213 //! Returns the current system clock frequency, in hertz. 214 // 215 uint32_t ui32SysclkFreq; 216 217 // 218 // eRTCOSC 219 // 220 //! Returns the current RTC oscillator as one of: 221 //! AM_HAL_CLKGEN_STATUS_RTCOSC_LFRC 222 //! AM_HAL_CLKGEN_STATUS_RTCOSC_XTAL 223 // 224 uint32_t eRTCOSC; 225 226 // 227 // bXtalFailure 228 //! true = XTAL has failed (is enabled but not oscillating). Also if the 229 //! LFRC is selected as the oscillator in OCTRL.OSEL. 230 // 231 bool bXtalFailure; 232 233 // 234 // enable status for all the peripheral clocks. 235 // 1: enable 236 // 0: disable 237 // 238 //uint32_t ui32Clockenstat; 239 //uint32_t ui32Clocken2stat; 240 //uint32_t ui32Clocken3stat; 241 } am_hal_clkgen_status_t; 242 243 // **************************************************************************** 244 // 245 //! @brief Apply various specific commands/controls on the CLKGEN module. 246 //! 247 //! This function is used to apply various controls on CLKGEN. 248 //! 249 //! @note IMPORTANT! This function MUST be called very early in execution of 250 //! an application with the parameter AM_HAL_CLKGEN_CONTROL_SYSCLK_MAX 251 //! in order to set Apollo4p to its required operating frequency. 252 //! 253 //! @param eControl - One of the following: 254 //! AM_HAL_CLKGEN_CONTROL_RTC_SEL_LFRC 255 //! AM_HAL_CLKGEN_CONTROL_RTC_SEL_XTAL 256 //! AM_HAL_CLKGEN_CONTROL_HFADJ_ENABLE 257 //! AM_HAL_CLKGEN_CONTROL_HFADJ_DISABLE 258 //! AM_HAL_CLKGEN_CONTROL_HF2ADJ_ENABLE 259 //! AM_HAL_CLKGEN_CONTROL_HF2ADJ_DISABLE 260 //! AM_HAL_CLKGEN_CONTROL_HFRC2_START 261 //! AM_HAL_CLKGEN_CONTROL_HFRC2_STOP 262 //! AM_HAL_CLKGEN_CONTROL_DCCLK_ENABLE 263 //! AM_HAL_CLKGEN_CONTROL_DCCLK_DISABLE 264 //! AM_HAL_CLKGEN_CONTROL_DISPCLKSEL_OFF 265 //! AM_HAL_CLKGEN_CONTROL_DISPCLKSEL_HFRC48 266 //! AM_HAL_CLKGEN_CONTROL_DISPCLKSEL_HFRC96 267 //! AM_HAL_CLKGEN_CONTROL_DISPCLKSEL_DPHYPLL 268 //! AM_HAL_CLKGEN_CONTROL_PLLCLK_ENABLE 269 //! AM_HAL_CLKGEN_CONTROL_PLLCLK_DISABLE 270 //! AM_HAL_CLKGEN_CONTROL_PLLCLKSEL_OFF 271 //! AM_HAL_CLKGEN_CONTROL_PLLCLKSEL_HFRC12 272 //! AM_HAL_CLKGEN_CONTROL_PLLCLKSEL_HFRC6 273 //! AM_HAL_CLKGEN_CONTROL_PLLCLKSEL_HFXT 274 //! AM_HAL_CLKGEN_CONTROL_HF2ADJ_COMPUTE 275 //! @param pArgs - Pointer to arguments for Control Switch Case 276 //! 277 //! @return status - generic or interface specific status. 278 //! 279 //! @note After starting the XTAL, a 2 second warm-up delay is required. 280 // 281 // **************************************************************************** 282 extern uint32_t am_hal_clkgen_control(am_hal_clkgen_control_e eControl, 283 void *pArgs); 284 285 // **************************************************************************** 286 // 287 //! @brief Get CLKGEN status. 288 //! 289 //! This function returns the current value of various CLKGEN statuses. 290 //! 291 //! @param psStatus - ptr to a status structure to receive the current statuses. 292 //! 293 //! @return status - generic or interface specific status. 294 //! 295 //! @note After selection of the RTC Oscillator, a 2 second delay is required 296 //! before the new oscillator takes effect. Therefore the CLKGEN.STATUS.OMODE 297 //! bit will not reflect the new status until after the 2s wait period. 298 // 299 // **************************************************************************** 300 extern uint32_t am_hal_clkgen_status_get(am_hal_clkgen_status_t *psStatus); 301 302 // **************************************************************************** 303 // 304 //! @brief Enable CLKOUT. 305 //! 306 //! This function is used to enable and select a CLKOUT frequency. 307 //! 308 //! @param bEnable: true to enable, false to disable. 309 //! @param eClkSelect - One of the following: 310 //! AM_HAL_CLKGEN_CLKOUT_XTAL_32768 311 //! AM_HAL_CLKGEN_CLKOUT_XTAL_16384 312 //! AM_HAL_CLKGEN_CLKOUT_XTAL_8192 313 //! AM_HAL_CLKGEN_CLKOUT_XTAL_4096 314 //! AM_HAL_CLKGEN_CLKOUT_XTAL_2048 315 //! AM_HAL_CLKGEN_CLKOUT_XTAL_1024 316 //! AM_HAL_CLKGEN_CLKOUT_XTAL_128 317 //! AM_HAL_CLKGEN_CLKOUT_XTAL_4 318 //! AM_HAL_CLKGEN_CLKOUT_XTAL_0_5 319 //! AM_HAL_CLKGEN_CLKOUT_XTAL_0_015 320 //! 321 //! AM_HAL_CLKGEN_CLKOUT_LFRC 322 //! AM_HAL_CLKGEN_CLKOUT_LFRC_512 323 //! AM_HAL_CLKGEN_CLKOUT_LFRC_32 324 //! AM_HAL_CLKGEN_CLKOUT_LFRC_2 325 //! AM_HAL_CLKGEN_CLKOUT_LFRC_0_03 326 //! AM_HAL_CLKGEN_CLKOUT_LFRC_0_0010 327 //! 328 //! AM_HAL_CLKGEN_CLKOUT_HFRC_48M 329 //! AM_HAL_CLKGEN_CLKOUT_HFRC_12M 330 //! AM_HAL_CLKGEN_CLKOUT_HFRC_6M 331 //! AM_HAL_CLKGEN_CLKOUT_HFRC_3M 332 //! AM_HAL_CLKGEN_CLKOUT_HFRC_750K 333 //! AM_HAL_CLKGEN_CLKOUT_HFRC_375K 334 //! AM_HAL_CLKGEN_CLKOUT_HFRC_187K 335 //! AM_HAL_CLKGEN_CLKOUT_HFRC_93750 336 //! AM_HAL_CLKGEN_CLKOUT_HFRC_366 337 //! AM_HAL_CLKGEN_CLKOUT_HFRC_1P4 338 //! AM_HAL_CLKGEN_CLKOUT_HFRC2_24M 339 //! AM_HAL_CLKGEN_CLKOUT_HFRC2_12M 340 //! AM_HAL_CLKGEN_CLKOUT_HFRC2_6M 341 //! 342 //! // Uncalibrated LFRC 343 //! AM_HAL_CLKGEN_CLKOUT_ULFRC_64 344 //! AM_HAL_CLKGEN_CLKOUT_ULFRC_8 345 //! AM_HAL_CLKGEN_CLKOUT_ULFRC_1 346 //! AM_HAL_CLKGEN_CLKOUT_ULFRC_0_25 347 //! AM_HAL_CLKGEN_CLKOUT_ULFRC_0_0009 348 //! 349 //! // Not Autoenabled ("NE") 350 //! AM_HAL_CLKGEN_CLKOUT_XTALNE_32768 351 //! AM_HAL_CLKGEN_CLKOUT_XTALNE_2048 352 //! AM_HAL_CLKGEN_CLKOUT_LFRCNE 353 //! AM_HAL_CLKGEN_CLKOUT_LFRCNE_32 354 //! AM_HAL_CLKGEN_CLKOUT_HFRCNE_96M 355 //! AM_HAL_CLKGEN_CLKOUT_HFRCNE_12M 356 //! 357 //! // Misc clocks 358 //! AM_HAL_CLKGEN_CLKOUT_RTC_1HZ 359 //! AM_HAL_CLKGEN_CLKOUT_CG_100 360 //! AM_HAL_CLKGEN_CLKOUT_FLASHCLK 361 //! 362 //! @return status - generic or interface specific status. 363 // 364 // **************************************************************************** 365 extern uint32_t am_hal_clkgen_clkout_enable(bool bEnable, 366 am_hal_clkgen_clkout_e eClkSelect); 367 #ifdef __cplusplus 368 } 369 #endif 370 371 #endif // AM_HAL_CLKGEN_H 372 373 //***************************************************************************** 374 // 375 // End Doxygen group. 376 //! @} 377 // 378 //***************************************************************************** 379 380
