1 //***************************************************************************** 2 // 3 //! @file am_hal_mcuctrl.h 4 //! 5 //! @brief Functions for interfacing with the MCUCTRL. 6 //! 7 //! @addtogroup mcuctrl4_4p MCUCTRL - MCU Control 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_MCUCTRL_H 48 #define AM_HAL_MCUCTRL_H 49 50 #include <stdint.h> 51 #include <stdbool.h> 52 #include "am_mcu_apollo.h" 53 54 55 #ifdef __cplusplus 56 extern "C" 57 { 58 #endif 59 // 60 61 //**************************************************************************** 62 //! @brief but number representing a peripheral that is using the HS XTAL 63 //! @details this is used by each peripheral to register the use of the HS XTAL 64 //! so the HFXTAL will not be disabled when a peripheral are using it 65 //**************************************************************************** 66 typedef enum 67 { 68 AM_HAL_HFXTAL_BLE_CONTROLLER_EN = 0, 69 AM_HAL_HFXTAL_USB_PHI_EN = 1, 70 AM_HAL_HFXTAL_ADC_EN = 2, 71 AM_HAL_HFXTAL_AUADC_EN = 3, 72 AM_HAL_HCXTAL_DBGCTRL_EN = 4, 73 AM_HAL_HCXTAL_CLKGEN_MISC_EN = 5, 74 AM_HAL_HCXTAL_CLKGEN_CLKOUT_EN = 6, 75 AM_HAL_HCXTAL_PDM_BASE_EN = 7, 76 AM_HAL_HCXTAL_II2S_BASE_EN = AM_HAL_HCXTAL_PDM_BASE_EN + AM_REG_PDM_NUM_MODULES, 77 AM_HAL_HCXTAL_IOM_BASE_EN = AM_HAL_HCXTAL_II2S_BASE_EN + AM_REG_I2S_NUM_MODULES, 78 // 79 //! this is used when setting a bit and no argument was passed (legacy) 80 // 81 AM_HAL_HCXTAL_DEFAULT_EN = AM_HAL_HCXTAL_IOM_BASE_EN + AM_REG_IOM_NUM_MODULES, 82 AM_HAL_HCXTAL_END_EN, 83 AM_HAL_HCXTAL_X32 = 0x7FFFFFFF, 84 85 } 86 am_hal_mcuctrl_hfxtal_users_e; 87 88 //**************************************************************************** 89 // 90 //! @brief this struct is used to pass data into am_hal_mcuctrl_control() 91 // 92 //**************************************************************************** 93 typedef struct 94 { 95 // 96 //! bit that identifies which peripheral is requesting modification of the 97 //! HF XTAL clock 98 // 99 uint32_t ui32_arg_hfxtal_user_mask ; 100 // 101 //! this is set if the hfxtal bit is being used 102 // 103 bool b_arg_hfxtal_in_use; 104 // 105 //! this is for legacy calls that would pass an argument with some enums 106 // 107 bool b_arg_apply_ext_source; 108 // 109 //! force the register modification 110 // 111 bool b_arg_force_update; 112 // 113 //! enable XTALHF GPIO output on clockout pin. 114 // 115 bool b_arg_enable_HfXtalClockout; 116 117 } 118 am_hal_mcuctrl_control_arg_t; 119 120 121 extern const am_hal_mcuctrl_control_arg_t g_amHalMcuctrlArgDefault; 122 extern const am_hal_mcuctrl_control_arg_t g_amHalMcuctrlArgBLEDefault; 123 124 #define MCUCTRL_CHIPPN_PARTNUM_PN_M 0xFF000000 125 #define MCUCTRL_CHIPPN_PARTNUM_PN_S 24 126 127 //********************************************************** 128 //! MCUCTRL XTALHSCAP defaults for Cooper 129 //! Refer to App Note Apollo4 Blue 32MHz Crystal Calibration 130 //********************************************************** 131 #define XTALHSCAP2TRIM_DEFAULT 44 132 #define XTALHSCAPTRIM_DEFAULT 4 133 134 #define APOLLO4_A \ 135 ((MCUCTRL->CHIPREV & MCUCTRL_CHIPREV_REVMAJ_Msk) == \ 136 _VAL2FLD(MCUCTRL_CHIPREV_REVMAJ, MCUCTRL_CHIPREV_REVMAJ_A)) 137 138 #define APOLLO4_B0 \ 139 ((MCUCTRL->CHIPREV & \ 140 (MCUCTRL_CHIPREV_REVMAJ_Msk | MCUCTRL_CHIPREV_REVMIN_Msk)) == \ 141 (_VAL2FLD(MCUCTRL_CHIPREV_REVMAJ, MCUCTRL_CHIPREV_REVMAJ_B) | \ 142 _VAL2FLD(MCUCTRL_CHIPREV_REVMIN, MCUCTRL_CHIPREV_REVMIN_REV0))) 143 144 #define APOLLO4_B1 \ 145 ((MCUCTRL->CHIPREV & \ 146 (MCUCTRL_CHIPREV_REVMAJ_Msk | MCUCTRL_CHIPREV_REVMIN_Msk)) == \ 147 (_VAL2FLD(MCUCTRL_CHIPREV_REVMAJ, MCUCTRL_CHIPREV_REVMAJ_B) | \ 148 _VAL2FLD(MCUCTRL_CHIPREV_REVMIN, MCUCTRL_CHIPREV_REVMIN_REV1))) 149 150 #define APOLLO4_B2 \ 151 ((MCUCTRL->CHIPREV & \ 152 (MCUCTRL_CHIPREV_REVMAJ_Msk | MCUCTRL_CHIPREV_REVMIN_Msk)) == \ 153 (_VAL2FLD(MCUCTRL_CHIPREV_REVMAJ, MCUCTRL_CHIPREV_REVMAJ_B) | \ 154 _VAL2FLD(MCUCTRL_CHIPREV_REVMIN, MCUCTRL_CHIPREV_REVMIN_REV2))) 155 156 // 157 // Determine if >= a given revision level. 158 // 159 #define APOLLO4_GE_B0 \ 160 ((MCUCTRL->CHIPREV & \ 161 (MCUCTRL_CHIPREV_REVMAJ_Msk | MCUCTRL_CHIPREV_REVMIN_Msk)) >= \ 162 (_VAL2FLD(MCUCTRL_CHIPREV_REVMAJ, MCUCTRL_CHIPREV_REVMAJ_B) | \ 163 _VAL2FLD(MCUCTRL_CHIPREV_REVMIN, MCUCTRL_CHIPREV_REVMIN_REV0))) 164 165 #define APOLLO4_GE_B1 \ 166 ((MCUCTRL->CHIPREV & \ 167 (MCUCTRL_CHIPREV_REVMAJ_Msk | MCUCTRL_CHIPREV_REVMIN_Msk)) >= \ 168 (_VAL2FLD(MCUCTRL_CHIPREV_REVMAJ, MCUCTRL_CHIPREV_REVMAJ_B) | \ 169 _VAL2FLD(MCUCTRL_CHIPREV_REVMIN, MCUCTRL_CHIPREV_REVMIN_REV1))) 170 171 #define APOLLO4_GE_B2 \ 172 ((MCUCTRL->CHIPREV & \ 173 (MCUCTRL_CHIPREV_REVMAJ_Msk | MCUCTRL_CHIPREV_REVMIN_Msk)) >= \ 174 (_VAL2FLD(MCUCTRL_CHIPREV_REVMAJ, MCUCTRL_CHIPREV_REVMAJ_B) | \ 175 _VAL2FLD(MCUCTRL_CHIPREV_REVMIN, MCUCTRL_CHIPREV_REVMIN_REV2))) 176 177 #define APOLLO4_GT_B2 \ 178 ((MCUCTRL->CHIPREV & \ 179 (MCUCTRL_CHIPREV_REVMAJ_Msk | MCUCTRL_CHIPREV_REVMIN_Msk)) > \ 180 (_VAL2FLD(MCUCTRL_CHIPREV_REVMAJ, MCUCTRL_CHIPREV_REVMAJ_B) | \ 181 _VAL2FLD(MCUCTRL_CHIPREV_REVMIN, MCUCTRL_CHIPREV_REVMIN_REV2))) 182 183 #define APOLLO4_GE_C0 \ 184 ((MCUCTRL->CHIPREV & \ 185 (MCUCTRL_CHIPREV_REVMAJ_Msk | MCUCTRL_CHIPREV_REVMIN_Msk)) >= \ 186 (_VAL2FLD(MCUCTRL_CHIPREV_REVMAJ, MCUCTRL_CHIPREV_REVMAJ_C) | \ 187 _VAL2FLD(MCUCTRL_CHIPREV_REVMIN, MCUCTRL_CHIPREV_REVMIN_REV0))) 188 189 #define APOLLO4_GT_C0 \ 190 ((MCUCTRL->CHIPREV & \ 191 (MCUCTRL_CHIPREV_REVMAJ_Msk | MCUCTRL_CHIPREV_REVMIN_Msk)) > \ 192 (_VAL2FLD(MCUCTRL_CHIPREV_REVMAJ, MCUCTRL_CHIPREV_REVMAJ_C) | \ 193 _VAL2FLD(MCUCTRL_CHIPREV_REVMIN, MCUCTRL_CHIPREV_REVMIN_REV0))) 194 195 //***************************************************************************** 196 // 197 // MCUCTRL specific definitions. 198 // 199 //***************************************************************************** 200 // Define the size of fields derived from the PARTNUM register 201 #define AM_HAL_MCUCTRL_CHIPPN_NV_SIZE_N (_FLD2VAL(MCUCTRL_CHIPPN_MRAMSIZE, 0xFFFFFFFF) + 1) 202 #define AM_HAL_MCUCTRL_CHIPPN_SRAM_SIZE_N (_FLD2VAL(MCUCTRL_CHIPPN_SRAMSIZE, 0xFFFFFFFF) + 1) 203 204 // Define the size of fields derived from the SKU register 205 #define AM_HAL_MCUCTRL_SKU_SSRAM_SIZE_N (_FLD2VAL(MCUCTRL_SKU_SKUSRAMSIZE, 0xFFFFFFFF) + 1) 206 #define AM_HAL_MCUCTRL_SKU_MRAM_SIZE_N (_FLD2VAL(MCUCTRL_SKU_SKUMRAMSIZE, 0xFFFFFFFF) + 1) 207 208 #define AM_HAL_MCUCTRL_CRYSTAL_IBST_DURATION 500 209 210 //***************************************************************************** 211 // 212 // MCUCTRL enumerations 213 // 214 //***************************************************************************** 215 //************************************** 216 //! MCUCTRL control operations 217 //************************************** 218 typedef enum 219 { 220 AM_HAL_MCUCTRL_CONTROL_EXTCLK32K_ENABLE, 221 AM_HAL_MCUCTRL_CONTROL_EXTCLK32K_DISABLE, 222 AM_HAL_MCUCTRL_CONTROL_EXTCLK32M_KICK_START, 223 AM_HAL_MCUCTRL_CONTROL_EXTCLK32M_NORMAL, 224 AM_HAL_MCUCTRL_CONTROL_EXTCLK32M_DISABLE, 225 AM_HAL_MCUCTRL_CONTROL_EXTCLK32M_CLOCKOUT, 226 } 227 am_hal_mcuctrl_control_e; 228 229 //************************************** 230 // 231 //! MCUCTRL info get 232 // 233 //************************************** 234 typedef enum 235 { 236 AM_HAL_MCUCTRL_INFO_FEATURES_AVAIL, 237 AM_HAL_MCUCTRL_INFO_DEVICEID 238 } 239 am_hal_mcuctrl_infoget_e; 240 241 //***************************************************************************** 242 // 243 //! MCUCTRL SKU/Feature Enums 244 // 245 //***************************************************************************** 246 typedef enum 247 { 248 AM_HAL_MCUCTRL_DTCM_384K 249 } am_hal_mcuctrl_dtcm_e; 250 251 // 252 //! SKU SSRAM size: 0=1MB, 1=2MB, 2=1MB, 3=2MB 253 //! SKU MRAM size: 0=0.5MB, 1=1MB, 2=1.5MB, 3=2MB, 254 // 255 typedef enum 256 { 257 AM_HAL_MCUCTRL_SSRAM_1M_PLUS_EXT0, // 1024KB SSRAM + 384KB Ext 258 AM_HAL_MCUCTRL_SSRAM_2M_PLUS_EXT1, // 2048KB SSRAM + 384KB Ext 259 AM_HAL_MCUCTRL_SSRAM_1M_PLUS_EXT, // 1024KB SSRAM + 384KB Ext 260 AM_HAL_MCUCTRL_SSRAM_2M_PLUS_EXT, // 2048KB SSRAM + 384KB Ext 261 } am_hal_mcuctrl_ssram_e; 262 #define AM_HAL_MCUCTRL_SSRAM_MAX AM_HAL_MCUCTRL_SSRAM_2M_PLUS_EXT 263 264 // 265 //! MRAM Size Setting 266 // 267 typedef enum 268 { 269 AM_HAL_MCUCTRL_MRAM_0P5M, 270 AM_HAL_MCUCTRL_MRAM_1M, 271 AM_HAL_MCUCTRL_MRAM_1P5M, 272 AM_HAL_MCUCTRL_MRAM_2M, 273 } am_hal_mcuctrl_mram_e; 274 275 #define AM_HAL_MCUCTRL_MRAM_MAX AM_HAL_MCUCTRL_MRAM_2M 276 277 // 278 //! MRAM GP/LL Setting 279 // 280 typedef enum 281 { 282 AM_HAL_MCUCTRL_CM4F_ONLY, 283 AM_HAL_MCUCTRL_CM4F_GPDSP, 284 AM_HAL_MCUCTRL_CM4F_GPDSP_LLDSP 285 } am_hal_mcuctrl_dsp_e; 286 287 //***************************************************************************** 288 // 289 // MCUCTRL data structures 290 // 291 //***************************************************************************** 292 //************************************** 293 // 294 //! MCUCTRL device structure 295 // 296 //************************************** 297 typedef struct 298 { 299 // 300 //! Device part number. (BCD format) 301 // 302 uint32_t ui32ChipPN; 303 304 // 305 //! Unique Chip ID 0. 306 // 307 uint32_t ui32ChipID0; 308 309 // 310 //! Unique Chip ID 1. 311 // 312 uint32_t ui32ChipID1; 313 314 // 315 //! Chip Revision. 316 // 317 uint32_t ui32ChipRev; 318 319 // 320 //! Vendor ID. 321 // 322 uint32_t ui32VendorID; 323 324 // 325 //! SKU 326 // 327 uint32_t ui32SKU; 328 329 // 330 //! Qualified chip. 331 // 332 uint32_t ui32Qualified; 333 334 // 335 //! Flash Size. 336 // 337 uint32_t ui32FlashSize; 338 339 // 340 //! SRAM Size. 341 //! Note: Total onboard SRAM is computed as ui32DTCMSize + ui32SSRAMSize. 342 // 343 uint32_t ui32DTCMSize; 344 345 // 346 //! SSRAM Size. 347 // 348 uint32_t ui32SSRAMSize; 349 350 // 351 //! MRAM Size. 352 // 353 uint32_t ui32MRAMSize; 354 355 // 356 // JEDEC chip info 357 // 358 uint32_t ui32JedecPN; 359 uint32_t ui32JedecJEPID; 360 uint32_t ui32JedecCHIPREV; 361 uint32_t ui32JedecCID; 362 } am_hal_mcuctrl_device_t; 363 364 //************************************** 365 // 366 //! MCUCTRL status structure 367 // 368 //************************************** 369 typedef struct 370 { 371 bool bDebuggerLockout; // DEBUGGER 372 bool bADCcalibrated; // ADCCAL 373 bool bBattLoadEnabled; // ADCBATTLOAD 374 uint8_t bSecBootOnWarmRst; // BOOTLOADER 375 uint8_t bSecBootOnColdRst; // BOOTLOADER 376 } am_hal_mcuctrl_status_t; 377 378 //************************************** 379 // 380 //! MCUCTRL features available structure 381 // 382 //************************************** 383 typedef struct 384 { 385 am_hal_mcuctrl_dtcm_e eDTCMSize; 386 am_hal_mcuctrl_ssram_e eSharedSRAMSize; 387 am_hal_mcuctrl_mram_e eMRAMSize; 388 bool bTurboSpot; 389 bool bDisplayCtrl; 390 bool bGPU; 391 bool bUSB; 392 bool bSecBootFeature; 393 } am_hal_mcuctrl_feature_t; 394 395 //********************************************************** 396 // 397 //! MCUCTRL XTALHSCAP Globals for Cooper Device 398 //! Refer to App Note Apollo4 Blue 32MHz Crystal Calibration 399 // 400 //********************************************************** 401 extern uint32_t g_ui32xtalhscap2trim; 402 extern uint32_t g_ui32xtalhscaptrim; 403 404 405 /****************************************************************************** 406 //! @brief get usage status of HF XTAL clock 407 //! 408 //! @return true if one or more users (modules) are using the HF XTAL clock 409 //! @return false if the XTAL clock is disabled and there are no users 410 *****************************************************************************/ 411 extern bool am_hal_mcuctrl_EXTCLK_active(void ); 412 413 // **************************************************************************** 414 // 415 //! @brief Apply various specific commands/controls on the MCUCTRL module. 416 //! 417 //! This function is used to apply various controls to MCUCTRL. 418 //! 419 //! @param eControl - One of the following: 420 //! AM_HAL_MCUCTRL_CONTROL_EXTCLK32K_ENABLE, 421 //! AM_HAL_MCUCTRL_CONTROL_EXTCLK32K_DISABLE, 422 //! AM_HAL_MCUCTRL_CONTROL_EXTCLK32M_KICK_START, 423 //! AM_HAL_MCUCTRL_CONTROL_EXTCLK32M_NORMAL, 424 //! AM_HAL_MCUCTRL_CONTROL_EXTCLK32M_DISABLE, 425 //! AM_HAL_MCUCTRL_CONTROL_EXTCLK32M_CLOCKOUT, 426 //! 427 //! @param pArgs - Pointer to arguments for Control Switch Case, see note and example below 428 //! 429 //! @note pArgs: new use for SDK Rev 4.4:<br> 430 //! to use the HF XTAL clock this function now expects a pointer the following 431 //! struct variable<br> 432 //! am_hal_mcuctrl_control_arg_t<br> 433 //! this is needed for the following eControl keywords 434 //! AM_HAL_MCUCTRL_CONTROL_EXTCLK32M_KICK_START, 435 //! AM_HAL_MCUCTRL_CONTROL_EXTCLK32M_NORMAL, 436 //! AM_HAL_MCUCTRL_CONTROL_EXTCLK32M_DISABLE, 437 //! AM_HAL_MCUCTRL_CONTROL_EXTCLK32M_CLOCKOUT, 438 //! 439 //! @code{.unparsed} 440 //! 441 //! am_hal_mcuctrl_control_arg_t cvar = g_amHalMcuctrlArgDefault;<br> 442 //! 443 //! // 444 //! // the user must choose the appropriate bit from the enum am_hal_mcuctrl_hfxtal_users_e<br> 445 //! // there are numerous examples that use this structure<br> 446 //! // 447 //! cvar.ui32_arg_hfxtal_user_mask = (1 \<\< AM_HAL_HFXTAL_AUADC_EN);<br> 448 //! 449 //! // 450 //! // populate the remaing fields as needed or use the default values<br> 451 //! // 452 //! retStat = am_hal_mcuctrl_control( AM_HAL_MCUCTRL_CONTROL_EXTCLK32M_NORMAL, (void *) &cvar );<br> 453 //! 454 //! @endcode 455 //! 456 //! @return status - generic or interface specific status. 457 // 458 // **************************************************************************** 459 extern uint32_t am_hal_mcuctrl_control(am_hal_mcuctrl_control_e eControl, 460 void *pArgs); 461 462 // **************************************************************************** 463 // 464 //! @brief MCUCTRL status function 465 //! 466 //! This function returns current status of the MCUCTRL as obtained from 467 //! various registers of the MCUCTRL block. 468 //! 469 //! @param psStatus - ptr to a status structure to receive the current statuses. 470 //! 471 //! @return status - generic or interface specific status. 472 // 473 // **************************************************************************** 474 extern uint32_t am_hal_mcuctrl_status_get(am_hal_mcuctrl_status_t *psStatus); 475 476 // **************************************************************************** 477 // 478 //! @brief Get information of the given MCUCTRL item. 479 //! 480 //! This function returns a data structure of information regarding the given 481 //! MCUCTRL parameter. 482 //! 483 //! @param eInfoGet - One of the following: Return structure type: 484 //! AM_HAL_MCUCTRL_INFO_DEVICEID, psDevice 485 //! AM_HAL_MCUCTRL_INFO_FAULT_STATUS psFault 486 //! 487 //! @param pInfo - A pointer to a structure to receive the return data, 488 //! the type of which is dependent on the eInfo parameter. 489 //! 490 //! @return status - generic or interface specific status. 491 // 492 // **************************************************************************** 493 extern uint32_t am_hal_mcuctrl_info_get(am_hal_mcuctrl_infoget_e eInfoGet, 494 void *pInfo); 495 496 #ifdef __cplusplus 497 } 498 #endif 499 500 #endif // AM_HAL_MCUCTRL_H 501 502 //***************************************************************************** 503 // 504 // End Doxygen group. 505 //! @} 506 // 507 //***************************************************************************** 508 509
