1 /***************************************************************************//**
2 * \file cy_rtc.h
3 * \version 2.70
4 *
5 * This file provides constants and parameter values for the APIs for the
6 * Real-Time Clock (RTC).
7 *
8 ********************************************************************************
9 * \copyright
10 * Copyright (c) (2016-2022), Cypress Semiconductor Corporation (an Infineon company) or
11 * an affiliate of Cypress Semiconductor Corporation.
12 * SPDX-License-Identifier: Apache-2.0
13 *
14 * Licensed under the Apache License, Version 2.0 (the "License");
15 * you may not use this file except in compliance with the License.
16 * You may obtain a copy of the License at
17 *
18 * http://www.apache.org/licenses/LICENSE-2.0
19 *
20 * Unless required by applicable law or agreed to in writing, software
21 * distributed under the License is distributed on an "AS IS" BASIS,
22 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
23 * See the License for the specific language governing permissions and
24 * limitations under the License.
25 *
26 *******************************************************************************/
27
28 /**
29 * \addtogroup group_rtc
30 * \{
31 *
32 * The Real-Time Clock (RTC) driver provides an application interface
33 * for keeping track of time and date.
34 *
35 * The functions and other declarations used in this driver are in cy_rtc.h.
36 * You can include cy_pdl.h to get access to all functions
37 * and declarations in the PDL.
38 *
39 * Use the RTC driver when the system requires the current time or date. You
40 * can also use the RTC when you do not need the current time and date but you
41 * do need accurate timing of events with one-second resolution.
42 *
43 * The RTC driver provides these features:
44 * * Different hour format support.
45 * * Multiple alarm function (two-alarms).
46 * * Daylight Savings Time (DST) support.
47 * * Automatic leap year compensation.
48 * * Option to drive the RTC by an external 50 Hz or 60 Hz clock source
49 *
50 * The RTC driver provides access to the HW real-time clock. The HW RTC is
51 * located in the Backup domain. You need to choose the clock source for the
52 * Backup domain using the Cy_SysClk_ClkBakSetSource() function. If the clock
53 * for the Backup domain is set and enabled, the RTC automatically
54 * starts counting.
55 *
56 * The RTC driver keeps track of second, minute, hour, day of the week, day of
57 * the month, month, and year.
58 *
59 * DST may be enabled and supports any start and end date. The start and end
60 * dates can be a fixed date (like 24 March) or a relative date (like the
61 * second Sunday in March).
62 *
63 * The RTC has two alarms that you can configure to generate an interrupt.
64 * You specify the match value for the time when you want the alarm to occur.
65 * Your interrupt handler then handles the response. The alarm flexibility
66 * supports periodic alarms (such as every minute), or a single alarm
67 * (13:45 on 28 September, 2043).
68 *
69 * <b> Clock Source </b>
70 *
71 * The Backup domain can be driven by:
72 * * Watch-crystal oscillator (WCO). This is a high-accuracy oscillator that is
73 * suitable for RTC applications and requires a 32.768 kHz external crystal
74 * populated on the application board. The WCO can be supplied by Backup domain
75 * and therefore can run without Vddd/Vccd present. This can be used to wake the
76 * chip from Hibernate mode.
77 *
78 * * The Internal Low-speed Oscillator (ILO) routed from Clk_LF or directly
79 * (as alternate backup domain clock source). Depending on the device power
80 * mode the alternate backup domain clock source is set. For example, for
81 * Deep Sleep mode the ILO is routed through Clk_LF. But for Hibernate
82 * power mode the ILO is set directly. Note that, the ILO should be configured to
83 * work in the Hibernate mode. For more info refer to the \ref group_sysclk
84 * driver. The ILO is a low-accuracy RC-oscillator that does not require
85 * any external elements on the board. Its poor accuracy (+/- 30%) means it is
86 * less useful for the RTC. However, current can be supplied by an internal
87 * power supply (Vback) and therefore it can run without Vddd/Vccd present.
88 * This also can be used to wake the chip from Hibernate mode using RTC alarm
89 * interrupt. For more details refer to \ref group_syspm driver description.
90 *
91 * * The Precision Internal Low-speed Oscillator (PILO), routed from Clk_LF
92 * (alternate backup domain clock source). This is an RC-oscillator (ILO) that
93 * can achieve accuracy of +/- 2% with periodic calibration. It is not expected
94 * to be accurate enough for good RTC capability. The PILO requires
95 * Vddd/Vccd present. It can be used in modes down to Deep Sleep, but ceases to
96 * function in Hibernate mode.
97 *
98 * * External 50 Hz or 60 Hz sine-wave clock source or 32.768 kHz square clock
99 * source.
100 * For example, the wall AC frequency can be the clock source. Such a clock
101 * source can be used if the external 32.768 kHz WCO is absent from the board.
102 * For more details, refer to the Cy_RTC_SelectFrequencyPrescaler() function
103 * description.
104 *
105 * The WCO is the recommended clock source for the RTC, if it is present
106 * in design. For setting the Backup domain clock source, refer to the
107 * \ref group_sysclk driver.
108 *
109 * \note If the WCO is enabled, it should source the Backup domain directly.
110 * Do not route the WCO through the Clk_LF. This is because Clk_LF is not
111 * available in all low-power modes.
112 *
113 * \section group_rtc_section_configuration Configuration Considerations
114 *
115 * Before RTC set up, ensure that the Backup domain is clocked with the desired
116 * clock source.
117 *
118 * To set up an RTC, provide the configuration parameters in the
119 * cy_stc_rtc_config_t structure. Then call Cy_RTC_Init(). You can also set the
120 * date and time at runtime. Call Cy_RTC_SetDateAndTime() using the filled
121 * cy_stc_rtc_config_t structure, or call Cy_RTC_SetDateAndTimeDirect() with
122 * valid time and date values.
123 *
124 * <b> RTC Interrupt Handling </b>
125 *
126 * The RTC driver provides three interrupt handler functions:
127 * Cy_RTC_Alarm1Interrupt(), Cy_RTC_Alarm2Interrupt(), and
128 * Cy_RTC_CenturyInterrupt(). All three functions are blank functions with
129 * the WEAK attribute. For any interrupt you use, redefine the interrupt handler
130 * in your source code.
131 *
132 * When an interrupt occurs, call the Cy_RTC_Interrupt() function. The RTC
133 * hardware provides a single interrupt line to the NVIC for the three RTC
134 * interrupts. This function checks the interrupt register to determine which
135 * interrupt (out of the three) was generated. It then calls the
136 * appropriate handler.
137 *
138 * \warning The Cy_RTC_Alarm2Interrupt() is not called if the DST feature is
139 * enabled. If DST is enabled, the Cy_RTC_Interrupt() function redirects that
140 * interrupt to manage daylight savings time using Cy_RTC_DstInterrupt().
141 * In general, the RTC interrupt handler function the Cy_RTC_DstInterrupt()
142 * function is called instead of Cy_RTC_Alarm2Interrupt().
143 *
144 * For RTC interrupt handling, the user should:
145 * -# Implement strong interrupt handling function(s) for the required events
146 * (see above). If DST is enabled, then Alarm2 is not available. The DST handler
147 * is built into the PDL.
148 * -# Implement an RTC interrupt handler and call Cy_RTC_Interrupt()
149 * from there.
150 * -# Configure the RTC interrupt:
151 * - Set the mask for RTC required interrupt using
152 * Cy_RTC_SetInterruptMask().
153 * - Initialize the RTC interrupt by setting priority and the RTC interrupt
154 * vector using the Cy_SysInt_Init() function.
155 * - Enable the RTC interrupt using the CMSIS core function NVIC_EnableIRQ().
156 *
157 * <b> Alarm functionality </b>
158 *
159 * To set up an alarm, enable the required RTC interrupt. Then provide the
160 * configuration parameters in the cy_stc_rtc_alarm_t structure. You enable
161 * any item you want matched, and provide a match value. You disable any other.
162 * You do not need to set match values for disabled elements, as they are
163 * ignored.
164 * \note The alarm itself must be enabled in this structure. When a match
165 * occurs, the alarm is triggered and your interrupt handler is called.
166 *
167 * An example is the best way to explain how this works. If you want an alarm
168 * on every hour, then in the cy_stc_rtc_alarm_t structure, you provide
169 * these values:
170 *
171 * Alarm_1.sec = 0u \n
172 * Alarm_1.secEn = CY_RTC_ALARM_ENABLE \n
173 * Alarm_1.min = 0u \n
174 * Alarm_1.minEn = CY_RTC_ALARM_ENABLE \n
175 * Alarm_1.hourEn = CY_RTC_ALARM_DISABLE \n
176 * Alarm_1.dayOfWeekEn = CY_RTC_ALARM_DISABLE \n
177 * Alarm_1.dateEn = CY_RTC_ALARM_DISABLE \n
178 * Alarm_1.monthEn = CY_RTC_ALARM_DISABLE \n
179 * Alarm_1.almEn = CY_RTC_ALARM_ENABLE \n
180 *
181 * With this setup, every time both the second and minute are zero, Alarm1 is
182 * asserted. That happens once per hour. Note that, counterintuitively, to have
183 * an alarm every hour, Alarm_1.hourEn is disabled. This is disabled because
184 * for an hourly alarm you do not match the value of the hour.
185 *
186 * After cy_stc_rtc_alarm_t structure is filled, call the
187 * Cy_RTC_SetAlarmDateAndTime(). The alarm can also be set without using the
188 * cy_stc_rtc_alarm_t structure. Call Cy_RTC_SetAlarmDateAndTimeDirect() with
189 * valid values.
190 *
191 * <b> The DST Feature </b>
192 *
193 * The DST feature is managed by the PDL using the RTC Alarm2 interrupt.
194 * Therefore, you cannot have both DST enabled and use the Alarm2 interrupt.
195 *
196 * To set up the DST, route the RTC interrupt to NVIC:
197 *
198 * -# Initialize the RTC interrupt by setting priority and the RTC interrupt
199 * vector using Cy_SysInt_Init().
200 * -# Enable the RTC interrupt using the CMSIS core function NVIC_EnableIRQ().
201 *
202 * After this, provide the configuration parameters in the
203 * cy_stc_rtc_dst_t structure. This structure consists of two
204 * cy_stc_rtc_dst_format_t structures, one for DST Start time and one for
205 * DST Stop time. You also specify whether these times are absolute or relative.
206 *
207 * After the cy_stc_rtc_dst_t structure is filled, call Cy_RTC_EnableDstTime()
208 *
209 * \section group_rtc_lp Low Power Support
210 * The RTC provides the callback functions to facilitate
211 * the low-power mode transition. The callback
212 * \ref Cy_RTC_DeepSleepCallback must be called during execution
213 * of \ref Cy_SysPm_CpuEnterDeepSleep, \ref Cy_RTC_HibernateCallback must be
214 * called during execution of \ref Cy_SysPm_SystemEnterHibernate.
215 * To trigger the callback execution, the callback must be registered
216 * before calling the mode transition function.
217 * Refer to \ref group_syspm driver for more
218 * information about low-power mode transitions.
219 *
220 * \section group_rtc_section_more_information More Information
221 *
222 * For more information on the RTC peripheral, refer to the technical reference
223 * manual (TRM).
224 *
225 * \section group_rtc_changelog Changelog
226 * <table class="doxtable">
227 * <tr><th>Version</th><th>Changes</th><th>Reason for Change</th></tr>
228 * <tr>
229 * <td>2.70</td>
230 * <td>Enhanced API's : Cy_RTC_SetDateAndTime(), Cy_RTC_SetDateAndTimeDirect(), Cy_RTC_SetAlarmDateAndTime(), Cy_RTC_SetAlarmDateAndTimeDirect().</td>
231 * <td>Minor Enhancements to the Driver.</td>
232 * </tr>
233 * <tr>
234 * <td>2.60</td>
235 * <td>CAT1B, CAT1C, CAT1D devices support.<br>Newly added API's Cy_RTC_WriteEnable() to Set/Clear writeable option for RTC user registers,
236 * Cy_RTC_EnableDstTime() to set the DST time and configure the ALARM2 interrupt register
237 * with the appropriate DST time, Cy_RTC_DstInterrupt() to handle the DST event.
238 * <br>Added a delay in Cy_RTC_SyncFromRtc() to check the RTC busy status.</td>
239 * <td>Support for new devices.</td>
240 * </tr>
241 * <tr>
242 * <td>2.50</td>
243 * <td>Removed the calls that convert among BCD and Binary.</td>
244 * <td>RTC encoding changed from BCD to Binary.</td>
245 * </tr>
246 * <tr>
247 * <td>2.40</td>
248 * <td>Fixed/Documented MISRA 2012 violations.</td>
249 * <td>MISRA 2012 compliance.</td>
250 * </tr>
251 * <tr>
252 * <td>2.30.1</td>
253 * <td>Minor documentation updates.</td>
254 * <td>Documentation enhancement.</td>
255 * </tr>
256 * <tr>
257 * <td>2.30</td>
258 * <td>
259 * * Corrected the Cy_RTC_GetDstStatus() and Cy_RTC_SetNextDstTime()
260 * documentation.
261 * * Fixed the Cy_RTC_GetDstStatus() behaviour in the 'an hour before/after the DST stop event' period.
262 * </td>
263 * <td>
264 * * Collateral Review: user experience enhancement.
265 * * Bug fix.
266 * </td>
267 * </tr>
268 * <tr>
269 * <td>2.20.1</td>
270 * <td>Modified header guard CY_IP_MXS40SRSS_RTC.</td>
271 * <td>To enable the PDL compilation with wounded out IP blocks.</td>
272 * </tr>
273 * <tr>
274 * <td rowspan="3">2.20</td>
275 * <td>Flattened the organization of the driver source code into the single
276 * source directory and the single include directory.
277 * </td>
278 * <td>Driver library directory-structure simplification.</td>
279 * </tr>
280 * <tr>
281 * <td>Added register access layer. Use register access macros instead
282 * of direct register access using dereferenced pointers.</td>
283 * <td>Makes register access device-independent, so that the PDL does
284 * not need to be recompiled for each supported part number.</td>
285 * </tr>
286 * <tr>
287 * <td>Documentation update.</td>
288 * <td>Documentation enhancement.</td>
289 * </tr>
290 * <tr>
291 * <td>2.10</td>
292 * <td>
293 * * Corrected Cy_RTC_SetDateAndTimeDirect(), Cy_RTC_SetNextDstTime()
294 * function.
295 * * Corrected internal macro.
296 * * Documentation updates.
297 * </td>
298 * <td>
299 * * Incorrect behavior of \ref Cy_RTC_SetDateAndTimeDirect() and
300 * \ref Cy_RTC_SetNextDstTime() work in debug mode.
301 * * Debug assert correction in \ref Cy_RTC_ConvertDayOfWeek,
302 * \ref Cy_RTC_IsLeapYear, \ref Cy_RTC_DaysInMonth.
303 * </td>
304 * </tr>
305 * <tr>
306 * <td>2.0</td>
307 * <td>
308 * Enhancement and defect fixes:
309 * * Added input parameter(s) validation to all public functions.
310 * * Removed "Cy_RTC_" prefixes from the internal functions names.
311 * * Renamed the elements in the cy_stc_rtc_alarm structure.
312 * * Changed the type of elements with limited set of values, from
313 * uint32_t to enumeration.
314 * </td>
315 * <td></td>
316 * </tr>
317 * <tr>
318 * <td>1.0</td>
319 * <td>Initial version</td>
320 * <td></td>
321 * </tr>
322 * </table>
323 *
324 * \defgroup group_rtc_macros Macros
325 * \defgroup group_rtc_functions Functions
326 * \{
327 * \defgroup group_rtc_general_functions General
328 * \defgroup group_rtc_alarm_functions Alarm
329 * \defgroup group_rtc_dst_functions DST functions
330 * \defgroup group_rtc_low_level_functions Low-Level
331 * \defgroup group_rtc_interrupt_functions Interrupt
332 * \defgroup group_rtc_low_power_functions Low Power Callbacks
333 * \}
334 * \defgroup group_rtc_data_structures Data Structures
335 * \defgroup group_rtc_enums Enumerated Types
336 */
337
338 #if !defined (CY_RTC_H)
339 #define CY_RTC_H
340
341 #include "cy_device.h"
342
343 #if defined (CY_IP_MXS40SRSS_RTC) || defined (CY_IP_MXS28SRSS) || defined (CY_IP_MXS40SSRSS) || defined (CY_IP_MXS22SRSS)
344
345 #include <stdint.h>
346 #include <stddef.h>
347 #include <stdbool.h>
348 #include "cy_syslib.h"
349 #include "cy_syspm.h"
350
351 #if defined(__cplusplus)
352 extern "C" {
353 #endif
354
355 /**
356 * \addtogroup group_rtc_macros
357 * \{
358 */
359
360 /** RTC driver identifier */
361 #define CY_RTC_ID (CY_PDL_DRV_ID(0x28U))
362
363 /** Driver major version */
364 #define CY_RTC_DRV_VERSION_MAJOR 2
365
366 /** Driver minor version */
367 #define CY_RTC_DRV_VERSION_MINOR 70
368
369 /** RTC driver retry macros */
370 #define CY_RTC_ACCESS_BUSY_RETRY_COUNT (200u)
371
372 /** RTC driver retry delay value */
373 #define CY_RTC_BUSY_RETRY_DELAY_US (1u) /* 1 usec */
374
375 /** \} group_rtc_macros */
376
377 /*******************************************************************************
378 * Enumerated Types
379 *******************************************************************************/
380
381 /**
382 * \addtogroup group_rtc_enums
383 * \{
384 */
385
386 /** RTC status enumeration */
387 typedef enum
388 {
389 CY_RTC_SUCCESS = 0x00U, /**< Successful */
390 CY_RTC_BAD_PARAM = CY_RTC_ID | CY_PDL_STATUS_ERROR | 0x01U, /**< One or more invalid parameters */
391 CY_RTC_TIMEOUT = CY_RTC_ID | CY_PDL_STATUS_ERROR | 0x02U, /**< Time-out occurs */
392 CY_RTC_INVALID_STATE = CY_RTC_ID | CY_PDL_STATUS_ERROR | 0x03U, /**< Operation not setup or is in an improper state */
393 CY_RTC_UNKNOWN = CY_RTC_ID | CY_PDL_STATUS_ERROR | 0xFFU /**< Unknown failure */
394 } cy_en_rtc_status_t;
395
396 /** This enumeration is used to set frequency by changing the it pre-scaler */
397 typedef enum
398 {
399 CY_RTC_FREQ_WCO_32768_HZ, /**< prescaler value for 32.768 kHz oscillator */
400 CY_RTC_FREQ_60_HZ, /**< prescaler value for 60 Hz source */
401 CY_RTC_FREQ_50_HZ, /**< prescaler value for 50 Hz source */
402 } cy_en_rtc_clock_freq_t;
403
404 /** This enumeration is used to set/get information for alarm 1 or alarm 2 */
405 typedef enum cy_en_rtc_alarm
406 {
407 CY_RTC_ALARM_1, /**< Alarm 1 enum */
408 CY_RTC_ALARM_2 /**< Alarm 2 enum */
409 } cy_en_rtc_alarm_t;
410
411 /** This enumeration is used to set/get hours format */
412 typedef enum
413 {
414 CY_RTC_24_HOURS, /**< The 24 hour format */
415 CY_RTC_12_HOURS /**< The 12 hour (AM/PM) format */
416 } cy_en_rtc_hours_format_t;
417
418 /** Enumeration to configure the RTC Write register */
419 typedef enum
420 {
421 CY_RTC_WRITE_DISABLED, /**< Writing the RTC is disabled */
422 CY_RTC_WRITE_ENABLED /**< Writing the RTC is enabled */
423 } cy_en_rtc_write_status_t;
424
425 /** Enumeration used to set/get DST format */
426 typedef enum
427 {
428 CY_RTC_DST_RELATIVE, /**< Relative DST format */
429 CY_RTC_DST_FIXED /**< Fixed DST format */
430 } cy_en_rtc_dst_format_t;
431
432 /** Enumeration to indicate the AM/PM period of day */
433 typedef enum
434 {
435 CY_RTC_AM, /**< AM period of day */
436 CY_RTC_PM /**< PM period of day */
437 } cy_en_rtc_am_pm_t;
438
439 /** Enumeration to enable/disable the RTC alarm on match with required value */
440 typedef enum
441 {
442 CY_RTC_ALARM_DISABLE, /**< Disable alarm on match with required value */
443 CY_RTC_ALARM_ENABLE /**< Enable alarm on match with required value */
444 } cy_en_rtc_alarm_enable_t;
445
446
447 /** Enumeration to list all the clock sources for RTC */
448 /**
449 **/
450 typedef enum
451 {
452 CY_RTC_CLK_SELECT_WCO = 0U, /**< Select WCO as input to RTC */
453 CY_RTC_CLK_SELECT_ALTBAK = 1U, /**< Select ALTBAK as input to RTC */
454 CY_RTC_CLK_SELECT_ILO = 2U, /**< Select ILO as input to RTC */
455 CY_RTC_CLK_SELECT_LPECO_PRESCALER = 3U, /**< Select LPECO_PRESCALER as input to RTC */
456 CY_RTC_CLK_SELECT_PILO = 4U, /**< Select PILO as input to RTC */
457 } cy_en_rtc_clk_select_sources_t;
458
459 /** Enumeration to select the sign of calibration for RTC */
460 /**
461 **/
462 typedef enum
463 {
464 CY_RTC_CALIB_SIGN_NEGATIVE = 0, /**< Negative sign: remove pulses */
465 CY_RTC_CALIB_SIGN_POSITIVE = 1, /**< Positive sign: add pulses */
466 } cy_en_rtc_calib_sign_t;
467
468 /** Enumeration to select the calibration wave output signal */
469 /**
470 **/
471 typedef enum
472 {
473 CY_RTC_CAL_SEL_CAL512 = 0, /**< 512Hz wave, not affected by calibration setting, (not supported for 50/60Hz input clock: CTL.PRESCALER!=0) */
474 CY_RTC_CAL_SEL_CAL2 = 2, /**< 2Hz wave, includes the effect of the calibration setting, (not supported for 50/60Hz input clock: CTL.PRESCALER!=0) */
475 CY_RTC_CAL_SEL_CAL1 = 3, /**< 1Hz wave, includes the effect of the calibration setting (supported for all input clocks) */
476 } cy_en_rtc_calib_sel_t;
477
478 /** \} group_rtc_enums */
479
480
481 /*******************************************************************************
482 * Types definition
483 *******************************************************************************/
484
485 /**
486 * \addtogroup group_rtc_data_structures
487 * \{
488 */
489
490 /**
491 * This is the data structure that is used to configure the rtc time
492 * and date values.
493 */
494 typedef struct cy_stc_rtc_config
495 {
496 /* Time information */
497 uint32_t sec; /**< Seconds value, range [0-59] */
498 uint32_t min; /**< Minutes value, range [0-59] */
499 uint32_t hour; /**< Hour, range depends on hrFormat, if hrFormat = CY_RTC_24_HOURS, range [0-23];
500 If hrFormat = CY_RTC_12_HOURS, range [1-12] and appropriate AM/PM day
501 period should be set (amPm) */
502 cy_en_rtc_am_pm_t amPm; /**< AM/PM hour period, see \ref cy_en_rtc_am_pm_t.
503 This element is actual when hrFormat = CY_RTC_12_HOURS. The firmware
504 ignores this element if hrFormat = CY_RTC_24_HOURS */
505 cy_en_rtc_hours_format_t hrFormat; /**< Hours format, see \ref cy_en_rtc_hours_format_t */
506 uint32_t dayOfWeek; /**< Day of the week, range [1-7], see \ref group_rtc_day_of_the_week */
507
508 /* Date information */
509 uint32_t date; /**< Date of month, range [1-31] */
510 uint32_t month; /**< Month, range [1-12]. See \ref group_rtc_month */
511 uint32_t year; /**< Year, range [0-99] */
512 } cy_stc_rtc_config_t;
513
514 /** Decimal data structure that is used to save the Alarms */
515 typedef struct cy_stc_rtc_alarm
516 {
517 /* Alarm time information */
518 uint32_t sec; /**< Alarm seconds, range [0-59].
519 The appropriate ALARMX interrupt is be asserted on matching with this
520 value if secEn is previous enabled (secEn = 1) */
521 cy_en_rtc_alarm_enable_t secEn; /**< Enable alarm on seconds matching, see \ref cy_en_rtc_alarm_enable_t. */
522
523 uint32_t min; /**< Alarm minutes, range [0-59].
524 The appropriate ALARMX interrupt is be asserted on matching with this
525 value if minEn is previous enabled (minEn = 1) */
526 cy_en_rtc_alarm_enable_t minEn; /**< Enable alarm on minutes matching, see \ref cy_en_rtc_alarm_enable_t. */
527
528 uint32_t hour; /**< Alarm hours, range [0-23]
529 The appropriate ALARMX interrupt is be asserted on matching with this
530 value if hourEn is previous enabled (hourEn = 1) */
531 cy_en_rtc_alarm_enable_t hourEn; /**< Enable alarm on hours matching, see \ref cy_en_rtc_alarm_enable_t. */
532
533 uint32_t dayOfWeek; /**< Alarm day of the week, range [1-7]
534 The appropriate ALARMX interrupt is be asserted on matching with this
535 value if dayOfWeek is previous enabled (dayOfWeekEn = 1) */
536 cy_en_rtc_alarm_enable_t dayOfWeekEn; /**< Enable alarm on day of the week matching,
537 see \ref cy_en_rtc_alarm_enable_t */
538
539 /* Alarm date information */
540 uint32_t date; /**< Alarm date, range [1-31].
541 The appropriate ALARMX interrupt is be asserted on matching with this
542 value if dateEn is previous enabled (dateEn = 1) */
543 cy_en_rtc_alarm_enable_t dateEn; /**< Enable alarm on date matching, see \ref cy_en_rtc_alarm_enable_t. */
544
545 uint32_t month; /**< Alarm Month, range [1-12].
546 The appropriate ALARMX interrupt is be asserted on matching with this
547 value if dateEn is previous enabled (dateEn = 1) */
548 cy_en_rtc_alarm_enable_t monthEn; /**< Enable alarm on month matching, see \ref cy_en_rtc_alarm_enable_t. */
549
550 cy_en_rtc_alarm_enable_t almEn; /**< Enable Alarm for appropriate ALARMX, see \ref cy_en_rtc_alarm_enable_t.
551 If all alarm structure elements are enabled (almEn = CY_RTC_ALARM_ENABLE)
552 the alarm interrupt is be asserted every second. */
553 } cy_stc_rtc_alarm_t;
554
555 /**
556 * This is DST structure for DST feature setting. Structure is combined with the
557 * fixed format and the relative format. It is used to save the DST time and date
558 * fixed or relative time format.
559 */
560 typedef struct
561 {
562 cy_en_rtc_dst_format_t format; /**< DST format. See /ref cy_en_rtc_dst_format_t.
563 Based on this value other structure elements
564 should be filled or could be ignored */
565 uint32_t hour; /**< Should be filled for both format types.
566 Hour is always presented in 24hour format, range[0-23] */
567 uint32_t dayOfMonth; /**< Day of Month, range[1-31]. This element should be filled if
568 format = CY_RTC_DST_FIXED. Firmware calculates this value in condition that
569 format = CY_RTC_DST_RELATIVE is selected */
570 uint32_t weekOfMonth; /**< Week of month, range[1-6]. This element should be filled if
571 format = CY_RTC_DST_RELATIVE.
572 Firmware calculates dayOfMonth value based on weekOfMonth
573 and dayOfWeek values */
574 uint32_t dayOfWeek; /**< Day of the week, this element should be filled in condition that
575 format = CY_RTC_DST_RELATIVE. Range[1- 7],
576 see \ref group_rtc_day_of_the_week. Firmware calculates dayOfMonth value
577 based on dayOfWeek and weekOfMonth values */
578 uint32_t month; /**< Month value, range[1-12], see \ref group_rtc_month.
579 This value should be filled for both format types */
580 } cy_stc_rtc_dst_format_t;
581
582 /** This is the DST structure to handle start DST and stop DST */
583 typedef struct
584 {
585 cy_stc_rtc_dst_format_t startDst; /**< DST start time structure */
586 cy_stc_rtc_dst_format_t stopDst; /**< DST stop time structure */
587 } cy_stc_rtc_dst_t;
588
589 /** \} group_rtc_data_structures */
590
591
592 /*******************************************************************************
593 * Function Prototypes
594 *******************************************************************************/
595
596 /**
597 * \addtogroup group_rtc_functions
598 * \{
599 */
600
601 /**
602 * \addtogroup group_rtc_general_functions
603 * \{
604 */
605 cy_en_rtc_status_t Cy_RTC_Init(cy_stc_rtc_config_t const *config);
606 cy_en_rtc_status_t Cy_RTC_SetDateAndTime(cy_stc_rtc_config_t const *dateTime);
607 void Cy_RTC_GetDateAndTime(cy_stc_rtc_config_t *dateTime);
608 cy_en_rtc_status_t Cy_RTC_SetDateAndTimeDirect(uint32_t sec, uint32_t min, uint32_t hour,
609 uint32_t date, uint32_t month, uint32_t year);
610 cy_en_rtc_status_t Cy_RTC_SetHoursFormat(cy_en_rtc_hours_format_t hoursFormat);
611 #if defined (CY_IP_MXS40SRSS_RTC) || defined (CY_IP_MXS40SSRSS) || defined (CY_IP_MXS22SRSS)
612 void Cy_RTC_SelectFrequencyPrescaler(cy_en_rtc_clock_freq_t clkSel);
613 #endif
614 void Cy_RTC_SelectClockSource(cy_en_rtc_clk_select_sources_t clkSel);
615 cy_en_rtc_status_t Cy_RTC_CalibrationControlEnable(uint8_t calib_val, cy_en_rtc_calib_sign_t calib_sign, cy_en_rtc_calib_sel_t calib_sel);
616 cy_en_rtc_status_t Cy_RTC_CalibrationControlDisable(void);
617
618 /** \} group_rtc_general_functions */
619
620 /**
621 * \addtogroup group_rtc_alarm_functions
622 * \{
623 */
624 cy_en_rtc_status_t Cy_RTC_SetAlarmDateAndTime(cy_stc_rtc_alarm_t const *alarmDateTime, cy_en_rtc_alarm_t alarmIndex);
625 void Cy_RTC_GetAlarmDateAndTime(cy_stc_rtc_alarm_t *alarmDateTime, cy_en_rtc_alarm_t alarmIndex);
626 cy_en_rtc_status_t Cy_RTC_SetAlarmDateAndTimeDirect(uint32_t sec, uint32_t min, uint32_t hour,
627 uint32_t date, uint32_t month, cy_en_rtc_alarm_t alarmIndex);
628 /** \} group_rtc_alarm_functions */
629
630 /**
631 * \addtogroup group_rtc_dst_functions
632 * \{
633 */
634 cy_en_rtc_status_t Cy_RTC_EnableDstTime(cy_stc_rtc_dst_t const *dstTime, cy_stc_rtc_config_t const *timeDate);
635 cy_en_rtc_status_t Cy_RTC_SetNextDstTime(cy_stc_rtc_dst_format_t const *nextDst);
636 bool Cy_RTC_GetDstStatus(cy_stc_rtc_dst_t const *dstTime, cy_stc_rtc_config_t const *timeDate);
637 /** \} group_rtc_dst_functions */
638
639 /**
640 * \addtogroup group_rtc_interrupt_functions
641 * \{
642 */
643 void Cy_RTC_Interrupt(cy_stc_rtc_dst_t const *dstTime, bool mode);
644 void Cy_RTC_Alarm1Interrupt(void);
645 void Cy_RTC_Alarm2Interrupt(void);
646 void Cy_RTC_DstInterrupt(cy_stc_rtc_dst_t const *dstTime);
647 void Cy_RTC_CenturyInterrupt(void);
648 uint32_t Cy_RTC_GetInterruptStatus(void);
649 uint32_t Cy_RTC_GetInterruptStatusMasked(void);
650 uint32_t Cy_RTC_GetInterruptMask(void);
651 void Cy_RTC_ClearInterrupt(uint32_t interruptMask);
652 void Cy_RTC_SetInterrupt(uint32_t interruptMask);
653 void Cy_RTC_SetInterruptMask(uint32_t interruptMask);
654 /** \} group_rtc_interrupt_functions */
655
656 /**
657 * \addtogroup group_rtc_low_power_functions
658 * \{
659 */
660 cy_en_syspm_status_t Cy_RTC_DeepSleepCallback(const cy_stc_syspm_callback_params_t *callbackParams, cy_en_syspm_callback_mode_t mode);
661 cy_en_syspm_status_t Cy_RTC_HibernateCallback(const cy_stc_syspm_callback_params_t *callbackParams, cy_en_syspm_callback_mode_t mode);
662 /** \} group_rtc_low_power_functions */
663
664 /**
665 * \addtogroup group_rtc_low_level_functions
666 * \{
667 */
668 __STATIC_INLINE uint32_t Cy_RTC_ConvertDayOfWeek(uint32_t day, uint32_t month, uint32_t year);
669 __STATIC_INLINE bool Cy_RTC_IsLeapYear(uint32_t year);
670 __STATIC_INLINE uint32_t Cy_RTC_DaysInMonth(uint32_t month, uint32_t year);
671 __STATIC_INLINE void Cy_RTC_SyncFromRtc(void);
672 __STATIC_INLINE cy_en_rtc_status_t Cy_RTC_WriteEnable(cy_en_rtc_write_status_t writeEnable);
673 __STATIC_INLINE uint32_t Cy_RTC_GetSyncStatus(void);
674 __STATIC_INLINE cy_en_rtc_hours_format_t Cy_RTC_GetHoursFormat(void);
675 __STATIC_INLINE bool Cy_RTC_IsExternalResetOccurred(void);
676
677 __STATIC_INLINE void Cy_RTC_SyncToRtcAhbDateAndTime(uint32_t timeBcd, uint32_t dateBcd);
678 __STATIC_INLINE void Cy_RTC_SyncToRtcAhbAlarm(uint32_t alarmTimeBcd, uint32_t alarmDateBcd, cy_en_rtc_alarm_t alarmIndex);
679
680 /** \} group_rtc_low_level_functions */
681
682 /** \} group_rtc_functions */
683
684 /**
685 * \addtogroup group_rtc_macros
686 * \{
687 */
688
689 /*******************************************************************************
690 * API Constants
691 *******************************************************************************/
692
693 /**
694 * \defgroup group_rtc_day_of_the_week Day of the week definitions
695 * \{
696 * Definitions of days in the week
697 */
698 #define CY_RTC_SUNDAY (1UL) /**< Sequential number of Sunday in the week */
699 #define CY_RTC_MONDAY (2UL) /**< Sequential number of Monday in the week */
700 #define CY_RTC_TUESDAY (3UL) /**< Sequential number of Tuesday in the week */
701 #define CY_RTC_WEDNESDAY (4UL) /**< Sequential number of Wednesday in the week */
702 #define CY_RTC_THURSDAY (5UL) /**< Sequential number of Thursday in the week */
703 #define CY_RTC_FRIDAY (6UL) /**< Sequential number of Friday in the week */
704 #define CY_RTC_SATURDAY (7UL) /**< Sequential number of Saturday in the week */
705 #define CY_RTC_DAY_AUTO (8UL) /**< Calculate the day of the week for the provided date, month, year automatically */
706 /** \} group_rtc_day_of_the_week */
707
708 /**
709 * \defgroup group_rtc_dst_week_of_month Week of month definitions
710 * \{
711 * Week of Month setting constants definitions for Daylight Saving Time feature
712 */
713 #define CY_RTC_FIRST_WEEK_OF_MONTH (1UL) /**< First week in the month */
714 #define CY_RTC_SECOND_WEEK_OF_MONTH (2UL) /**< Second week in the month */
715 #define CY_RTC_THIRD_WEEK_OF_MONTH (3UL) /**< Third week in the month */
716 #define CY_RTC_FOURTH_WEEK_OF_MONTH (4UL) /**< Fourth week in the month */
717 #define CY_RTC_FIFTH_WEEK_OF_MONTH (5UL) /**< Fifth week in the month */
718 #define CY_RTC_LAST_WEEK_OF_MONTH (6UL) /**< Last week in the month */
719 /** \} group_rtc_dst_week_of_month */
720
721 /**
722 * \defgroup group_rtc_month Month definitions
723 * \{
724 * Constants definition for Months
725 */
726 #define CY_RTC_JANUARY (1UL) /**< Sequential number of January in the year */
727 #define CY_RTC_FEBRUARY (2UL) /**< Sequential number of February in the year */
728 #define CY_RTC_MARCH (3UL) /**< Sequential number of March in the year */
729 #define CY_RTC_APRIL (4UL) /**< Sequential number of April in the year */
730 #define CY_RTC_MAY (5UL) /**< Sequential number of May in the year */
731 #define CY_RTC_JUNE (6UL) /**< Sequential number of June in the year */
732 #define CY_RTC_JULY (7UL) /**< Sequential number of July in the year */
733 #define CY_RTC_AUGUST (8UL) /**< Sequential number of August in the year */
734 #define CY_RTC_SEPTEMBER (9UL) /**< Sequential number of September in the year */
735 #define CY_RTC_OCTOBER (10UL) /**< Sequential number of October in the year */
736 #define CY_RTC_NOVEMBER (11UL) /**< Sequential number of November in the year */
737 #define CY_RTC_DECEMBER (12UL) /**< Sequential number of December in the year */
738 /** \} group_rtc_month */
739
740 /**
741 * \defgroup group_rtc_days_in_month Number of days in month definitions
742 * \{
743 * Definition of days in current month
744 */
745 #define CY_RTC_DAYS_IN_JANUARY (31U) /**< Number of days in January */
746 #define CY_RTC_DAYS_IN_FEBRUARY (28U) /**< Number of days in February */
747 #define CY_RTC_DAYS_IN_MARCH (31U) /**< Number of days in March */
748 #define CY_RTC_DAYS_IN_APRIL (30U) /**< Number of days in April */
749 #define CY_RTC_DAYS_IN_MAY (31U) /**< Number of days in May */
750 #define CY_RTC_DAYS_IN_JUNE (30U) /**< Number of days in June */
751 #define CY_RTC_DAYS_IN_JULY (31U) /**< Number of days in July */
752 #define CY_RTC_DAYS_IN_AUGUST (31U) /**< Number of days in August */
753 #define CY_RTC_DAYS_IN_SEPTEMBER (30U) /**< Number of days in September */
754 #define CY_RTC_DAYS_IN_OCTOBER (31U) /**< Number of days in October */
755 #define CY_RTC_DAYS_IN_NOVEMBER (30U) /**< Number of days in November */
756 #define CY_RTC_DAYS_IN_DECEMBER (31U) /**< Number of days in December */
757 /** \} group_rtc_days_in_month */
758
759 /**
760 * \defgroup group_rtc_macros_interrupts RTC Interrupt sources
761 * \{
762 * Definitions for RTC interrupt sources
763 */
764 /** Alarm 1 status */
765 #define CY_RTC_INTR_ALARM1 BACKUP_INTR_ALARM1_Msk
766
767 /** Alarm 2 status */
768 #define CY_RTC_INTR_ALARM2 BACKUP_INTR_ALARM2_Msk
769
770 /**
771 * This interrupt occurs when the year is reached to 2100 which is rolling
772 * over the year field value from 99 to 0
773 */
774 #define CY_RTC_INTR_CENTURY BACKUP_INTR_CENTURY_Msk
775 /** \} group_rtc_macros_interrupts */
776
777 /**
778 * \defgroup group_rtc_busy_status RTC Status definitions
779 * \{
780 * Definitions for indicating the RTC BUSY bit
781 */
782 #define CY_RTC_BUSY (1UL) /**< RTC Busy bit is set, RTC is pending */
783 #define CY_RTC_AVAILABLE (0UL) /**< RTC Busy bit is cleared, RTC is available */
784 /** \} group_rtc_busy_status */
785
786 /*******************************************************************************
787 * Internal Constants
788 *******************************************************************************/
789
790 /** \cond INTERNAL */
791
792 /** Days per week definition */
793 #define CY_RTC_DAYS_PER_WEEK (7UL)
794
795 /** Month per year definition */
796 #define CY_RTC_MONTHS_PER_YEAR (12U)
797
798 /** Maximum value of seconds and minutes */
799 #define CY_RTC_MAX_SEC_OR_MIN (59UL)
800
801 /** Biggest value of hours definition */
802 #define CY_RTC_MAX_HOURS_24H (23UL)
803
804 /** Maximum value of year definition */
805 #define CY_RTC_MAX_DAYS_IN_MONTH (31UL)
806
807 /** Maximum value of year definition */
808 #define CY_RTC_MAX_YEAR (99UL)
809
810 /** Number of RTC interrupts */
811 #define CY_RTC_NUM_OF_INTR (3U)
812
813 /** Number of RTC interrupts */
814 #define CY_RTC_TRYES_TO_SETUP_DST (24U)
815
816 /** RTC AM/PM bit for 12H hour mode */
817 #if defined (CY_IP_MXS40SSRSS) || defined (CY_IP_MXS40SRSS) && (CY_IP_MXS40SRSS_VERSION >= 3)
818 #define CY_RTC_12HRS_PM_BIT (0x10UL)
819 #else
820 #define CY_RTC_12HRS_PM_BIT (0x20UL)
821 #endif/* CY_IP_MXS40SSRSS */
822
823 /** Mask for reading RTC AM/PM bit for 12H mode */
824 #define CY_RTC_BACKUP_RTC_TIME_RTC_PM ((uint32_t) (CY_RTC_12HRS_PM_BIT << BACKUP_RTC_TIME_RTC_HOUR_Pos))
825
826 /** Internal define for BCD values converting */
827 #define CY_RTC_BCD_NUMBER_SIZE (4UL)
828
829 /** Internal mask for BCD values converting */
830 #define CY_RTC_BCD_ONE_DIGIT_MASK (0x0000000FUL)
831
832 /** Internal define of dozen degree for BCD values converting */
833 #define CY_RTC_BCD_DOZED_DEGREE (10UL)
834
835 /** Internal define of hundred degree for BCD values converting */
836 #define CY_RTC_BCD_HUNDRED_DEGRE (100UL)
837
838 /** Definition of forty two AHB clocks in microseconds */
839 #define CY_RTC_DELAY_WHILE_READING_US ((42000000UL / cy_AhbFreqHz) + 1UL)
840
841 /** Definition of two WCO clocks in microseconds */
842 #define CY_RTC_DELAY_FOR_NEXT_DST (2000U)
843
844 /** Two thousand years definition */
845 #define CY_RTC_TWO_THOUSAND_YEARS (2000UL)
846
847 /** Two thousand years definition */
848 #define CY_RTC_TWENTY_ONE_HUNDRED_YEARS (2100UL)
849
850 /** Mask for reading RTC hour for 12H mode */
851 #if defined (CY_IP_MXS40SSRSS) || defined (CY_IP_MXS40SRSS) && (CY_IP_MXS40SRSS_VERSION >= 3)
852 #define CY_RTC_BACKUP_RTC_TIME_RTC_12HOUR (0xf0000UL)
853 #else
854 #define CY_RTC_BACKUP_RTC_TIME_RTC_12HOUR (0x1f0000UL)
855 #endif/* CY_IP_MXS40SSRSS */
856
857 /** Half day hours definition */
858 #define CY_RTC_HOURS_PER_HALF_DAY (12UL)
859
860 /** First day of the month definition */
861 #define CY_RTC_FIRST_DAY_OF_MONTH (1UL)
862
863 /** Internal definition for DST GetDstStatus() function */
864 #define CY_RTC_DST_MONTH_POSITION (10UL)
865
866 /** Internal definition for DST GetDstStatus() function */
867 #define CY_RTC_DST_DAY_OF_MONTH_POSITION (5UL)
868
869 /** RTC days in months table */
870 extern uint8_t const cy_RTC_daysInMonthTbl[CY_RTC_MONTHS_PER_YEAR];
871
872 /* Internal macro to validate parameters in Cy_RTC_SelectFrequencyPrescaler() function */
873 #if defined (CY_IP_MXS40SRSS_RTC) || defined (CY_IP_MXS40SSRSS) || defined (CY_IP_MXS22SRSS)
874 #define CY_RTC_IS_CLK_VALID(clkSel) (((clkSel) == CY_RTC_FREQ_WCO_32768_HZ) || \
875 ((clkSel) == CY_RTC_FREQ_60_HZ) || \
876 ((clkSel) == CY_RTC_FREQ_50_HZ))
877 #endif
878
879 #if defined (CY_IP_MXS40SRSS_RTC)
880 /* Internal macro to validate parameters in Cy_RTC_SelectClockSource() function */
881 #define CY_RTC_IS_SRC_CLK_SELECT_VALID(clkSel) (((clkSel) == CY_RTC_CLK_SELECT_WCO) || \
882 ((clkSel) == CY_RTC_CLK_SELECT_ALTBAK) || \
883 ((clkSel) == CY_RTC_CLK_SELECT_ILO) || \
884 ((clkSel) == CY_RTC_CLK_SELECT_LPECO_PRESCALER) || \
885 ((clkSel) == CY_RTC_CLK_SELECT_PILO))
886 #endif
887
888 #if defined (CY_IP_MXS28SRSS) || defined (CY_IP_MXS40SSRSS) || defined (CY_IP_MXS22SRSS)
889 /* Internal macro to validate parameters in Cy_RTC_SelectClockSource() function */
890 #define CY_RTC_IS_SRC_CLK_SELECT_VALID(clkSel) (((clkSel) == CY_RTC_CLK_SELECT_WCO) || \
891 ((clkSel) == CY_RTC_CLK_SELECT_ALTBAK) || \
892 ((clkSel) == CY_RTC_CLK_SELECT_ILO) || \
893 ((clkSel) == CY_RTC_CLK_SELECT_PILO))
894 #endif
895
896 /* Internal macro to validate parameters in Cy_RTC_SetHoursFormat() function */
897 #define CY_RTC_IS_HRS_FORMAT_VALID(hoursFormat) (((hoursFormat) == CY_RTC_24_HOURS) || \
898 ((hoursFormat) == CY_RTC_12_HOURS))
899
900 /* Internal macro to validate parameters in Cy_RTC_WriteEnable() function */
901 #define CY_RTC_IS_WRITE_VALID(writeEnable) (((writeEnable) == CY_RTC_WRITE_DISABLED) || \
902 ((writeEnable) == CY_RTC_WRITE_ENABLED))
903
904 /* Internal macro of all possible RTC interrupts */
905 #define CY_RTC_INTR_MASK (CY_RTC_INTR_ALARM1 | CY_RTC_INTR_ALARM2 | CY_RTC_INTR_CENTURY)
906
907 /* Macro to validate parameters in interrupt related functions */
908 #define CY_RTC_INTR_VALID(interruptMask) (0UL == ((interruptMask) & ((uint32_t) ~(CY_RTC_INTR_MASK))))
909
910 /* Internal macro to validate RTC seconds and minutes parameters */
911 #define CY_RTC_IS_SEC_VALID(sec) ((sec) <= CY_RTC_MAX_SEC_OR_MIN)
912
913 /* Internal macro to validate RTC seconds and minutes parameters */
914 #define CY_RTC_IS_MIN_VALID(min) ((min) <= CY_RTC_MAX_SEC_OR_MIN)
915
916 /* Internal macro to validate RTC hour parameter */
917 #define CY_RTC_IS_HOUR_VALID(hour) ((hour) <= CY_RTC_MAX_HOURS_24H)
918
919 /* Internal macro to validate RTC day of the week parameter, To support CY_RTC_DAY_AUTO feature incremented the valid case by 1 */
920 #define CY_RTC_IS_DOW_VALID(dayOfWeek) (((dayOfWeek) > 0U) && ((dayOfWeek) <= (CY_RTC_DAYS_PER_WEEK + 1UL)))
921
922 /* Internal macro to validate RTC day parameter */
923 #define CY_RTC_IS_DAY_VALID(day) (((day) > 0U) && ((day) <= CY_RTC_MAX_DAYS_IN_MONTH))
924
925 /* Internal macro to validate RTC month parameter */
926 #define CY_RTC_IS_MONTH_VALID(month) (((month) > 0U) && ((month) <= CY_RTC_MONTHS_PER_YEAR))
927
928 #define CY_RTC_IS_DATE_VALID(date, DaysInMonth) ((date > 0U) && (date <= DaysInMonth))
929
930 /* Internal macro to validate RTC week day parameter */
931 #define CY_RTC_IS_WEEK_DAY_VALID(dayOfWeek, validDay) ((dayOfWeek == CY_RTC_DAY_AUTO) ? true : (dayOfWeek == validDay))
932
933 /* Internal macro to validate RTC year parameter */
934 #define CY_RTC_IS_YEAR_SHORT_VALID(year) ((year) <= CY_RTC_MAX_YEAR)
935
936 /* Internal macro to validate the year value in the Cy_RTC_ConvertDayOfWeek() */
937 #define CY_RTC_IS_YEAR_LONG_VALID(year) ((year) > 0U)
938
939 /* Internal macro to validate RTC alarm parameter */
940 #define CY_RTC_IS_ALARM_EN_VALID(alarmEn) (((alarmEn) == CY_RTC_ALARM_DISABLE) || \
941 ((alarmEn) == CY_RTC_ALARM_ENABLE))
942
943 /* Internal macro to validate RTC alarm index parameter */
944 #define CY_RTC_IS_ALARM_IDX_VALID(alarmIndex) (((alarmIndex) == CY_RTC_ALARM_1) || ((alarmIndex) == CY_RTC_ALARM_2))
945
946 /* Internal macro to validate RTC alarm index parameter */
947 #define CY_RTC_IS_DST_FORMAT_VALID(format) (((format) == CY_RTC_DST_RELATIVE) || ((format) == CY_RTC_DST_FIXED))
948
949 /** \endcond */
950 /** \} group_rtc_macros */
951
952 /**
953 * \addtogroup group_rtc_low_level_functions
954 * \{
955 */
956
957 /*******************************************************************************
958 * Function Name: Cy_RTC_ConvertDayOfWeek
959 ****************************************************************************//**
960 *
961 * Returns a day of the week for a year, month, and day of month that are passed
962 * through parameters. Zeller's congruence is used to calculate the day of
963 * the week.
964 * RTC HW block does not provide the converting function for day of week. This
965 * function should be called before Cy_RTC_SetDateAndTime() to get the day of
966 * week.
967 *
968 * For the Georgian calendar, Zeller's congruence is:
969 * h = (q + [13 * (m + 1)] + K + [K/4] + [J/4] - 2J) mod 7
970 *
971 * h - The day of the week (0 = Saturday, 1 = Sunday, 2 = Monday, ., 6 = Friday).
972 * q - The day of the month.
973 * m - The month (3 = March, 4 = April, 5 = May, ..., 14 = February)
974 * K - The year of the century (year mod 100).
975 * J - The zero-based century (actually [year/100]) For example, the zero-based
976 * centuries for 1995 and 2000 are 19 and 20 respectively (not to be
977 * confused with the common ordinal century enumeration which indicates
978 * 20th for both cases).
979 *
980 * \note In this algorithm January and February are counted as months 13 and 14
981 * of the previous year.
982 *
983 * \param day
984 * The day of the month, Valid range 1..31.
985 *
986 * \param month
987 * The month of the year, see \ref group_rtc_month.
988 *
989 * \param year
990 * The year value. Valid range non-zero value.
991 *
992 * \return
993 * Returns a day of the week, see \ref group_rtc_day_of_the_week.
994 *
995 *******************************************************************************/
Cy_RTC_ConvertDayOfWeek(uint32_t day,uint32_t month,uint32_t year)996 __STATIC_INLINE uint32_t Cy_RTC_ConvertDayOfWeek(uint32_t day, uint32_t month, uint32_t year)
997 {
998 uint32_t retVal;
999
1000 CY_ASSERT_L2(CY_RTC_IS_DAY_VALID(day));
1001 CY_ASSERT_L2(CY_RTC_IS_MONTH_VALID(month));
1002 CY_ASSERT_L2(CY_RTC_IS_YEAR_LONG_VALID(year));
1003
1004 /* Converts month number from regular convention
1005 * (1=January,..., 12=December) to convention required for this
1006 * algorithm (January and February are counted as months 13 and 14 of
1007 * previous year).
1008 */
1009 if (month < CY_RTC_MARCH)
1010 {
1011 month = CY_RTC_MONTHS_PER_YEAR + month;
1012 year--;
1013 }
1014
1015 /* Calculates Day of Week using Zeller's congruence algorithms */
1016 retVal =
1017 (day + (((month + 1UL) * 26UL) / 10UL) + year + (year / 4UL) + (6UL * (year / 100UL)) + (year / 400UL)) % 7UL;
1018
1019 /* Makes correction for Saturday. Saturday number should be 7 instead of 0*/
1020 if (0u == retVal)
1021 {
1022 retVal = CY_RTC_SATURDAY;
1023 }
1024
1025 return(retVal);
1026 }
1027
1028
1029 /*******************************************************************************
1030 * Function Name: Cy_RTC_IsLeapYear
1031 ****************************************************************************//**
1032 *
1033 * Checks whether the year passed through the parameter is leap or not.
1034 *
1035 * This API is for checking an invalid value input for leap year.
1036 * RTC HW block does not provide a validation checker against time/date values,
1037 * the valid range of days in Month should be checked before SetDateAndTime()
1038 * function call. Leap year is identified as a year that is a multiple of 4
1039 * or 400 but not 100.
1040 *
1041 * \param year
1042 * The year to be checked. Valid range non-zero value.
1043 *
1044 * \return
1045 * False - The year is not leap.
1046 * True - The year is leap.
1047 *
1048 *******************************************************************************/
Cy_RTC_IsLeapYear(uint32_t year)1049 __STATIC_INLINE bool Cy_RTC_IsLeapYear(uint32_t year)
1050 {
1051 CY_ASSERT_L2(CY_RTC_IS_YEAR_LONG_VALID(year));
1052
1053 return(((0U == (year % 4UL)) && (0U != (year % 100UL))) || (0U == (year % 400UL)));
1054 }
1055
1056
1057 /*******************************************************************************
1058 * Function Name: Cy_RTC_DaysInMonth
1059 ****************************************************************************//**
1060 *
1061 * Returns a number of days in a month passed through the parameters. This API
1062 * is for checking an invalid value input for days.
1063 * RTC HW block does not provide a validation checker against time/date values,
1064 * the valid range of days in Month should be checked before SetDateAndTime()
1065 * function call.
1066 *
1067 * \param month
1068 * The month of the year, see \ref group_rtc_month.
1069 *
1070 * \param year
1071 * A year value. Valid range non-zero value.
1072 *
1073 * \return
1074 * A number of days in a month in the year passed through the parameters.
1075 *
1076 *******************************************************************************/
Cy_RTC_DaysInMonth(uint32_t month,uint32_t year)1077 __STATIC_INLINE uint32_t Cy_RTC_DaysInMonth(uint32_t month, uint32_t year)
1078 {
1079 uint32_t retVal;
1080
1081 CY_ASSERT_L2(CY_RTC_IS_MONTH_VALID(month));
1082 CY_ASSERT_L2(CY_RTC_IS_YEAR_LONG_VALID(year));
1083
1084 retVal = cy_RTC_daysInMonthTbl[month - 1UL];
1085
1086 if (CY_RTC_FEBRUARY == month)
1087 {
1088 if (Cy_RTC_IsLeapYear(year))
1089 {
1090 retVal++;
1091 }
1092 }
1093 return(retVal);
1094 }
1095
1096
1097 /*******************************************************************************
1098 * Function Name: Cy_RTC_SyncFromRtc
1099 ****************************************************************************//**
1100 *
1101 * The Synchronizer updates RTC values into AHB RTC user registers from the
1102 * actual RTC. By calling this function, the actual RTC register values is
1103 * copied to AHB user registers.
1104 *
1105 * \note Only after calling Cy_RTC_SyncFromRtc(), the RTC time values can be
1106 * read. After Cy_RTC_SyncFromRtc() calling the snapshot of the actual RTC
1107 * registers are copied to the user registers. Meanwhile the RTC continues to
1108 * clock.
1109 *
1110 *******************************************************************************/
Cy_RTC_SyncFromRtc(void)1111 __STATIC_INLINE void Cy_RTC_SyncFromRtc(void)
1112 {
1113 uint32_t interruptState;
1114 uint32_t rtcAccessRetry = CY_RTC_ACCESS_BUSY_RETRY_COUNT;
1115
1116 interruptState = Cy_SysLib_EnterCriticalSection();
1117
1118 /* RTC Write is possible only in the condition that CY_RTC_BUSY bit = 0
1119 * or RTC Write bit is not set.
1120 */
1121 while((Cy_RTC_GetSyncStatus() == CY_RTC_BUSY) && (rtcAccessRetry != 0U))
1122 {
1123 rtcAccessRetry--;
1124 Cy_SysLib_DelayUs(CY_RTC_BUSY_RETRY_DELAY_US);
1125 }
1126
1127 if ((rtcAccessRetry != 0U) && (!_FLD2BOOL(BACKUP_RTC_RW_WRITE, BACKUP_RTC_RW)))
1128 {
1129 /* Setting RTC Read bit */
1130 BACKUP_RTC_RW = BACKUP_RTC_RW_READ_Msk;
1131
1132 /* Delay to guarantee RTC data reading */
1133 Cy_SysLib_DelayUs((uint16_t)CY_RTC_DELAY_WHILE_READING_US);
1134
1135 /* Clearing RTC Read bit */
1136 BACKUP_RTC_RW = 0U;
1137 }
1138 Cy_SysLib_ExitCriticalSection(interruptState);
1139 }
1140
1141
1142 /*******************************************************************************
1143 * Function Name: Cy_RTC_WriteEnable
1144 ****************************************************************************//**
1145 *
1146 * Set/Clear writeable option for RTC user registers. When the Write bit is set,
1147 * data can be written into the RTC user registers. After all the RTC writes are
1148 * done, the firmware must clear (call Cy_RTC_WriteEnable(RTC_WRITE_DISABLED))
1149 * the Write bit for the RTC update to take effect.
1150 *
1151 * Set/Clear cannot be done if the RTC is still busy with a previous update
1152 * (CY_RTC_BUSY = 1) or RTC Reading is executing.
1153 *
1154 * \param writeEnable
1155 * Write status, see \ref cy_en_rtc_write_status_t.
1156 *
1157 * \return
1158 * CY_RTC_SUCCESS - Set/Clear Write bit was successful.
1159 * CY_RTC_INVALID_STATE - RTC is busy with a previous update.
1160 * See \ref cy_en_rtc_status_t.
1161 *
1162 *******************************************************************************/
Cy_RTC_WriteEnable(cy_en_rtc_write_status_t writeEnable)1163 __STATIC_INLINE cy_en_rtc_status_t Cy_RTC_WriteEnable(cy_en_rtc_write_status_t writeEnable)
1164 {
1165 cy_en_rtc_status_t retVal = CY_RTC_INVALID_STATE;
1166 uint32_t rtcAccessRetry = CY_RTC_ACCESS_BUSY_RETRY_COUNT;
1167
1168 CY_ASSERT_L3(CY_RTC_IS_WRITE_VALID(writeEnable));
1169
1170 if (writeEnable == CY_RTC_WRITE_ENABLED)
1171 {
1172 /* RTC Write bit set is possible only in condition that CY_RTC_BUSY bit = 0
1173 * or RTC Read bit is not set
1174 */
1175 while((Cy_RTC_GetSyncStatus() == CY_RTC_BUSY) && (rtcAccessRetry != 0U))
1176 {
1177 rtcAccessRetry--;
1178 Cy_SysLib_DelayUs(CY_RTC_BUSY_RETRY_DELAY_US);
1179 }
1180
1181 if((rtcAccessRetry != 0U) && (!_FLD2BOOL(BACKUP_RTC_RW_READ, BACKUP_RTC_RW)))
1182 {
1183 BACKUP_RTC_RW |= BACKUP_RTC_RW_WRITE_Msk;
1184 retVal = CY_RTC_SUCCESS;
1185 }
1186 }
1187 else
1188 {
1189 /* Clearing Write Bit to complete write procedure */
1190 BACKUP_RTC_RW &= ((uint32_t) ~BACKUP_RTC_RW_WRITE_Msk);
1191
1192 retVal = CY_RTC_SUCCESS;
1193 }
1194
1195 return(retVal);
1196 }
1197
1198
1199 /*******************************************************************************
1200 * Function Name: Cy_RTC_GetSyncStatus
1201 ****************************************************************************//**
1202 *
1203 * Return current status of CY_RTC_BUSY. The status indicates
1204 * synchronization between the RTC user register and the actual RTC register.
1205 * CY_RTC_BUSY bit is set if it is synchronizing. It is not possible to set
1206 * the Read or Write bit until CY_RTC_BUSY clears.
1207 *
1208 * \return
1209 * The status of RTC user register synchronization. See
1210 * \ref group_rtc_busy_status
1211 *
1212 *******************************************************************************/
Cy_RTC_GetSyncStatus(void)1213 __STATIC_INLINE uint32_t Cy_RTC_GetSyncStatus(void)
1214 {
1215 return((_FLD2BOOL(BACKUP_STATUS_RTC_BUSY, BACKUP_STATUS)) ? CY_RTC_BUSY : CY_RTC_AVAILABLE);
1216 }
1217
1218
1219 /*******************************************************************************
1220 * Function Name: Cy_RTC_GetHoursFormat
1221 ****************************************************************************//**
1222 *
1223 * Returns current 12/24 hours format.
1224 *
1225 * \note
1226 * Before getting the RTC current hours format, the Cy_RTC_SyncFromRtc() function
1227 * should be called.
1228 *
1229 * \return
1230 * The current RTC hours format. See \ref cy_en_rtc_hours_format_t.
1231 *
1232 *******************************************************************************/
Cy_RTC_GetHoursFormat(void)1233 __STATIC_INLINE cy_en_rtc_hours_format_t Cy_RTC_GetHoursFormat(void)
1234 {
1235 return((_FLD2BOOL(BACKUP_RTC_TIME_CTRL_12HR, BACKUP_RTC_TIME)) ? CY_RTC_12_HOURS : CY_RTC_24_HOURS);
1236 }
1237
1238
1239 /*******************************************************************************
1240 * Function Name: Cy_RTC_IsExternalResetOccurred
1241 ****************************************************************************//**
1242 *
1243 * The function checks the reset cause and returns the Boolean result.
1244 *
1245 * \return
1246 * True if the reset reason is the power cycle and the XRES (external reset).
1247 * False if the reset reason is other than power cycle and the XRES.
1248 *
1249 * \note Based on a return value the RTC time and date can be updated or skipped
1250 * after the device reset. For example, you should skip the
1251 * Cy_RTC_SetAlarmDateAndTime() call function if internal WDT reset occurs.
1252 *
1253 *******************************************************************************/
Cy_RTC_IsExternalResetOccurred(void)1254 __STATIC_INLINE bool Cy_RTC_IsExternalResetOccurred(void)
1255 {
1256 #if (defined (CY_IP_MXS40SRSS) && (CY_IP_MXS40SRSS_VERSION >= 3))
1257 return(0u != ((CY_SYSLIB_RESET_XRES | CY_SYSLIB_RESET_PORVDDD) & Cy_SysLib_GetResetReason()));
1258 #else
1259 return(0u == Cy_SysLib_GetResetReason());
1260 #endif
1261 }
1262
1263
1264 /*******************************************************************************
1265 * Function Name: Cy_RTC_SyncToRtcAhbDateAndTime
1266 ****************************************************************************//**
1267 *
1268 * This function updates new time and date into the time and date RTC AHB
1269 * registers.
1270 *
1271 * \param timeBcd
1272 * The BCD-formatted time variable which has the same bit masks as the
1273 * RTC_TIME register:
1274 *
1275 * [0:6] - Calendar seconds in BCD, the range 0-59. \n
1276 * [14:8] - Calendar minutes in BCD, the range 0-59. \n
1277 * [21:16] - Calendar hours in BCD, value depends on the 12/24-hour mode. \n
1278 * 12HR: [21]:0 = AM, 1 = PM, [20:16] = 1 - 12; \n
1279 * 24HR: [21:16] = 0-23. \n
1280 * [22] - Selects the 12/24-hour mode: 1 - 12-hour, 0 - 24-hour. \n
1281 * [26:24] - A calendar day of the week, the range 1 - 7, where 1 - Sunday. \n
1282 *
1283 * \param dateBcd
1284 * The BCD-formatted time variable which has the same bit masks as the
1285 * RTC_DATE register:
1286 *
1287 * [5:0] - A calendar day of a month in BCD, the range 1-31. \n
1288 * [12:8] - A calendar month in BCD, the range 1-12. \n
1289 * [23:16] - A calendar year in BCD, the range 0-99. \n
1290 *
1291 * \note Ensure that the parameters are presented in the BCD format. Use the
1292 * ConstructTimeDate() function to construct BCD time and date values.
1293 * Refer to ConstructTimeDate() function description for more details
1294 * about the RTC_TIME and RTC_DATE bit fields format.
1295 *
1296 * The RTC AHB registers can be updated only under condition that the
1297 * Write bit is set and the RTC busy bit is cleared (RTC_BUSY = 0). Call the
1298 * Cy_RTC_WriteEnable(CY_RTC_WRITE_ENABLED) and ensure that Cy_RTC_WriteEnable()
1299 * returned CY_RTC_SUCCESS. Then you can call Cy_RTC_SyncToRtcAhbDateAndTime().
1300 * Do not forget to clear the RTC Write bit to finish an RTC register update by
1301 * calling Cy_RTC_WriteEnable(CY_RTC_WRITE_DISABLED) after you executed
1302 * Cy_RTC_SyncToRtcAhbDateAndTime(). Ensure that Cy_RTC_WriteEnable()
1303 * returned CY_RTC_SUCCESS.
1304 *
1305 *******************************************************************************/
Cy_RTC_SyncToRtcAhbDateAndTime(uint32_t timeBcd,uint32_t dateBcd)1306 __STATIC_INLINE void Cy_RTC_SyncToRtcAhbDateAndTime(uint32_t timeBcd, uint32_t dateBcd)
1307 {
1308 BACKUP_RTC_TIME = timeBcd;
1309 BACKUP_RTC_DATE = dateBcd;
1310 }
1311
1312
1313 /*******************************************************************************
1314 * Function Name: Cy_RTC_SyncToRtcAhbAlarm
1315 ****************************************************************************//**
1316 *
1317 * This function updates new alarm time and date into the alarm tire and date
1318 * RTC AHB registers.
1319 *
1320 * \param alarmTimeBcd
1321 * The BCD-formatted time variable which has the same bit masks as the
1322 * ALMx_TIME register time fields:
1323 *
1324 * [0:6] - Alarm seconds in BCD, the range 0-59. \n
1325 * [7] - Alarm seconds Enable: 0 - ignore, 1 - match. \n
1326 * [14:8] - Alarm minutes in BCD, the range 0-59. \n
1327 * [15] - Alarm minutes Enable: 0 - ignore, 1 - match. \n
1328 * [21:16] - Alarm hours in BCD, value depending on the 12/24-hour mode
1329 * (RTC_CTRL_12HR)\n
1330 * 12HR: [21]:0 = AM, 1 = PM, [20:16] = 1 - 12; \n
1331 * 24HR: [21:16] = the range 0-23. \n
1332 * [23] - Alarm hours Enable: 0 - ignore, 1 - match. \n
1333 * [26:24] - An alarm day of the week, the range 1 - 7, where 1 - Monday. \n
1334 * [31] - An alarm day of the week Enable: 0 - ignore, 1 - match. \n
1335 *
1336 * \param alarmDateBcd
1337 * The BCD-formatted date variable which has the same bit masks as the
1338 * ALMx_DATE register date fields: \n
1339 * [5:0] - An alarm day of a month in BCD, the range 1-31. \n
1340 * [7] - An alarm day of a month Enable: 0 - ignore, 1 - match. \n
1341 * [12:8] - An alarm month in BCD, the range 1-12. \n
1342 * [15] - An alarm month Enable: 0 - ignore, 1 - match. \n
1343 * [31] - The Enable alarm: 0 - Alarm is disabled, 1 - Alarm is enabled. \n
1344 *
1345 * \param alarmIndex
1346 * The alarm index to be configured, see \ref cy_en_rtc_alarm_t.
1347 *
1348 * \note Ensure that the parameters are presented in the BCD format. Use the
1349 * ConstructTimeDate() function to construct BCD time and date values.
1350 * Refer to ConstructTimeDate() function description for more details
1351 * about the RTC ALMx_TIME and ALMx_DATE bit-fields format.
1352 *
1353 * The RTC AHB registers can be updated only under condition that the
1354 * Write bit is set and the RTC busy bit is cleared (RTC_BUSY = 0). Call the
1355 * Cy_RTC_WriteEnable(CY_RTC_WRITE_ENABLED) and ensure that Cy_RTC_WriteEnable()
1356 * returned CY_RTC_SUCCESS. Then you can call Cy_RTC_SyncToRtcAhbDateAndTime().
1357 * Do not forget to clear the RTC Write bit to finish an RTC register update by
1358 * calling the Cy_RTC_WriteEnable(CY_RTC_WRITE_DISABLED) after you executed
1359 * Cy_RTC_SyncToRtcAhbDateAndTime(). Ensure that Cy_RTC_WriteEnable()
1360 * returned CY_RTC_SUCCESS.
1361 *
1362 *******************************************************************************/
Cy_RTC_SyncToRtcAhbAlarm(uint32_t alarmTimeBcd,uint32_t alarmDateBcd,cy_en_rtc_alarm_t alarmIndex)1363 __STATIC_INLINE void Cy_RTC_SyncToRtcAhbAlarm(uint32_t alarmTimeBcd, uint32_t alarmDateBcd, cy_en_rtc_alarm_t alarmIndex)
1364 {
1365 CY_ASSERT_L3(CY_RTC_IS_ALARM_IDX_VALID(alarmIndex));
1366
1367 if (alarmIndex != CY_RTC_ALARM_2)
1368 {
1369 BACKUP_ALM1_TIME = alarmTimeBcd;
1370 BACKUP_ALM1_DATE = alarmDateBcd;
1371 }
1372 else
1373 {
1374 BACKUP_ALM2_TIME = alarmTimeBcd;
1375 BACKUP_ALM2_DATE = alarmDateBcd;
1376 }
1377 }
1378
1379 /** \} group_rtc_low_level_functions */
1380 /** \} group_rtc */
1381
1382 /*******************************************************************************
1383 * Internal Functions
1384 *******************************************************************************/
1385
1386 __STATIC_INLINE uint32_t Cy_RTC_ConvertBcdToDec(uint32_t bcdNum);
1387 __STATIC_INLINE uint32_t Cy_RTC_ConvertDecToBcd(uint32_t decNum);
1388
1389 /*******************************************************************************
1390 * Function Name: Cy_RTC_ConvertBcdToDec
1391 ****************************************************************************//**
1392 *
1393 * Converts an 8-bit BCD number into an 8-bit hexadecimal number. Each byte is
1394 * converted individually and returned as an individual byte in the 32-bit
1395 * variable.
1396 *
1397 * \param
1398 * bcdNum An 8-bit BCD number. Each byte represents BCD.
1399 *
1400 * \return
1401 * decNum An 8-bit hexadecimal equivalent number of the BCD number.
1402 *
1403 * For example, for 0x11223344 BCD number, the function returns
1404 * 0x2C in hexadecimal format.
1405 *
1406 * \note
1407 * This API is available for CAT1A devices.
1408 *
1409 *******************************************************************************/
Cy_RTC_ConvertBcdToDec(uint32_t bcdNum)1410 __STATIC_INLINE uint32_t Cy_RTC_ConvertBcdToDec(uint32_t bcdNum)
1411 {
1412 uint32_t retVal;
1413
1414 retVal =
1415 ((bcdNum & (CY_RTC_BCD_ONE_DIGIT_MASK << CY_RTC_BCD_NUMBER_SIZE))
1416 >> CY_RTC_BCD_NUMBER_SIZE ) * CY_RTC_BCD_DOZED_DEGREE;
1417
1418 retVal += bcdNum & CY_RTC_BCD_ONE_DIGIT_MASK;
1419
1420 return (retVal);
1421 }
1422
1423
1424 /*******************************************************************************
1425 * Function Name: Cy_RTC_ConvertDecToBcd
1426 ****************************************************************************//**
1427 *
1428 * Converts an 8-bit hexadecimal number into an 8-bit BCD number. Each byte
1429 * is converted individually and returned as an individual byte in the 32-bit
1430 * variable.
1431 *
1432 * \param
1433 * decNum An 8-bit hexadecimal number. Each byte is represented in hex.
1434 * 0x11223344 -> 0x20 hex format.
1435 *
1436 * \return
1437 * An 8-bit BCD equivalent of the passed hexadecimal number.
1438 *
1439 * For example, for 0x11223344 hexadecimal number, the function returns
1440 * 0x20 BCD number.
1441 *
1442 * \note
1443 * This API is available for CAT1A devices.
1444 *
1445 *******************************************************************************/
Cy_RTC_ConvertDecToBcd(uint32_t decNum)1446 __STATIC_INLINE uint32_t Cy_RTC_ConvertDecToBcd(uint32_t decNum)
1447 {
1448 uint32_t retVal;
1449 uint32_t tmpVal;
1450
1451 tmpVal = decNum % CY_RTC_BCD_HUNDRED_DEGRE;
1452 retVal = ((uint32_t)(tmpVal / CY_RTC_BCD_DOZED_DEGREE)) << CY_RTC_BCD_NUMBER_SIZE;
1453 retVal += tmpVal % CY_RTC_BCD_DOZED_DEGREE;
1454
1455 return (retVal);
1456 }
1457
1458 #if defined(__cplusplus)
1459 }
1460 #endif
1461
1462 #endif /* CY_IP_MXS40SRSS_RTC, CY_IP_MXS28SRSS, CY_IP_MXS40SSRSS. CY_IP_MXS22SRSS */
1463
1464 #endif /* CY_RTC_H */
1465
1466 /* [] END OF FILE */
1467
