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