1 //***************************************************************************** 2 // 3 //! @file am_hal_mcuctrl.h 4 //! 5 //! @brief Functions for Interfacing with the MCUCTRL. 6 //! 7 //! @addtogroup mcuctrl3p MCUCTRL - MCU Control 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_MCUCTRL_H 48 #define AM_HAL_MCUCTRL_H 49 50 #ifdef __cplusplus 51 extern "C" 52 { 53 #endif 54 55 //***************************************************************************** 56 // 57 //! Chip Revision IDentification. 58 // 59 //***************************************************************************** 60 #define APOLLO3P \ 61 ((MCUCTRL->CHIPREV & \ 62 (MCUCTRL_CHIPREV_REVMAJ_Msk | MCUCTRL_CHIPREV_REVMIN_Msk)) == \ 63 (_VAL2FLD(MCUCTRL_CHIPREV_REVMAJ, MCUCTRL_CHIPREV_REVMAJ_C) | \ 64 _VAL2FLD(MCUCTRL_CHIPREV_REVMIN, MCUCTRL_CHIPREV_REVMIN_REV0))) 65 66 #define APOLLO3_B0 \ 67 ((MCUCTRL->CHIPREV & \ 68 (MCUCTRL_CHIPREV_REVMAJ_Msk | MCUCTRL_CHIPREV_REVMIN_Msk)) == \ 69 (_VAL2FLD(MCUCTRL_CHIPREV_REVMAJ, MCUCTRL_CHIPREV_REVMAJ_B) | \ 70 _VAL2FLD(MCUCTRL_CHIPREV_REVMIN, MCUCTRL_CHIPREV_REVMIN_REV0))) 71 72 #define APOLLO3_A1 \ 73 ((MCUCTRL->CHIPREV & \ 74 (MCUCTRL_CHIPREV_REVMAJ_Msk | MCUCTRL_CHIPREV_REVMIN_Msk)) == \ 75 (_VAL2FLD(MCUCTRL_CHIPREV_REVMAJ, MCUCTRL_CHIPREV_REVMAJ_A) | \ 76 _VAL2FLD(MCUCTRL_CHIPREV_REVMIN, MCUCTRL_CHIPREV_REVMIN_REV1))) 77 78 #define APOLLO3_A0 \ 79 ((MCUCTRL->CHIPREV & \ 80 (MCUCTRL_CHIPREV_REVMAJ_Msk | MCUCTRL_CHIPREV_REVMIN_Msk)) == \ 81 (_VAL2FLD(MCUCTRL_CHIPREV_REVMAJ, MCUCTRL_CHIPREV_REVMAJ_A) | \ 82 _VAL2FLD(MCUCTRL_CHIPREV_REVMIN, MCUCTRL_CHIPREV_REVMIN_REV0))) 83 84 // 85 //! Determine if >= a given revision level. 86 // 87 #define APOLLO3_GE_B0 \ 88 ((MCUCTRL->CHIPREV & \ 89 (MCUCTRL_CHIPREV_REVMAJ_Msk | MCUCTRL_CHIPREV_REVMIN_Msk)) >= \ 90 (_VAL2FLD(MCUCTRL_CHIPREV_REVMAJ, MCUCTRL_CHIPREV_REVMAJ_B) | \ 91 _VAL2FLD(MCUCTRL_CHIPREV_REVMIN, MCUCTRL_CHIPREV_REVMIN_REV0))) 92 93 #define APOLLO3_GE_A1 \ 94 ((MCUCTRL->CHIPREV & \ 95 (MCUCTRL_CHIPREV_REVMAJ_Msk | MCUCTRL_CHIPREV_REVMIN_Msk)) >= \ 96 (_VAL2FLD(MCUCTRL_CHIPREV_REVMAJ, MCUCTRL_CHIPREV_REVMAJ_A) | \ 97 _VAL2FLD(MCUCTRL_CHIPREV_REVMIN, MCUCTRL_CHIPREV_REVMIN_REV1))) 98 99 100 //***************************************************************************** 101 // 102 //! MCUCTRL specific definitions. 103 // 104 //***************************************************************************** 105 #define AM_HAL_MCUCTRL_CHIPPN_FLASH_SIZE_N ((MCUCTRL_CHIPPN_PARTNUM_FLASHSIZE_M >> MCUCTRL_CHIPPN_PARTNUM_FLASHSIZE_S) + 1) 106 #define AM_HAL_MCUCTRL_CHIPPN_SRAM_SIZE_N ((MCUCTRL_CHIPPN_PARTNUM_SRAMSIZE_M >> MCUCTRL_CHIPPN_PARTNUM_SRAMSIZE_S) + 1) 107 108 //***************************************************************************** 109 // 110 // MCUCTRL enumerations 111 // 112 //***************************************************************************** 113 //************************************** 114 //! MCUCTRL control operations 115 //************************************** 116 typedef enum 117 { 118 AM_HAL_MCUCTRL_CONTROL_FAULT_CAPTURE_ENABLE, 119 AM_HAL_MCUCTRL_CONTROL_FAULT_CAPTURE_DISABLE, 120 AM_HAL_MCUCTRL_CONTROL_EXTCLK32K_ENABLE, 121 AM_HAL_MCUCTRL_CONTROL_EXTCLK32K_DISABLE, 122 AM_HAL_MCUCTRL_CONTROL_SRAM_PREFETCH 123 } am_hal_mcuctrl_control_e; 124 125 //************************************** 126 //! MCUCTRL info get 127 //************************************** 128 typedef enum 129 { 130 AM_HAL_MCUCTRL_INFO_FEATURES_AVAIL, 131 AM_HAL_MCUCTRL_INFO_DEVICEID, 132 AM_HAL_MCUCTRL_INFO_FAULT_STATUS 133 } am_hal_mcuctrl_infoget_e; 134 135 //************************************** 136 //! MCUCTRL SRAM prefetch settings 137 //! 138 //! Prefetch settings are made via a call to: 139 //! am_hal_mcuctrl_control(AM_HAL_MCUCTRL_CONTROL_SRAM_PREFETCH, 140 //! &ui32PrefetchSetting); 141 //! 142 //! The settings may be logically ORed together to obtain the desired settings. 143 //! 144 //! Notes: 145 //! - NOPREFETCH settings override PREFETCH settings if both are provided. 146 //! For example, calling with both PREFETCH_INSTR and NOPREFETCH_INSTR 147 //! will result in instruction prefetch being disabled. 148 //! - When executing from SRAM, it is recommended that the PREFETCH_INSTR and 149 //! PREFETCH_INSTRCACHE bits be set. 150 //! - It is generally okay to have PREFETCH_INSTR & PREFETCH_INSTRCACHE enabled 151 //! even if no SRAM execution is expected. 152 //! - It is generally not recommended that data prefetch be enabled unless the 153 //! work flow has a large number of sequential accesses. 154 //! - Setting PREFETCH_INSTRCACHE requires PREFETCH_INSTR. This is enforced by 155 //! the function and an error is returned if both are not being set or if 156 //! PREFETCH_INSTR is not already set in the register. 157 //! - Setting PREFETCH_DATACACHE requires PREFETCH_DATA. This is enforced by 158 //! the function. An error is returned if both are not being set or if 159 //! PREFETCH_DATA is not already set in the register. 160 //************************************** 161 #define SRAM_NOPREFETCH_Pos 16 162 #define AM_HAL_MCUCTRL_SRAM_PREFETCH_INSTR (MCUCTRL_SRAMMODE_IPREFETCH_Msk << 0) 163 #define AM_HAL_MCUCTRL_SRAM_PREFETCH_INSTRCACHE (MCUCTRL_SRAMMODE_IPREFETCH_CACHE_Msk << 0) 164 #define AM_HAL_MCUCTRL_SRAM_PREFETCH_DATA (MCUCTRL_SRAMMODE_DPREFETCH_Msk << 0) 165 #define AM_HAL_MCUCTRL_SRAM_PREFETCH_DATACACHE (MCUCTRL_SRAMMODE_DPREFETCH_CACHE_Msk << 0) 166 #define AM_HAL_MCUCTRL_SRAM_NOPREFETCH_INSTR (MCUCTRL_SRAMMODE_IPREFETCH_Msk << SRAM_NOPREFETCH_Pos) 167 #define AM_HAL_MCUCTRL_SRAM_NOPREFETCH_INSTRCACHE (MCUCTRL_SRAMMODE_IPREFETCH_CACHE_Msk << SRAM_NOPREFETCH_Pos) 168 #define AM_HAL_MCUCTRL_SRAM_NOPREFETCH_DATA (MCUCTRL_SRAMMODE_DPREFETCH_Msk << SRAM_NOPREFETCH_Pos) 169 #define AM_HAL_MCUCTRL_SRAM_NOPREFETCH_DATACACHE (MCUCTRL_SRAMMODE_DPREFETCH_CACHE_Msk << SRAM_NOPREFETCH_Pos) 170 171 //***************************************************************************** 172 // 173 // MCUCTRL data structures 174 // 175 //***************************************************************************** 176 //************************************** 177 //! MCUCTRL device structure 178 //************************************** 179 typedef struct 180 { 181 // 182 //! Device part number. (BCD format) 183 // 184 uint32_t ui32ChipPN; 185 186 // 187 //! Unique Chip ID 0. 188 // 189 uint32_t ui32ChipID0; 190 191 // 192 //! Unique Chip ID 1. 193 // 194 uint32_t ui32ChipID1; 195 196 // 197 //! Chip Revision. 198 // 199 uint32_t ui32ChipRev; 200 201 // 202 //! Vendor ID. 203 // 204 uint32_t ui32VendorID; 205 206 // 207 //! SKU (Apollo3). 208 // 209 uint32_t ui32SKU; 210 211 // 212 //! Qualified chip. 213 // 214 uint32_t ui32Qualified; 215 216 // 217 //! Flash Size. 218 // 219 uint32_t ui32FlashSize; 220 221 // 222 //! SRAM Size. 223 // 224 uint32_t ui32SRAMSize; 225 226 // 227 //! JEDEC chip info 228 // 229 uint32_t ui32JedecPN; 230 uint32_t ui32JedecJEPID; 231 uint32_t ui32JedecCHIPREV; 232 uint32_t ui32JedecCID; 233 } 234 am_hal_mcuctrl_device_t; 235 236 //************************************** 237 //! MCUCTRL fault structure 238 //************************************** 239 typedef struct 240 { 241 // 242 //! ICODE bus fault occurred. 243 // 244 bool bICODE; 245 246 // 247 //! ICODE bus fault address. 248 // 249 uint32_t ui32ICODE; 250 251 // 252 //! DCODE bus fault occurred. 253 // 254 bool bDCODE; 255 256 // 257 //! DCODE bus fault address. 258 // 259 uint32_t ui32DCODE; 260 261 // 262 //! SYS bus fault occurred. 263 // 264 bool bSYS; 265 266 // 267 //! SYS bus fault address. 268 // 269 uint32_t ui32SYS; 270 } 271 am_hal_mcuctrl_fault_t; 272 273 //************************************** 274 //! MCUCTRL status structure 275 //************************************** 276 typedef struct 277 { 278 bool bBurstAck; // FEATUREENABLE 279 bool bBLEAck; // " 280 bool bDebuggerLockout; // DEBUGGER 281 bool bADCcalibrated; // ADCCAL 282 bool bBattLoadEnabled; // ADCBATTLOAD 283 uint8_t bSecBootOnWarmRst; // BOOTLOADER 284 uint8_t bSecBootOnColdRst; // " 285 } am_hal_mcuctrl_status_t; 286 287 //************************************** 288 //! MCUCTRL features available structure 289 //************************************** 290 typedef struct 291 { 292 bool bBurstAvail; // FEATUREENABLE 293 bool bBLEavail; // " 294 bool bBLEFeature; // SKU 295 bool bBurstFeature; // " 296 uint8_t ui8SecBootFeature; // BOOTLOADER 297 } am_hal_mcuctrl_feature_t; 298 299 300 // **************************************************************************** 301 // 302 //! @brief Apply various specific commands/controls on the MCUCTRL module. 303 //! 304 //! This function is used to apply various controls to MCUCTRL. 305 //! 306 //! @param eControl - One of the following: 307 //! @parblock 308 //! - AM_HAL_MCUCTRL_CONTROL_FAULT_CAPTURE_ENABLE 309 //! - AM_HAL_MCUCTRL_CONTROL_FAULT_CAPTURE_DISABLE 310 //! - AM_HAL_MCUCTRL_CONTROL_EXTCLK32K_ENABLE 311 //! - AM_HAL_MCUCTRL_CONTROL_EXTCLK32K_DISABLE 312 //! - AM_HAL_MCUCTRL_CONTROL_SRAM_PREFETCH 313 //! @endparblock 314 //! @param pArgs - Pointer to Args 315 //! 316 //! @return status - generic or interface specific status. 317 // 318 // **************************************************************************** 319 extern uint32_t am_hal_mcuctrl_control(am_hal_mcuctrl_control_e eControl, 320 void *pArgs); 321 322 // **************************************************************************** 323 // 324 //! @brief MCUCTRL status function 325 //! 326 //! This function returns current status of the MCUCTRL as obtained from 327 //! various registers of the MCUCTRL block. 328 //! 329 //! @param psStatus - Ptr to a status structure to receive the current statuses. 330 //! 331 //! @return status - generic or interface specific status. 332 // 333 // **************************************************************************** 334 extern uint32_t am_hal_mcuctrl_status_get(am_hal_mcuctrl_status_t *psStatus); 335 336 // **************************************************************************** 337 // 338 //! @brief Get information of the given MCUCTRL item. 339 //! 340 //! This function returns a data structure of information regarding the given 341 //! MCUCTRL parameter. 342 //! 343 //! @param eInfoGet - One of the following: Return structure type: 344 //! - AM_HAL_MCUCTRL_INFO_DEVICEID, psDevice 345 //! - AM_HAL_MCUCTRL_INFO_FAULT_STATUS psFault 346 //! 347 //! @param pInfo - A pointer to a structure to receive the return data, 348 //! the type of which is dependent on the eInfo parameter. 349 //! 350 //! @return status - generic or interface specific status. 351 // 352 // **************************************************************************** 353 extern uint32_t am_hal_mcuctrl_info_get(am_hal_mcuctrl_infoget_e eInfoGet, 354 void *pInfo); 355 356 #ifdef __cplusplus 357 } 358 #endif 359 360 #endif // AM_HAL_MCUCTRL_H 361 362 //***************************************************************************** 363 // 364 // End Doxygen group. 365 //! @} 366 // 367 //***************************************************************************** 368
