1 //***************************************************************************** 2 // 3 //! @file am_hal_rtc.h 4 //! 5 //! @brief Functions for interfacing and accessing the Real-Time Clock (RTC). 6 //! 7 //! @addtogroup rtc3 RTC - Real-Time Clock 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_RTC_H 48 #define AM_HAL_RTC_H 49 50 #ifdef __cplusplus 51 extern "C" 52 { 53 #endif 54 55 //***************************************************************************** 56 // 57 //! @name OSC Start and Stop 58 //! @brief OSC Start and Stop defines. 59 //! 60 //! OSC Start and Stop defines to be used with \e am_hal_clkgen_osc_x(). 61 //! @{ 62 // 63 //***************************************************************************** 64 #define AM_HAL_RTC_OSC_XT 0x0 65 //! @} 66 67 //***************************************************************************** 68 // 69 //! @name RTC Interrupts 70 //! @brief Macro definitions for RTC interrupt status bits. 71 //! 72 //! These macros correspond to the bits in the RTC interrupt status register. 73 //! They may be used with any of the \e am_hal_rtc_int_x() functions. 74 //! 75 //! @{ 76 // 77 //***************************************************************************** 78 #define AM_HAL_RTC_INT_ALM RTC_INTEN_ALM_Msk 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 //***************************************************************************** 148 // 149 // External function definitions 150 // 151 //***************************************************************************** 152 //***************************************************************************** 153 // 154 //! @brief Selects the clock source for the RTC. 155 //! 156 //! This function selects the clock source for the RTC. 157 //! 158 //! @param ui32OSC The clock source for the RTC.\n 159 //! Valid values for ui32OSC are: 160 //! 161 //! - AM_HAL_RTC_OSC_XT 162 //! 163 //! 164 //! @note After selection of the RTC oscillator, a 2 second delay occurs before 165 //! the new setting is reflected in status. Therefore the CLKGEN.STATUS.OMODE 166 //! bit will not reflect the new status until after the 2s wait period. 167 //! 168 // 169 //***************************************************************************** 170 extern void am_hal_rtc_osc_select(uint32_t ui32OSC); 171 172 //***************************************************************************** 173 // 174 //! @brief Enable/Start the RTC oscillator. 175 //! 176 //! Starts the RTC oscillator. 177 // 178 //***************************************************************************** 179 extern void am_hal_rtc_osc_enable(void); 180 181 //***************************************************************************** 182 // 183 //! @brief Disable/Stop the RTC oscillator. 184 //! 185 //! Stops the RTC oscillator. 186 // 187 //***************************************************************************** 188 extern void am_hal_rtc_osc_disable(void); 189 190 //***************************************************************************** 191 // 192 //! @brief Configures the RTC for 12 or 24 hour time keeping. 193 //! 194 //! Configures the RTC for 12 (true) or 24 (false) hour time keeping. 195 //! 196 //! @param b12Hour - A 'true' configures the RTC for 12 hour time keeping. 197 // 198 //***************************************************************************** 199 extern void am_hal_rtc_time_12hour(bool b12Hour); 200 201 //***************************************************************************** 202 // 203 //! @brief Set the Real Time Clock counter registers. 204 //! 205 //! Sets the RTC counter registers to the supplied values. 206 //! 207 //! @param *pTime - A pointer to the time structure. 208 // 209 //***************************************************************************** 210 extern uint32_t am_hal_rtc_time_set(am_hal_rtc_time_t *pTime); 211 212 //***************************************************************************** 213 // 214 //! @brief Get the Real Time Clock current time. 215 //! 216 //! Gets the RTC's current time 217 //! 218 //! @param *pTime - A pointer to the time structure to store the current time. 219 //! 220 //! @return 0 for success and 1 for error. 221 // 222 //***************************************************************************** 223 extern uint32_t am_hal_rtc_time_get(am_hal_rtc_time_t *pTime); 224 225 //***************************************************************************** 226 // 227 //! @brief Sets the alarm repeat interval. 228 //! 229 //! Sets the alarm repeat interval. 230 //! 231 //! @param ui32RepeatInterval 232 //! @parblock 233 //! the desired repeat interval. 234 //! 235 //! Valid values for ui32RepeatInterval: 236 //! 237 //! - AM_HAL_RTC_ALM_RPT_DIS 238 //! - AM_HAL_RTC_ALM_RPT_YR 239 //! - AM_HAL_RTC_ALM_RPT_MTH 240 //! - AM_HAL_RTC_ALM_RPT_WK 241 //! - AM_HAL_RTC_ALM_RPT_DAY 242 //! - AM_HAL_RTC_ALM_RPT_HR 243 //! - AM_HAL_RTC_ALM_RPT_MIN 244 //! - AM_HAL_RTC_ALM_RPT_SEC 245 //! - AM_HAL_RTC_ALM_RPT_10TH 246 //! - AM_HAL_RTC_ALM_RPT_100TH 247 //! @endparblock 248 // 249 //***************************************************************************** 250 extern void am_hal_rtc_alarm_interval_set(uint32_t ui32RepeatInterval); 251 252 //***************************************************************************** 253 // 254 //! @brief Sets the RTC's Alarm. 255 //! 256 //! Set the Real Time Clock Alarm Parameters. 257 //! 258 //! @param *pTime - A pointer to the time structure. 259 //! @param ui32RepeatInterval 260 //! @parblock 261 //! the desired alarm repeat interval.\n 262 //! Valid values for ui32RepeatInterval: 263 //! 264 //! - AM_HAL_RTC_ALM_RPT_DIS 265 //! - AM_HAL_RTC_ALM_RPT_YR 266 //! - AM_HAL_RTC_ALM_RPT_MTH 267 //! - AM_HAL_RTC_ALM_RPT_WK 268 //! - AM_HAL_RTC_ALM_RPT_DAY 269 //! - AM_HAL_RTC_ALM_RPT_HR 270 //! - AM_HAL_RTC_ALM_RPT_MIN 271 //! - AM_HAL_RTC_ALM_RPT_SEC 272 //! - AM_HAL_RTC_ALM_RPT_10TH 273 //! - AM_HAL_RTC_ALM_RPT_EVERY_100TH 274 //! @endparblock 275 // 276 //***************************************************************************** 277 extern void am_hal_rtc_alarm_set(am_hal_rtc_time_t *pTime, 278 uint32_t ui32RepeatInterval); 279 280 //***************************************************************************** 281 // 282 //! @brief Get the Real Time Clock Alarm Parameters 283 //! @note Gets the RTC's Alarm time 284 //! 285 //! @param *pTime - A pointer to the time structure to store the current alarm. 286 // 287 //***************************************************************************** 288 extern void am_hal_rtc_alarm_get(am_hal_rtc_time_t *pTime); 289 290 //***************************************************************************** 291 // 292 //! @brief Enable selected RTC interrupts. 293 //! 294 //! Enables the RTC interrupts. 295 //! 296 //! @param ui32Interrupt desired interrupts 297 //! @parblock 298 //! 299 //! ui32Interrupt should be the following: 300 //! 301 //! AM_HAL_RTC_INT_ALM 302 //! @endparblock 303 // 304 //***************************************************************************** 305 extern void am_hal_rtc_int_enable(uint32_t ui32Interrupt); 306 307 //***************************************************************************** 308 // 309 //! @brief Return the enabled RTC interrupts. 310 //! 311 //! @return enabled RTC interrupts. Return is 0 or AM_HAL_RTC_INT_ALM 312 // 313 //***************************************************************************** 314 extern uint32_t am_hal_rtc_int_enable_get(void); 315 316 //***************************************************************************** 317 // 318 //! @brief Disable selected RTC interrupts. 319 //! 320 //! Disables RTC interrupts. 321 //! 322 //! @param ui32Interrupt 323 //! @parblock 324 //! desired interrupts 325 //! 326 //! ui32Interrupt should be the following: 327 //! 328 //! AM_HAL_RTC_INT_ALM 329 //! @endparblock 330 // 331 //***************************************************************************** 332 extern void am_hal_rtc_int_disable(uint32_t ui32Interrupt); 333 334 //***************************************************************************** 335 // 336 //! @brief Clear selected RTC interrupts. 337 //! 338 //! Clears the RTC interrupts. 339 //! 340 //! @param ui32Interrupt 341 //! @parblock 342 //! desired interrupts 343 //! 344 //! ui32Interrupt should be the following: 345 //! 346 //! AM_HAL_RTC_INT_ALM 347 //! @endparblock 348 // 349 //***************************************************************************** 350 extern void am_hal_rtc_int_clear(uint32_t ui32Interrupt); 351 352 //***************************************************************************** 353 // 354 //! @brief Sets the selected RTC interrupts. 355 //! 356 //! Sets the RTC interrupts causing them to immediately trigger. 357 //! 358 //! @param ui32Interrupt 359 //! @parblock 360 //! desired interrupts 361 //! 362 //! ui32Interrupt should be the following: 363 //! 364 //! AM_HAL_RTC_INT_ALM 365 //! @endparblock 366 // 367 //***************************************************************************** 368 extern void am_hal_rtc_int_set(uint32_t ui32Interrupt); 369 370 //***************************************************************************** 371 // 372 //! @brief Returns the RTC interrupt status. 373 //! 374 //! Returns the RTC interrupt status. 375 //! 376 //! @param bEnabledOnly - return the status of only the enabled interrupts. 377 //! 378 //! @return Bitwise representation of the current interrupt status. 379 //! The return value will be 0 or the following: 380 //! - AM_HAL_RTC_INT_ALM 381 // 382 //***************************************************************************** 383 extern uint32_t am_hal_rtc_int_status_get(bool bEnabledOnly); 384 385 #ifdef __cplusplus 386 } 387 #endif 388 389 #endif // AM_HAL_RTC_H 390 391 //***************************************************************************** 392 // 393 // End Doxygen group. 394 //! @} 395 // 396 //***************************************************************************** 397
