1 /*
2 * Copyright (c) 2015, Freescale Semiconductor, Inc.
3 * Copyright 2016-2019 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, 2, 1)) /*!< Version 2.2.1 */
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 kRTC_SecondsInterruptEnable = (1U << 3U), /*!< Seconds interrupt.*/
34 #if defined(FSL_FEATURE_RTC_HAS_MONOTONIC) && (FSL_FEATURE_RTC_HAS_MONOTONIC)
35 kRTC_MonotonicOverflowInterruptEnable = (1U << 4U), /*!< Monotonic Overflow Interrupt Enable */
36 #endif /* FSL_FEATURE_RTC_HAS_MONOTONIC */
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 #if !(defined(FSL_FEATURE_RTC_HAS_NO_CR_OSCE) && FSL_FEATURE_RTC_HAS_NO_CR_OSCE)
319 /*!
320 * @brief Set RTC clock source.
321 *
322 * @param base RTC peripheral base address
323 *
324 * @note After setting this bit, wait the oscillator startup time before enabling
325 * the time counter to allow the 32.768 kHz clock time to stabilize.
326 */
RTC_SetClockSource(RTC_Type * base)327 static inline void RTC_SetClockSource(RTC_Type *base)
328 {
329 /* Enable the RTC 32KHz oscillator */
330 base->CR |= RTC_CR_OSCE_MASK;
331 }
332 #endif /* FSL_FEATURE_RTC_HAS_NO_CR_OSCE */
333
334 #if (defined(FSL_FEATURE_RTC_HAS_TTSR) && FSL_FEATURE_RTC_HAS_TTSR)
335
336 /*!
337 * @brief Get the RTC tamper time seconds.
338 *
339 * @param base RTC peripheral base address
340 */
RTC_GetTamperTimeSeconds(RTC_Type * base)341 static inline uint32_t RTC_GetTamperTimeSeconds(RTC_Type *base)
342 {
343 return base->TTSR;
344 }
345
346 #endif /* FSL_FEATURE_RTC_HAS_TTSR */
347
348 /*!
349 * @name Timer Start and Stop
350 * @{
351 */
352
353 /*!
354 * @brief Starts the RTC time counter.
355 *
356 * After calling this function, the timer counter increments once a second provided SR[TOF] or
357 * SR[TIF] are not set.
358 *
359 * @param base RTC peripheral base address
360 */
RTC_StartTimer(RTC_Type * base)361 static inline void RTC_StartTimer(RTC_Type *base)
362 {
363 base->SR |= RTC_SR_TCE_MASK;
364 }
365
366 /*!
367 * @brief Stops the RTC time counter.
368 *
369 * RTC's seconds register can be written to only when the timer is stopped.
370 *
371 * @param base RTC peripheral base address
372 */
RTC_StopTimer(RTC_Type * base)373 static inline void RTC_StopTimer(RTC_Type *base)
374 {
375 base->SR &= ~RTC_SR_TCE_MASK;
376 }
377
378 /*! @}*/
379
380 #if (defined(FSL_FEATURE_RTC_HAS_OSC_SCXP) && FSL_FEATURE_RTC_HAS_OSC_SCXP)
381
382 /*!
383 * @brief This function sets the specified capacitor configuration for the RTC oscillator.
384 *
385 * @param base RTC peripheral base address
386 * @param capLoad Oscillator loads to enable. This is a logical OR of members of the
387 * enumeration ::rtc_osc_cap_load_t
388 */
RTC_SetOscCapLoad(RTC_Type * base,uint32_t capLoad)389 static inline void RTC_SetOscCapLoad(RTC_Type *base, uint32_t capLoad)
390 {
391 uint32_t reg = base->CR;
392
393 reg &= ~(RTC_CR_SC2P_MASK | RTC_CR_SC4P_MASK | RTC_CR_SC8P_MASK | RTC_CR_SC16P_MASK);
394 reg |= capLoad;
395
396 base->CR = reg;
397 }
398
399 #endif /* FSL_FEATURE_SCG_HAS_OSC_SCXP */
400
401 /*!
402 * @brief Performs a software reset on the RTC module.
403 *
404 * This resets all RTC registers except for the SWR bit and the RTC_WAR and RTC_RAR
405 * registers. The SWR bit is cleared by software explicitly clearing it.
406 *
407 * @param base RTC peripheral base address
408 */
RTC_Reset(RTC_Type * base)409 static inline void RTC_Reset(RTC_Type *base)
410 {
411 base->CR |= RTC_CR_SWR_MASK;
412 base->CR &= ~RTC_CR_SWR_MASK;
413
414 /* Set TSR register to 0x1 to avoid the timer invalid (TIF) bit being set in the SR register */
415 base->TSR = 1U;
416 }
417
418 #if defined(FSL_FEATURE_RTC_HAS_MONOTONIC) && (FSL_FEATURE_RTC_HAS_MONOTONIC)
419
420 /*!
421 * @name Monotonic counter functions
422 * @{
423 */
424
425 /*!
426 * @brief Reads the values of the Monotonic Counter High and Monotonic Counter Low and returns
427 * them as a single value.
428 *
429 * @param base RTC peripheral base address
430 * @param counter Pointer to variable where the value is stored.
431 */
432 void RTC_GetMonotonicCounter(RTC_Type *base, uint64_t *counter);
433
434 /*!
435 * @brief Writes values Monotonic Counter High and Monotonic Counter Low by decomposing
436 * the given single value. The Monotonic Overflow Flag in RTC_SR is cleared due to the API.
437 *
438 * @param base RTC peripheral base address
439 * @param counter Counter value
440 */
441 void RTC_SetMonotonicCounter(RTC_Type *base, uint64_t counter);
442
443 /*!
444 * @brief Increments the Monotonic Counter by one.
445 *
446 * Increments the Monotonic Counter (registers RTC_MCLR and RTC_MCHR accordingly) by setting
447 * the monotonic counter enable (MER[MCE]) and then writing to the RTC_MCLR register. A write to the
448 * monotonic counter low that causes it to overflow also increments the monotonic counter high.
449 *
450 * @param base RTC peripheral base address
451 *
452 * @return kStatus_Success: success
453 * kStatus_Fail: error occurred, either time invalid or monotonic overflow flag was found
454 */
455 status_t RTC_IncrementMonotonicCounter(RTC_Type *base);
456
457 /*! @}*/
458
459 #endif /* FSL_FEATURE_RTC_HAS_MONOTONIC */
460
461 #if defined(FSL_FEATURE_RTC_HAS_WAKEUP_PIN) && (FSL_FEATURE_RTC_HAS_WAKEUP_PIN)
462 /*!
463 * @brief Enables or disables the RTC Wakeup Pin Operation.
464 *
465 * This function enable or disable RTC Wakeup Pin.
466 * The wakeup pin is optional and not available on all devices.
467 *
468 * @param base RTC_Type base pointer.
469 * @param enable true to enable, false to disable.
470 */
RTC_EnableWakeUpPin(RTC_Type * base,bool enable)471 static inline void RTC_EnableWakeUpPin(RTC_Type *base, bool enable)
472 {
473 if (enable)
474 {
475 base->CR |= RTC_CR_WPE_MASK;
476 }
477 else
478 {
479 base->CR &= ~RTC_CR_WPE_MASK;
480 }
481 }
482 #endif
483
484 #if defined(__cplusplus)
485 }
486 #endif
487
488 /*! @}*/
489
490 #endif /* _FSL_RTC_H_ */
491
