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