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