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