1 //*****************************************************************************
2 //
3 //  am_hal_rtc.h
4 //! @file
5 //!
6 //! @brief Functions for interfacing and accessing the Real-Time Clock (RTC).
7 //!
8 //! @addtogroup rtc2 Real-Time Clock (RTC)
9 //! @ingroup apollo2hal
10 //! @{
11 //
12 //*****************************************************************************
13 
14 //*****************************************************************************
15 //
16 // Copyright (c) 2017, Ambiq Micro
17 // All rights reserved.
18 //
19 // Redistribution and use in source and binary forms, with or without
20 // modification, are permitted provided that the following conditions are met:
21 //
22 // 1. Redistributions of source code must retain the above copyright notice,
23 // this list of conditions and the following disclaimer.
24 //
25 // 2. Redistributions in binary form must reproduce the above copyright
26 // notice, this list of conditions and the following disclaimer in the
27 // documentation and/or other materials provided with the distribution.
28 //
29 // 3. Neither the name of the copyright holder nor the names of its
30 // contributors may be used to endorse or promote products derived from this
31 // software without specific prior written permission.
32 //
33 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
34 // AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
35 // IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
36 // ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
37 // LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
38 // CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
39 // SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
40 // INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
41 // CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
42 // ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
43 // POSSIBILITY OF SUCH DAMAGE.
44 //
45 // This is part of revision 1.2.11 of the AmbiqSuite Development Package.
46 //
47 //*****************************************************************************
48 #ifndef AM_HAL_RTC_H
49 #define AM_HAL_RTC_H
50 
51 //*****************************************************************************
52 //
53 //! @name OSC Start and Stop
54 //! @brief OSC Start and Stop defines.
55 //!
56 //! OSC Start and Stop defines to be used with \e am_hal_clkgen_osc_x().
57 //! @{
58 //
59 //*****************************************************************************
60 #define AM_HAL_RTC_OSC_LFRC          0x1
61 #define AM_HAL_RTC_OSC_XT            0x0
62 //! @}
63 
64 //*****************************************************************************
65 //
66 //! @name RTC Interrupts
67 //! @brief Macro definitions for RTC interrupt status bits.
68 //!
69 //! These macros correspond to the bits in the RTC interrupt status register.
70 //! They may be used with any of the \e am_hal_rtc_int_x() functions.
71 //!
72 //! @{
73 //
74 //*****************************************************************************
75 #define AM_HAL_RTC_INT_ALM                  AM_REG_RTC_INTEN_ALM_M
76 #define AM_HAL_RTC_INT_OF                   AM_REG_RTC_INTEN_OF_M
77 #define AM_HAL_RTC_INT_ACC                  AM_REG_RTC_INTEN_ACC_M
78 #define AM_HAL_RTC_INT_ACF                  AM_REG_RTC_INTEN_ACF_M
79 //! @}
80 
81 //*****************************************************************************
82 //
83 //! @name RTC Alarm Repeat Interval.
84 //! @brief Macro definitions for the RTC alarm repeat interval.
85 //!
86 //! These macros correspond to the RPT bits in the RTCCTL register.
87 //! They may be used with the \e am_hal_rtc_alarm_interval_set() function.
88 //!
89 //! Note: AM_HAL_RTC_ALM_RPT_10TH and AM_HAL_RTC_ALM_RPT_100TH do not
90 //! correspond to the RPT bits but are used in conjunction with setting the
91 //! ALM100 bits in the ALMLOW register.
92 //!
93 //! @{
94 //
95 //*****************************************************************************
96 #define AM_HAL_RTC_ALM_RPT_DIS              0x0
97 #define AM_HAL_RTC_ALM_RPT_YR               0x1
98 #define AM_HAL_RTC_ALM_RPT_MTH              0x2
99 #define AM_HAL_RTC_ALM_RPT_WK               0x3
100 #define AM_HAL_RTC_ALM_RPT_DAY              0x4
101 #define AM_HAL_RTC_ALM_RPT_HR               0x5
102 #define AM_HAL_RTC_ALM_RPT_MIN              0x6
103 #define AM_HAL_RTC_ALM_RPT_SEC              0x7
104 #define AM_HAL_RTC_ALM_RPT_10TH             0x8
105 #define AM_HAL_RTC_ALM_RPT_100TH            0x9
106 //! @}
107 
108 //*****************************************************************************
109 //
110 //! @name RTC Alarm 100 Interval.
111 //! @brief Macro definitions for the RTC alarm ms intervals.
112 //!
113 //! These macros are used inside the #am_hal_rtc_alarm_interval_set function
114 //! when 10ms and 100ms repeated alarm intervals are desired.
115 //!
116 //! @{
117 //
118 //*****************************************************************************
119 #define AM_HAL_RTC_ALM100_DEFAULT           0x00
120 #define AM_HAL_RTC_ALM100_10TH              0xF0
121 #define AM_HAL_RTC_ALM100_100TH             0xFF
122 //! @}
123 
124 //*****************************************************************************
125 //
126 //! @brief The basic time structure used by the HAL for RTC interaction.
127 //!
128 //! All values are positive whole numbers. The HAL routines convert back and
129 //! forth to BCD.
130 //
131 //*****************************************************************************
132 typedef struct am_hal_rtc_time_struct
133 {
134     uint32_t ui32ReadError;
135     uint32_t ui32CenturyEnable;
136     uint32_t ui32Weekday;
137     uint32_t ui32Century;
138     uint32_t ui32Year;
139     uint32_t ui32Month;
140     uint32_t ui32DayOfMonth;
141     uint32_t ui32Hour;
142     uint32_t ui32Minute;
143     uint32_t ui32Second;
144     uint32_t ui32Hundredths;
145 }am_hal_rtc_time_t;
146 
147 #ifdef __cplusplus
148 extern "C"
149 {
150 #endif
151 
152 //*****************************************************************************
153 //
154 // External function definitions
155 //
156 //*****************************************************************************
157 extern void am_hal_rtc_osc_select(uint32_t ui32OSC);
158 extern void am_hal_rtc_osc_enable(void);
159 extern void am_hal_rtc_osc_disable(void);
160 extern void am_hal_rtc_time_12hour(bool b12Hour);
161 extern void am_hal_rtc_time_set(am_hal_rtc_time_t *pTime);
162 extern uint32_t am_hal_rtc_time_get(am_hal_rtc_time_t *pTime);
163 extern void am_hal_rtc_alarm_interval_set(uint32_t ui32RepeatInterval);
164 extern void am_hal_rtc_alarm_set(am_hal_rtc_time_t *pTime,
165                                  uint32_t ui32RepeatInterval);
166 extern void am_hal_rtc_alarm_get(am_hal_rtc_time_t *pTime);
167 extern void am_hal_rtc_int_enable(uint32_t ui32Interrupt);
168 extern uint32_t am_hal_rtc_int_enable_get(void);
169 extern void am_hal_rtc_int_disable(uint32_t ui32Interrupt);
170 extern void am_hal_rtc_int_clear(uint32_t ui32Interrupt);
171 extern void am_hal_rtc_int_set(uint32_t ui32Interrupt);
172 extern uint32_t am_hal_rtc_int_status_get(bool bEnabledOnly);
173 
174 #ifdef __cplusplus
175 }
176 #endif
177 
178 #endif // AM_HAL_RTC_H
179 
180 //*****************************************************************************
181 //
182 // End Doxygen group.
183 //! @}
184 //
185 //*****************************************************************************
186