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