ADuCM302x Device Drivers API Reference Manual  Release 3.1.2.0
adi_pwr.h
1 /*
2  *****************************************************************************
3  * @file: adi_pwr.h
4  * @brief: System clock and power management driver.
5  *-----------------------------------------------------------------------------
6 Copyright (c) 2016-2017 Analog Devices, Inc.
7 
8 All rights reserved.
9 
10 Redistribution and use in source and binary forms, with or without modification,
11 are permitted provided that the following conditions are met:
12  - Redistributions of source code must retain the above copyright notice,
13  this list of conditions and the following disclaimer.
14  - Redistributions in binary form must reproduce the above copyright notice,
15  this list of conditions and the following disclaimer in the documentation
16  and/or other materials provided with the distribution.
17  - Modified versions of the software must be conspicuously marked as such.
18  - This software is licensed solely and exclusively for use with processors
19  manufactured by or for Analog Devices, Inc.
20  - This software may not be combined or merged with other code in any manner
21  that would cause the software to become subject to terms and conditions
22  which differ from those listed here.
23  - Neither the name of Analog Devices, Inc. nor the names of its
24  contributors may be used to endorse or promote products derived
25  from this software without specific prior written permission.
26  - The use of this software may or may not infringe the patent rights of one
27  or more patent holders. This license does not release you from the
28  requirement that you obtain separate licenses from these patent holders
29  to use this software.
30 
31 THIS SOFTWARE IS PROVIDED BY ANALOG DEVICES, INC. AND CONTRIBUTORS "AS IS"
32 AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, NON-
33 INFRINGEMENT, TITLE, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
34 DISCLAIMED. IN NO EVENT SHALL ANALOG DEVICES, INC. OR CONTRIBUTORS BE LIABLE
35 FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, PUNITIVE OR
36 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, DAMAGES ARISING OUT OF
37 CLAIMS OF INTELLECTUAL PROPERTY RIGHTS INFRINGEMENT; 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 *****************************************************************************/
45 
46 
51 #ifndef ADI_PWR_H
52 #define ADI_PWR_H
53 
54 #include <adi_callback.h>
55 #include <adi_processor.h>
56 #include <stdbool.h>
57 
58 #ifdef __ICCARM__
59 /* IAR MISRA C 2004 error suppressions.
60  *
61  * Pm009 (rule 5.1): identifiers shall not rely on significance of more than 31 characters.
62  * IAR compiler supports longer identifiers.
63  * Pm011 (rule 6.3): The basic types of char, int, long, float cannot be used.
64  * bool is used in the APIs as it is not affending the rule. Disabling this as IAR treats it as an error.
65  */
66 #pragma diag_suppress=Pm009,Pm011
67 #endif /* __ICCARM__ */
68 
69 #ifdef __cplusplus
70  extern "C" {
71 #endif
72 
74 typedef enum {
81 
82 } ADI_CLOCK_ID;
83 
85 typedef enum {
99 
100 
108 typedef enum {
109 
114 
115 #if defined(__ADUCM4x50__)
116 
117  ADI_CLOCK_MUX_SPLL_GPIO,
118 #endif
119 
124 
136 
145 
147 
148 
152 typedef enum {
161 
163 
167 typedef enum
168 {
171 
174 
177 
180 
183 
186 
189 
192 
195 
198 
201 
204 
207 
210 
213 
216 
218 
219 
221 typedef enum {
223  ADI_CLOCK_GATE_GPT0_CLK = 1 << BITP_CLKG_CLK_CTL5_GPTCLK0OFF,
225  ADI_CLOCK_GATE_GPT1_CLK = 1 << BITP_CLKG_CLK_CTL5_GPTCLK1OFF,
227  ADI_CLOCK_GATE_GPT2_CLK = 1 << BITP_CLKG_CLK_CTL5_GPTCLK2OFF,
229  ADI_CLOCK_GATE_I2C_CLK = 1 << BITP_CLKG_CLK_CTL5_UCLKI2COFF,
231  ADI_CLOCK_GATE_GPIO_CLK = 1 << BITP_CLKG_CLK_CTL5_GPIOCLKOFF,
233  ADI_CLOCK_GATE_PCLK = 1 << BITP_CLKG_CLK_CTL5_PERCLKOFF,
234 
235 #if defined(__ADUCM4x50__)
236 
237  ADI_CLOCK_GATE_TMR_RGB_CLK = 1 << BITP_CLKG_CLK_CTL5_TMRRGBCLKOFF
238 #endif
239 
241 
242 #if defined(__ADUCM4x50__)
243 
246 typedef enum
247 {
249  ADI_PWR_HFOSC_DIV_BY_1,
251  ADI_PWR_HFOSC_DIV_BY_2,
253  ADI_PWR_HFOSC_DIV_BY_4,
255  ADI_PWR_HFOSC_DIV_BY_8,
257  ADI_PWR_HFOSC_DIV_BY_16,
259  ADI_PWR_HFOSC_DIV_BY_32
260 
261 } ADI_PWR_HFOSC_DIV;
262 #endif /* __ADUCM4x50__ */
263 
268 typedef enum
269 {
292 
294 
298 typedef enum
299 {
301  ADI_PWR_MODE_FLEXI = 0 << BITP_PMG_PWRMOD_MODE,
303  ADI_PWR_MODE_ACTIVE = 1 << BITP_PMG_PWRMOD_MODE,
305  ADI_PWR_MODE_HIBERNATE = 2 << BITP_PMG_PWRMOD_MODE,
307  ADI_PWR_MODE_SHUTDOWN = 3 << BITP_PMG_PWRMOD_MODE
308 
310 
311 
315 typedef enum
316 {
318  ADI_PWR_LOW_BATTERY_VOLTAGE_IEN = 1 << BITP_PMG_IEN_VBAT,
320  ADI_PWR_UNDER_VOLATAGE_IEN = 1 << BITP_PMG_IEN_VREGUNDR,
322  ADI_PWR_OVER_VOLATAGE_IEN = 1 << BITP_PMG_IEN_VREGOVR,
324  ADI_PWR_BATTERY_VOLTAGE_RANGE_IEN = 1 << BITP_PMG_IEN_IENBAT
325 
327 
328 
332 typedef enum
333 {
334 #if defined(__ADUCM4x50__)
335 
336  ADI_PWR_ROOT_CLOCK_MON_IEN = 1 << BITP_CLKG_OSC_CTL_ROOT_MON_EN,
338  ADI_PWR_LFXTAL_CLOCK_MON_IEN = 1 << BITP_CLKG_OSC_CTL_LFX_MON_EN,
340  ADI_PWR_LFXTAL_STATUS_IEN = 1 << BITP_CLKG_CLK_CTL0_LFXTALIE,
342  ADI_PWR_HFXTAL_STATUS_IEN = 1 << BITP_CLKG_CLK_CTL0_HFXTALIE,
344  ADI_PWR_PLL_STATUS_IEN = 1 << BITP_CLKG_CLK_CTL3_SPLLIE
345 #elif defined(__ADUCM302x__)
346 
347  ADI_PWR_LFXTAL_CLOCK_MON_IEN = 1 << BITP_CLKG_OSC_CTL_LFXTAL_MON_EN,
349  ADI_PWR_LFXTAL_STATUS_IEN = 1 << BITP_CLKG_CLK_CTL0_LFXTALIE,
351  ADI_PWR_HFXTAL_STATUS_IEN = 1 << BITP_CLKG_CLK_CTL0_HFXTALIE,
353  ADI_PWR_PLL_STATUS_IEN = 1 << BITP_CLKG_CLK_CTL3_SPLLIE
354 #endif
355 
357 
361 typedef enum
362 {
367 
370 
371 #if defined(__ADUCM4x50__)
372 
373  ADI_PWR_EVENT_BATTERY_VOLTAGE_RANGE_1,
375  ADI_PWR_EVENT_BATTERY_VOLTAGE_RANGE_2,
377  ADI_PWR_EVENT_BATTERY_VOLTAGE_RANGE_3,
378 
380  ADI_PWR_EVENT_OSC_LFXTAL_AUTO_SWITCH,
382  ADI_PWR_EVENT_OSC_LFXTAL_MON_FAIL,
384  ADI_PWR_EVENT_OSC_ROOT_CLOCK_MON_FAIL,
386  ADI_PWR_EVENT_OSC_ROOT_CLOCK_FAIL_AUTO_SWITCH,
387 #endif
388 
402 
403 } ADI_PWR_EVENT;
404 
405 
409 typedef enum
410 {
419 
421 
425 typedef enum
426 {
434 
435 #if defined(__ADUCM4x50__)
436 
440 typedef enum
441 {
444  ADI_PWR_HPBUCK_LD_MODE_LOW,
445 
448  ADI_PWR_HPBUCK_LD_MODE_HIGH
449 
450 }ADI_PWR_HPBUCK_LD_MODE;
451 #endif /* __ADUCM4x50__ */
452 
453 /* Related clock APIs */
454 
455 /*
456  * Initialize the dynamic power management service
457  */
458 ADI_PWR_RESULT adi_pwr_Init(void);
459 
460 /*
461  * =================================================================
462  * Clock Management related APIs
463  * =================================================================
464 */
465 
466 /*
467  * Update the internal clock variable based on current configuration
468  */
469 ADI_PWR_RESULT adi_pwr_UpdateCoreClock(void);
470 
471 /*
472  * Set the external clock frequency.
473  */
474 ADI_PWR_RESULT adi_pwr_SetExtClkFreq(
475  const uint32_t ExtClkFreq
476  );
477 
478 /*
479  * To Configure the root clock muxing
480  */
481 ADI_PWR_RESULT adi_pwr_SetRootClockMux(
482  const ADI_CLOCK_MUX_ID eClockID
483  );
484 
485 /*
486  * To Configure the root clock muxing
487  */
488 ADI_PWR_RESULT adi_pwr_SetPLLClockMux(
489  const ADI_CLOCK_MUX_ID eClockID
490  );
491 
492 /*
493  * To Configure the root clock muxing
494  */
495 ADI_PWR_RESULT adi_pwr_SetLFClockMux(
496  const ADI_CLOCK_MUX_ID eClockID
497  );
498 
499 #if defined(__ADUCM4x50__)
500 /*
501  * To Enable/Disable the LFXTAL Fail Auto switch.
502  */
503 ADI_PWR_RESULT adi_pwr_EnableLFXTALFailAutoSwitch(
504  const bool bEnable
505  );
506 
507 
508 /*
509  * To enable/disable auto switching of root clock to HFOSC upon detection
510  * of Root clock failure.
511  */
512 ADI_PWR_RESULT adi_pwr_EnableRootClockFailAutoSwitch(
513  const bool bEnable
514  );
515 
516 /*
517  * To set the HF Oscillator divide factor
518  */
519 ADI_PWR_RESULT adi_pwr_SetHFOscDivFactor(
520  const ADI_PWR_HFOSC_DIV eDivFactor
521  );
522 
523 /*
524  * To set the HF oscillator automatic divide by 1 during wakeup from Flexi mode
525  */
526 ADI_PWR_RESULT adi_pwr_EnableHFOscAutoDivBy1(
527  const bool bEnable
528  );
529 
530 #endif /* __ADUCM4x50__ */
531 
532 
533 
534 /*
535  * To Configure the reference clock muxing
536  */
537 ADI_PWR_RESULT adi_pwr_SetRefClockMux(
538  const ADI_CLOCK_MUX_ID eClockID
539  );
540 
541 /*
542  * Get external clock frequency.
543  */
544 ADI_PWR_RESULT adi_pwr_GetExtClkFreq(
545  uint32_t *pExtClock
546  );
547 
548 /*
549  * Get current clock frequency. This API can be used to know PCLK, HCLK.
550  */
551 ADI_PWR_RESULT adi_pwr_GetClockFrequency(
552  const ADI_CLOCK_ID eClockId,
553  uint32_t *pClock
554  );
555 /*
556  * To enable/disable the specific clock.
557  */
558 ADI_PWR_RESULT adi_pwr_EnableClock(
559  const ADI_CLOCK_GATE eClockGate,
560  const bool bEnable
561  );
562 
563 /*
564  * To enable/disable the specific clock source.
565  */
566 ADI_PWR_RESULT adi_pwr_EnableClockSource(
567  const ADI_CLOCK_SOURCE_ID eClockSource,
568  const bool bEnable
569  );
570 /*
571  * To set the specific clock divider.
572 */
573 ADI_PWR_RESULT adi_pwr_SetClockDivider(
574  const ADI_CLOCK_ID eClockId,
575  const uint16_t nDiv
576  );
577 /*
578  * To Get the clock status.
579 */
580 ADI_PWR_RESULT adi_pwr_GetClockStatus(
581  const ADI_CLOCK_SOURCE_ID eClockSource,
582  ADI_CLOCK_SOURCE_STATUS *peStatus
583  );
584 /*
585  * To configure the PLL to generate the SPLL
586 */
587 ADI_PWR_RESULT adi_pwr_SetPll(
588  uint8_t nDivFactor,
589  const uint8_t nMulFactor,
590  const bool bDiv2,
591  const bool bMul2
592  );
593 
594 /* To enable the interrupt for clock monitoring LFXTAL/HFXTAL/PLL.*/
595 ADI_PWR_RESULT adi_pwr_EnableClockInterrupt(
596  const ADI_PWR_CLOCK_IRQ eIrq,
597  const bool bEnable
598  );
599 
600 /* Enabling the LFXTAL bypass mode */
601 ADI_PWR_RESULT adi_pwr_EnableLFXTALBypass(
602  const bool bEnable
603  );
604 
605 
606 /*
607  * =================================================================
608  * Power Management related APIs
609  * =================================================================
610 */
611 /* To enable the interrupt for voltage monitoring.*/
612 ADI_PWR_RESULT adi_pwr_EnablePMGInterrupt(
613  const ADI_PWR_PMG_IRQ eIrq,
614  const bool bEnable
615  );
616 
617 /*
618  * To know which is interrupt caused the processor to wake up from SHUTDOWN mode.
619  */
620 ADI_PWR_RESULT adi_pwr_GetWakeUpStatus(
621  ADI_PWR_WAKEUP_STATUS *peStatus
622  );
623 
624 /*
625  * To select the voltage range of the battery for monitoring.
626 */
627 ADI_PWR_RESULT adi_pwr_SetVoltageRange(
628  const ADI_PWR_VOLTAGE_RANGE eRange
629  );
630 
631 /*
632  * For entering the low power mode.
633 */
634 ADI_PWR_RESULT adi_pwr_EnterLowPowerMode(
635  const ADI_PWR_POWER_MODE PowerMode,
636  uint32_t volatile * pnInterruptOccurred,
637  const uint8_t PriorityMask
638  );
639 
640 /*
641  * For exiting the low power mode.
642 */
643 ADI_PWR_RESULT adi_pwr_ExitLowPowerMode(
644  uint32_t volatile * pnInterruptOccurred
645  );
646 
647 /* To enable the HPBUCK */
648 ADI_PWR_RESULT adi_pwr_EnableHPBuck(
649  const bool bEnable
650  );
651 
652 #if defined(__ADUCM4x50__)
653 
654 /* Set the clock output through the GPIO */
655 ADI_PWR_RESULT adi_pwr_SetGPIOClockOutput(
656  const ADI_CLOCK_OUTPUT_ID eClockOutput
657  );
658 
659 
660 /* To enable the HPBUCK Low Power mode */
661 ADI_PWR_RESULT adi_pwr_EnableHPBuckLowPowerMode(
662  const bool bEnable
663  );
664 
665 /* To enable the HPBUCK Load mode */
666 ADI_PWR_RESULT adi_pwr_SetHPBuckLoadMode(
667  const ADI_PWR_HPBUCK_LD_MODE eLoadMode
668  );
669 
670 #endif /* __ADUCM4x50__ */
671 /*
672  * For registering the call back function .
673 */
674 ADI_PWR_RESULT adi_pwr_RegisterCallback(
675  const ADI_CALLBACK pfCallback,
676  void *pcbParam
677  );
678 
679 #ifdef __cplusplus
680 }
681 #endif
682 
683 #endif /* ADI_PWR_H */
684 
685 
688 /*
689 ** EOF
690 */
ADI_PWR_RESULT adi_pwr_SetClockDivider(const ADI_CLOCK_ID eClockId, const uint16_t nDiv)
Sets the clock divide factor for an individual clock group.
Definition: adi_pwr.c:565
ADI_PWR_RESULT adi_pwr_SetVoltageRange(const ADI_PWR_VOLTAGE_RANGE eRange)
To Monitor voltage range of battery.
Definition: adi_pwr.c:1399
ADI_PWR_POWER_MODE
Definition: adi_pwr.h:298
ADI_CLOCK_SOURCE_ID
Definition: adi_pwr.h:85
ADI_CLOCK_MUX_ID
Definition: adi_pwr.h:108
ADI_PWR_PMG_IRQ
Definition: adi_pwr.h:315
ADI_PWR_RESULT adi_pwr_SetPLLClockMux(const ADI_CLOCK_MUX_ID eClockID)
Sets the input clock source for PLL multiplexer.
Definition: adi_pwr.c:251
ADI_PWR_WAKEUP_STATUS
Definition: adi_pwr.h:409
ADI_CLOCK_ID
Definition: adi_pwr.h:74
ADI_CLOCK_OUTPUT_ID
Definition: adi_pwr.h:167
ADI_PWR_RESULT adi_pwr_EnablePMGInterrupt(const ADI_PWR_PMG_IRQ eIrq, const bool bEnable)
Enable/Disable the power management interrupt.
Definition: adi_pwr.c:1043
ADI_PWR_CLOCK_IRQ
Definition: adi_pwr.h:332
ADI_PWR_RESULT adi_pwr_UpdateCoreClock(void)
Updates the internal SystemCoreClock variable with current core Clock retrieved from cpu registers...
Definition: adi_pwr.c:179
ADI_PWR_RESULT
Definition: adi_pwr.h:268
ADI_PWR_RESULT adi_pwr_EnableHPBuck(const bool bEnable)
Enables or disables the HP Buck.
Definition: adi_pwr.c:1360
ADI_PWR_RESULT adi_pwr_SetPll(uint8_t nDivFactor, const uint8_t nMulFactor, const bool bDiv2, const bool bMul2)
Program PLL frequency.
Definition: adi_pwr.c:973
ADI_PWR_RESULT adi_pwr_EnableClockSource(const ADI_CLOCK_SOURCE_ID eClockSource, const bool bEnable)
To Enable/disable clock sources.
Definition: adi_pwr.c:693
ADI_PWR_RESULT adi_pwr_EnterLowPowerMode(const ADI_PWR_POWER_MODE PowerMode, uint32_t volatile *pnInterruptOccurred, const uint8_t PriorityMask)
Puts the processor into given low power mode.
Definition: adi_pwr.c:1718
ADI_PWR_RESULT adi_pwr_ExitLowPowerMode(uint32_t volatile *pnInterruptOccurred)
Definition: adi_pwr.c:1861
ADI_PWR_RESULT adi_pwr_GetExtClkFreq(uint32_t *pExtClock)
Gets the system external clock frequency. Gets the clock frequency of the source connected to the ext...
Definition: adi_pwr.c:434
ADI_PWR_RESULT adi_pwr_EnableClockInterrupt(const ADI_PWR_CLOCK_IRQ eIrq, const bool bEnable)
Enable/Disable the clock interrupt to monitor status of LFXTAL, HFXTAL and PLL.
Definition: adi_pwr.c:890
ADI_PWR_RESULT adi_pwr_RegisterCallback(const ADI_CALLBACK pfCallback, void *pcbParam)
Registers or unregister the callback function.
Definition: adi_pwr.c:198
ADI_CLOCK_GATE
Definition: adi_pwr.h:221
ADI_PWR_RESULT adi_pwr_EnableClock(const ADI_CLOCK_GATE eClockGate, const bool bEnable)
Enable/disable individual peripheral clocks.
Definition: adi_pwr.c:523
ADI_PWR_RESULT adi_pwr_EnableLFXTALBypass(const bool bEnable)
Enable/disable LFXTAL bypass mode.
Definition: adi_pwr.c:1081
ADI_PWR_EVENT
Definition: adi_pwr.h:361
ADI_PWR_RESULT adi_pwr_GetClockFrequency(const ADI_CLOCK_ID eClockId, uint32_t *pClock)
Get the frequency of the given clock. Obtain individual peripheral clock frequencies.
Definition: adi_pwr.c:467
ADI_PWR_RESULT adi_pwr_SetExtClkFreq(const uint32_t ExtClkFreq)
Sets the system external clock frequency.
Definition: adi_pwr.c:228
ADI_PWR_RESULT adi_pwr_SetRootClockMux(const ADI_CLOCK_MUX_ID eClockID)
Sets the source for the root clock multiplexer.
Definition: adi_pwr.c:390
ADI_PWR_RESULT adi_pwr_SetRefClockMux(const ADI_CLOCK_MUX_ID eClockID)
Sets clock source for the Reference clock multiplexer.
Definition: adi_pwr.c:346
ADI_PWR_VOLTAGE_RANGE
Definition: adi_pwr.h:425
ADI_PWR_RESULT adi_pwr_GetWakeUpStatus(ADI_PWR_WAKEUP_STATUS *peStatus)
Function to retrieve the wakeup from shut down mode status.
Definition: adi_pwr.c:1382
ADI_PWR_RESULT adi_pwr_GetClockStatus(const ADI_CLOCK_SOURCE_ID eClockSource, ADI_CLOCK_SOURCE_STATUS *peStatus)
Return the status of a clock source.
Definition: adi_pwr.c:794
ADI_PWR_RESULT adi_pwr_Init(void)
Definition: adi_pwr.c:109
ADI_PWR_RESULT adi_pwr_SetLFClockMux(const ADI_CLOCK_MUX_ID eClockID)
Sets the input clock for low frequency clock multiplexer.
Definition: adi_pwr.c:298
ADI_CLOCK_SOURCE_STATUS
Definition: adi_pwr.h:152