1 /*
2 * Copyright (c) 2015, Freescale Semiconductor, Inc.
3 * Copyright 2016-2019, 2022, 2023 NXP
4 * All rights reserved.
5 *
6 * SPDX-License-Identifier: BSD-3-Clause
7 */
8 #ifndef FSL_RTC_H_
9 #define FSL_RTC_H_
10
11 #include "fsl_common.h"
12
13 /*!
14 * @addtogroup rtc
15 * @{
16 */
17
18 /*******************************************************************************
19 * Definitions
20 ******************************************************************************/
21
22 /*! @name Driver version */
23 /*! @{ */
24 #define FSL_RTC_DRIVER_VERSION (MAKE_VERSION(2, 3, 0)) /*!< Version 2.3.0 */
25 /*! @} */
26
27 /*! @brief List of RTC interrupts */
28 typedef enum _rtc_interrupt_enable
29 {
30 kRTC_TimeInvalidInterruptEnable = (1U << 0U), /*!< Time invalid interrupt.*/
31 kRTC_TimeOverflowInterruptEnable = (1U << 1U), /*!< Time overflow interrupt.*/
32 kRTC_AlarmInterruptEnable = (1U << 2U), /*!< Alarm interrupt.*/
33 #if defined(FSL_FEATURE_RTC_HAS_MONOTONIC) && (FSL_FEATURE_RTC_HAS_MONOTONIC)
34 kRTC_MonotonicOverflowInterruptEnable = (1U << 3U), /*!< Monotonic Overflow Interrupt Enable */
35 #endif /* FSL_FEATURE_RTC_HAS_MONOTONIC */
36 kRTC_SecondsInterruptEnable = (1U << 4U), /*!< Seconds interrupt.*/
37 #if (defined(FSL_FEATURE_RTC_HAS_TIR) && FSL_FEATURE_RTC_HAS_TIR)
38 kRTC_TestModeInterruptEnable = (1U << 5U), /* test mode interrupt */
39 kRTC_FlashSecurityInterruptEnable = (1U << 6U), /* flash security interrupt */
40 #if (defined(FSL_FEATURE_RTC_HAS_TIR_TPIE) && FSL_FEATURE_RTC_HAS_TIR_TPIE)
41 kRTC_TamperPinInterruptEnable = (1U << 7U), /* Tamper pin interrupt */
42 #endif /* FSL_FEATURE_RTC_HAS_TIR_TPIE */
43 #if (defined(FSL_FEATURE_RTC_HAS_TIR_SIE) && FSL_FEATURE_RTC_HAS_TIR_SIE)
44 kRTC_SecurityModuleInterruptEnable = (1U << 8U), /* security module interrupt */
45 #endif /* FSL_FEATURE_RTC_HAS_TIR_SIE */
46 #if (defined(FSL_FEATURE_RTC_HAS_TIR_LCIE) && FSL_FEATURE_RTC_HAS_TIR_LCIE)
47 kRTC_LossOfClockInterruptEnable = (1U << 9U), /* loss of clock interrupt */
48 #endif /* FSL_FEATURE_RTC_HAS_TIR_LCIE */
49 #endif /* FSL_FEATURE_RTC_HAS_TIR */
50 } rtc_interrupt_enable_t;
51
52 /*! @brief List of RTC flags */
53 typedef enum _rtc_status_flags
54 {
55 kRTC_TimeInvalidFlag = (1U << 0U), /*!< Time invalid flag */
56 kRTC_TimeOverflowFlag = (1U << 1U), /*!< Time overflow flag */
57 kRTC_AlarmFlag = (1U << 2U), /*!< Alarm flag*/
58 #if defined(FSL_FEATURE_RTC_HAS_MONOTONIC) && (FSL_FEATURE_RTC_HAS_MONOTONIC)
59 kRTC_MonotonicOverflowFlag = (1U << 3U), /*!< Monotonic Overflow Flag */
60 #endif /* FSL_FEATURE_RTC_HAS_MONOTONIC */
61 #if (defined(FSL_FEATURE_RTC_HAS_SR_TIDF) && FSL_FEATURE_RTC_HAS_SR_TIDF)
62 kRTC_TamperInterruptDetectFlag = (1U << 4U), /*!< Tamper interrupt detect flag */
63 #endif /* FSL_FEATURE_RTC_HAS_SR_TIDF */
64 #if (defined(FSL_FEATURE_RTC_HAS_TDR) && FSL_FEATURE_RTC_HAS_TDR)
65 kRTC_TestModeFlag = (1U << 5U), /* Test mode flag */
66 kRTC_FlashSecurityFlag = (1U << 6U), /* Flash security flag */
67 #if (defined(FSL_FEATURE_RTC_HAS_TDR_TPF) && FSL_FEATURE_RTC_HAS_TDR_TPF)
68 kRTC_TamperPinFlag = (1U << 7U), /* Tamper pin flag */
69 #endif /* FSL_FEATURE_RTC_HAS_TDR_TPF */
70 #if (defined(FSL_FEATURE_RTC_HAS_TDR_STF) && FSL_FEATURE_RTC_HAS_TDR_STF)
71 kRTC_SecurityTamperFlag = (1U << 8U), /* Security tamper flag */
72 #endif /* FSL_FEATURE_RTC_HAS_TDR_STF */
73 #if (defined(FSL_FEATURE_RTC_HAS_TDR_LCTF) && FSL_FEATURE_RTC_HAS_TDR_LCTF)
74 kRTC_LossOfClockTamperFlag = (1U << 9U), /* Loss of clock flag */
75 #endif /* FSL_FEATURE_RTC_HAS_TDR_LCTF */
76 #endif /* FSL_FEATURE_RTC_HAS_TDR */
77 } rtc_status_flags_t;
78
79 #if (defined(FSL_FEATURE_RTC_HAS_OSC_SCXP) && FSL_FEATURE_RTC_HAS_OSC_SCXP)
80
81 /*! @brief List of RTC Oscillator capacitor load settings */
82 typedef enum _rtc_osc_cap_load
83 {
84 kRTC_Capacitor_2p = RTC_CR_SC2P_MASK, /*!< 2 pF capacitor load */
85 kRTC_Capacitor_4p = RTC_CR_SC4P_MASK, /*!< 4 pF capacitor load */
86 kRTC_Capacitor_8p = RTC_CR_SC8P_MASK, /*!< 8 pF capacitor load */
87 kRTC_Capacitor_16p = RTC_CR_SC16P_MASK /*!< 16 pF capacitor load */
88 } rtc_osc_cap_load_t;
89
90 #endif /* FSL_FEATURE_SCG_HAS_OSC_SCXP */
91
92 /*! @brief Structure is used to hold the date and time */
93 typedef struct _rtc_datetime
94 {
95 uint16_t year; /*!< Range from 1970 to 2099.*/
96 uint8_t month; /*!< Range from 1 to 12.*/
97 uint8_t day; /*!< Range from 1 to 31 (depending on month).*/
98 uint8_t hour; /*!< Range from 0 to 23.*/
99 uint8_t minute; /*!< Range from 0 to 59.*/
100 uint8_t second; /*!< Range from 0 to 59.*/
101 } rtc_datetime_t;
102
103 #if (defined(FSL_FEATURE_RTC_HAS_PCR) && FSL_FEATURE_RTC_HAS_PCR)
104
105 /*!
106 * @brief RTC pin config structure
107 */
108 typedef struct _rtc_pin_config
109 {
110 bool inputLogic; /*!< true: Tamper pin input data is logic one.
111 false: Tamper pin input data is logic zero. */
112 bool pinActiveLow; /*!< true: Tamper pin is active low.
113 false: Tamper pin is active high. */
114 bool filterEnable; /*!< true: Input filter is enabled on the tamper pin.
115 false: Input filter is disabled on the tamper pin. */
116 bool pullSelectNegate; /*!< true: Tamper pin pull resistor direction will negate the tamper pin.
117 false: Tamper pin pull resistor direction will assert the tamper pin. */
118 bool pullEnable; /*!< true: Pull resistor is enabled on tamper pin.
119 false: Pull resistor is disabled on tamper pin. */
120 } rtc_pin_config_t;
121
122 #endif /* FSL_FEATURE_RTC_HAS_PCR */
123
124 /*!
125 * @brief RTC config structure
126 *
127 * This structure holds the configuration settings for the RTC peripheral. To initialize this
128 * structure to reasonable defaults, call the RTC_GetDefaultConfig() function and pass a
129 * pointer to your config structure instance.
130 *
131 * The config struct can be made const so it resides in flash
132 */
133 typedef struct _rtc_config
134 {
135 bool wakeupSelect; /*!< true: Wakeup pin outputs the 32 KHz clock;
136 false:Wakeup pin used to wakeup the chip */
137 bool updateMode; /*!< true: Registers can be written even when locked under certain
138 conditions, false: No writes allowed when registers are locked */
139 bool supervisorAccess; /*!< true: Non-supervisor accesses are allowed;
140 false: Non-supervisor accesses are not supported */
141 uint32_t compensationInterval; /*!< Compensation interval that is written to the CIR field in RTC TCR Register */
142 uint32_t compensationTime; /*!< Compensation time that is written to the TCR field in RTC TCR Register */
143 } rtc_config_t;
144
145 /*******************************************************************************
146 * API
147 ******************************************************************************/
148
149 #if defined(__cplusplus)
150 extern "C" {
151 #endif
152
153 /*!
154 * @name Initialization and deinitialization
155 * @{
156 */
157
158 /*!
159 * @brief Ungates the RTC clock and configures the peripheral for basic operation.
160 *
161 * This function issues a software reset if the timer invalid flag is set.
162 *
163 * @note This API should be called at the beginning of the application using the RTC driver.
164 *
165 * @param base RTC peripheral base address
166 * @param config Pointer to the user's RTC configuration structure.
167 */
168 void RTC_Init(RTC_Type *base, const rtc_config_t *config);
169
170 /*!
171 * @brief Stops the timer and gate the RTC clock.
172 *
173 * @param base RTC peripheral base address
174 */
RTC_Deinit(RTC_Type * base)175 static inline void RTC_Deinit(RTC_Type *base)
176 {
177 /* Stop the RTC timer */
178 base->SR &= ~RTC_SR_TCE_MASK;
179
180 #if defined(RTC_CLOCKS)
181 #if !(defined(FSL_SDK_DISABLE_DRIVER_CLOCK_CONTROL) && FSL_SDK_DISABLE_DRIVER_CLOCK_CONTROL)
182 /* Gate the module clock */
183 CLOCK_DisableClock(kCLOCK_Rtc0);
184 #endif /* FSL_SDK_DISABLE_DRIVER_CLOCK_CONTROL */
185 #endif /* RTC_CLOCKS */
186 }
187
188 /*!
189 * @brief Fills in the RTC config struct with the default settings.
190 *
191 * The default values are as follows.
192 * @code
193 * config->wakeupSelect = false;
194 * config->updateMode = false;
195 * config->supervisorAccess = false;
196 * config->compensationInterval = 0;
197 * config->compensationTime = 0;
198 * @endcode
199 * @param config Pointer to the user's RTC configuration structure.
200 */
201 void RTC_GetDefaultConfig(rtc_config_t *config);
202
203 /*! @}*/
204
205 /*!
206 * @name Current Time & Alarm
207 * @{
208 */
209
210 /*!
211 * @brief Sets the RTC date and time according to the given time structure.
212 *
213 * The RTC counter must be stopped prior to calling this function because writes to the RTC
214 * seconds register fail if the RTC counter is running.
215 *
216 * @param base RTC peripheral base address
217 * @param datetime Pointer to the structure where the date and time details are stored.
218 *
219 * @return kStatus_Success: Success in setting the time and starting the RTC
220 * kStatus_InvalidArgument: Error because the datetime format is incorrect
221 */
222 status_t RTC_SetDatetime(RTC_Type *base, const rtc_datetime_t *datetime);
223
224 /*!
225 * @brief Gets the RTC time and stores it in the given time structure.
226 *
227 * @param base RTC peripheral base address
228 * @param datetime Pointer to the structure where the date and time details are stored.
229 */
230 void RTC_GetDatetime(RTC_Type *base, rtc_datetime_t *datetime);
231
232 /*!
233 * @brief Sets the RTC alarm time.
234 *
235 * The function checks whether the specified alarm time is greater than the present
236 * time. If not, the function does not set the alarm and returns an error.
237 *
238 * @param base RTC peripheral base address
239 * @param alarmTime Pointer to the structure where the alarm time is stored.
240 *
241 * @return kStatus_Success: success in setting the RTC alarm
242 * kStatus_InvalidArgument: Error because the alarm datetime format is incorrect
243 * kStatus_Fail: Error because the alarm time has already passed
244 */
245 status_t RTC_SetAlarm(RTC_Type *base, const rtc_datetime_t *alarmTime);
246
247 /*!
248 * @brief Returns the RTC alarm time.
249 *
250 * @param base RTC peripheral base address
251 * @param datetime Pointer to the structure where the alarm date and time details are stored.
252 */
253 void RTC_GetAlarm(RTC_Type *base, rtc_datetime_t *datetime);
254
255 /*! @}*/
256
257 /*!
258 * @name Interrupt Interface
259 * @{
260 */
261
262 /*!
263 * @brief Enables the selected RTC interrupts.
264 *
265 * @param base RTC peripheral base address
266 * @param mask The interrupts to enable. This is a logical OR of members of the
267 * enumeration ::rtc_interrupt_enable_t
268 */
269 void RTC_EnableInterrupts(RTC_Type *base, uint32_t mask);
270
271 /*!
272 * @brief Disables the selected RTC interrupts.
273 *
274 * @param base RTC peripheral base address
275 * @param mask The interrupts to enable. This is a logical OR of members of the
276 * enumeration ::rtc_interrupt_enable_t
277 */
278 void RTC_DisableInterrupts(RTC_Type *base, uint32_t mask);
279
280 /*!
281 * @brief Gets the enabled RTC interrupts.
282 *
283 * @param base RTC peripheral base address
284 *
285 * @return The enabled interrupts. This is the logical OR of members of the
286 * enumeration ::rtc_interrupt_enable_t
287 */
288 uint32_t RTC_GetEnabledInterrupts(RTC_Type *base);
289
290 /*! @}*/
291
292 /*!
293 * @name Status Interface
294 * @{
295 */
296
297 /*!
298 * @brief Gets the RTC status flags.
299 *
300 * @param base RTC peripheral base address
301 *
302 * @return The status flags. This is the logical OR of members of the
303 * enumeration ::rtc_status_flags_t
304 */
305 uint32_t RTC_GetStatusFlags(RTC_Type *base);
306
307 /*!
308 * @brief Clears the RTC status flags.
309 *
310 * @param base RTC peripheral base address
311 * @param mask The status flags to clear. This is a logical OR of members of the
312 * enumeration ::rtc_status_flags_t
313 */
314 void RTC_ClearStatusFlags(RTC_Type *base, uint32_t mask);
315
316 /*! @}*/
317
318 /*!
319 * @name Clock Source Configuration
320 * @{
321 */
322
323 #if !(defined(FSL_FEATURE_RTC_HAS_NO_CR_OSCE) && FSL_FEATURE_RTC_HAS_NO_CR_OSCE)
324
325 /*!
326 * @brief Enable/Disable RTC 32kHz Oscillator clock.
327 *
328 * @param base RTC peripheral base address
329 * @param enable Enable/Disable RTC 32.768 kHz clock
330 *
331 * @note After setting this bit, wait the oscillator startup time before enabling
332 * the time counter to allow the 32.768 kHz clock time to stabilize.
333 */
RTC_EnableOscillatorClock(RTC_Type * base,bool enable)334 static inline void RTC_EnableOscillatorClock(RTC_Type *base, bool enable)
335 {
336 if (enable)
337 {
338 base->CR |= RTC_CR_OSCE_MASK;
339 }
340 else
341 {
342 base->CR &= ~RTC_CR_OSCE_MASK;
343 }
344 }
345
346 /*!
347 * @brief Set RTC clock source.
348 * @deprecated Do not use this function. It has been superceded by @ref RTC_EnableOscillatorClock
349
350 * @param base RTC peripheral base address
351 *
352 * @note After setting this bit, wait the oscillator startup time before enabling
353 * the time counter to allow the 32.768 kHz clock time to stabilize.
354 */
RTC_SetClockSource(RTC_Type * base)355 static inline void RTC_SetClockSource(RTC_Type *base)
356 {
357 /* Enable the RTC 32KHz oscillator */
358 base->CR |= RTC_CR_OSCE_MASK;
359 }
360
361 #endif /* FSL_FEATURE_RTC_HAS_NO_CR_OSCE */
362
363 #if (defined(FSL_FEATURE_RTC_HAS_LPO_ADJUST) && FSL_FEATURE_RTC_HAS_LPO_ADJUST)
364
365 /*!
366 * @brief Enable/Disable RTC 1kHz LPO clock.
367 *
368 * @param base RTC peripheral base address
369 * @param enable Enable/Disable RTC 1kHz LPO clock
370 *
371 * @note After setting this bit, RTC prescaler increments using the LPO 1kHz clock
372 * and not the RTC 32kHz crystal clock.
373 */
RTC_EnableLPOClock(RTC_Type * base,bool enable)374 static inline void RTC_EnableLPOClock(RTC_Type *base, bool enable)
375 {
376 if (enable)
377 {
378 base->CR |= RTC_CR_LPOS_MASK;
379 }
380 else
381 {
382 base->CR &= ~RTC_CR_LPOS_MASK;
383 }
384 }
385
386 #endif /* FSL_FEATURE_RTC_HAS_LPO_ADJUST */
387
388 /*! @}*/
389
390 #if (defined(FSL_FEATURE_RTC_HAS_TTSR) && FSL_FEATURE_RTC_HAS_TTSR)
391
392 /*!
393 * @brief Get the RTC tamper time seconds.
394 *
395 * @param base RTC peripheral base address
396 */
RTC_GetTamperTimeSeconds(RTC_Type * base)397 static inline uint32_t RTC_GetTamperTimeSeconds(RTC_Type *base)
398 {
399 return base->TTSR;
400 }
401
402 #endif /* FSL_FEATURE_RTC_HAS_TTSR */
403
404 /*!
405 * @name Timer Start and Stop
406 * @{
407 */
408
409 /*!
410 * @brief Starts the RTC time counter.
411 *
412 * After calling this function, the timer counter increments once a second provided SR[TOF] or
413 * SR[TIF] are not set.
414 *
415 * @param base RTC peripheral base address
416 */
RTC_StartTimer(RTC_Type * base)417 static inline void RTC_StartTimer(RTC_Type *base)
418 {
419 base->SR |= RTC_SR_TCE_MASK;
420 }
421
422 /*!
423 * @brief Stops the RTC time counter.
424 *
425 * RTC's seconds register can be written to only when the timer is stopped.
426 *
427 * @param base RTC peripheral base address
428 */
RTC_StopTimer(RTC_Type * base)429 static inline void RTC_StopTimer(RTC_Type *base)
430 {
431 base->SR &= ~RTC_SR_TCE_MASK;
432 }
433
434 /*! @}*/
435
436 #if (defined(FSL_FEATURE_RTC_HAS_OSC_SCXP) && FSL_FEATURE_RTC_HAS_OSC_SCXP)
437
438 /*!
439 * @brief This function sets the specified capacitor configuration for the RTC oscillator.
440 *
441 * @param base RTC peripheral base address
442 * @param capLoad Oscillator loads to enable. This is a logical OR of members of the
443 * enumeration ::rtc_osc_cap_load_t
444 */
RTC_SetOscCapLoad(RTC_Type * base,uint32_t capLoad)445 static inline void RTC_SetOscCapLoad(RTC_Type *base, uint32_t capLoad)
446 {
447 uint32_t reg = base->CR;
448
449 reg &= ~(RTC_CR_SC2P_MASK | RTC_CR_SC4P_MASK | RTC_CR_SC8P_MASK | RTC_CR_SC16P_MASK);
450 reg |= capLoad;
451
452 base->CR = reg;
453 }
454
455 #endif /* FSL_FEATURE_SCG_HAS_OSC_SCXP */
456
457 /*!
458 * @brief Performs a software reset on the RTC module.
459 *
460 * This resets all RTC registers except for the SWR bit and the RTC_WAR and RTC_RAR
461 * registers. The SWR bit is cleared by software explicitly clearing it.
462 *
463 * @param base RTC peripheral base address
464 */
RTC_Reset(RTC_Type * base)465 static inline void RTC_Reset(RTC_Type *base)
466 {
467 base->CR |= RTC_CR_SWR_MASK;
468 base->CR &= ~RTC_CR_SWR_MASK;
469
470 /* Set TSR register to 0x1 to avoid the timer invalid (TIF) bit being set in the SR register */
471 base->TSR = 1U;
472 }
473
474 #if defined(FSL_FEATURE_RTC_HAS_MONOTONIC) && (FSL_FEATURE_RTC_HAS_MONOTONIC)
475
476 /*!
477 * @name Monotonic counter functions
478 * @{
479 */
480
481 /*!
482 * @brief Reads the values of the Monotonic Counter High and Monotonic Counter Low and returns
483 * them as a single value.
484 *
485 * @param base RTC peripheral base address
486 * @param counter Pointer to variable where the value is stored.
487 */
488 void RTC_GetMonotonicCounter(RTC_Type *base, uint64_t *counter);
489
490 /*!
491 * @brief Writes values Monotonic Counter High and Monotonic Counter Low by decomposing
492 * the given single value. The Monotonic Overflow Flag in RTC_SR is cleared due to the API.
493 *
494 * @param base RTC peripheral base address
495 * @param counter Counter value
496 */
497 void RTC_SetMonotonicCounter(RTC_Type *base, uint64_t counter);
498
499 /*!
500 * @brief Increments the Monotonic Counter by one.
501 *
502 * Increments the Monotonic Counter (registers RTC_MCLR and RTC_MCHR accordingly) by setting
503 * the monotonic counter enable (MER[MCE]) and then writing to the RTC_MCLR register. A write to the
504 * monotonic counter low that causes it to overflow also increments the monotonic counter high.
505 *
506 * @param base RTC peripheral base address
507 *
508 * @return kStatus_Success: success
509 * kStatus_Fail: error occurred, either time invalid or monotonic overflow flag was found
510 */
511 status_t RTC_IncrementMonotonicCounter(RTC_Type *base);
512
513 /*! @}*/
514
515 #endif /* FSL_FEATURE_RTC_HAS_MONOTONIC */
516
517 #if defined(FSL_FEATURE_RTC_HAS_WAKEUP_PIN) && (FSL_FEATURE_RTC_HAS_WAKEUP_PIN)
518 /*!
519 * @brief Enables or disables the RTC Wakeup Pin Operation.
520 *
521 * This function enable or disable RTC Wakeup Pin.
522 * The wakeup pin is optional and not available on all devices.
523 *
524 * @param base RTC_Type base pointer.
525 * @param enable true to enable, false to disable.
526 */
RTC_EnableWakeUpPin(RTC_Type * base,bool enable)527 static inline void RTC_EnableWakeUpPin(RTC_Type *base, bool enable)
528 {
529 if (enable)
530 {
531 base->CR |= RTC_CR_WPE_MASK;
532 }
533 else
534 {
535 base->CR &= ~RTC_CR_WPE_MASK;
536 }
537 }
538 #endif
539
540 #if defined(__cplusplus)
541 }
542 #endif
543
544 /*! @}*/
545
546 #endif /* FSL_RTC_H_ */
547
