1 //*****************************************************************************
2 //
3 //! @file am_hal_burst.h
4 //!
5 //! @brief Functions for Controlling Burst Mode Operation.
6 //!
7 //! @addtogroup burstmode3 Burst - Burst Mode Functionality
8 //! @ingroup apollo3_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_3_1_1-10cda4b5e0 of the AmbiqSuite Development Package.
45 //
46 //*****************************************************************************
47 #ifndef AM_HAL_BURST_H
48 #define AM_HAL_BURST_H
49 
50 #ifdef __cplusplus
51 extern "C"
52 {
53 #endif
54 
55 
56 //*****************************************************************************
57 //
58 // Burst Mode Status enums
59 //
60 //*****************************************************************************
61 //
62 //! Avail - the result of a feature availability interrogation.
63 //
64 typedef enum
65 {
66     AM_HAL_BURST_AVAIL,
67     AM_HAL_BURST_NOTAVAIL
68 } am_hal_burst_avail_e;
69 
70 //
71 //! Mode - the result of a change request.
72 //
73 typedef enum
74 {
75     AM_HAL_BURST_MODE,
76     AM_HAL_NORMAL_MODE,
77 } am_hal_burst_mode_e;
78 
79 //*****************************************************************************
80 //
81 //! @brief Burst mode initialization function
82 //!
83 //! @param peBurstAvail - Availibility of feature
84 //!
85 //! This function initializes the Apollo3 MCU for Burst Mode operation. It does
86 //! not set the MCU into Burst Mode.  This should be called once at system
87 //! initialization if Burst Mode is going to be used in the system.
88 //!
89 //! @return status of API call.
90 //
91 //*****************************************************************************
92 extern uint32_t am_hal_burst_mode_initialize(am_hal_burst_avail_e *peBurstAvail);
93 
94 //*****************************************************************************
95 //
96 //! @brief Burst mode enable function
97 //!
98 //! @param peBurstStatus - resulting mode after call.
99 //!
100 //! This function enables the Apollo3 MCU into Burst Mode operation.
101 //!
102 //! @return status of API call.
103 //
104 //*****************************************************************************
105 extern uint32_t am_hal_burst_mode_enable(am_hal_burst_mode_e *peBurstStatus);
106 
107 //*****************************************************************************
108 //
109 //! @brief Burst mode disable function
110 //!
111 //! @param peBurstStatus - resulting mode after call.
112 //!
113 //! This function disables the Apollo3 MCU from Burst Mode operation. It returns
114 //! the MCU to Normal Mode.
115 //!
116 //! @return status of API call.
117 //
118 //*****************************************************************************
119 extern uint32_t am_hal_burst_mode_disable(am_hal_burst_mode_e *peBurstStatus);
120 
121 //*****************************************************************************
122 //
123 //! @brief Return current burst mode state
124 //!
125 //! Implemented as a macro, this function returns the current burst mode state.
126 //!     AM_HAL_BURST_MODE
127 //!     AM_HAL_NORMAL_MODE
128 //
129 //*****************************************************************************
130 #define am_hal_burst_mode_status()                                          \
131     (CLKGEN->FREQCTRL_b.BURSTSTATUS ? AM_HAL_BURST_MODE : AM_HAL_NORMAL_MODE)
132 
133 #ifdef __cplusplus
134 }
135 #endif
136 
137 #endif // AM_HAL_BURST_H
138 //*****************************************************************************
139 //
140 // End Doxygen group.
141 //! @}
142 //
143 //*****************************************************************************
144