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