MTB CAT1 Peripheral driver library
RTC (Real-Time Clock)

General Description

The Real-Time Clock (RTC) driver provides an application interface for keeping track of time and date.

The functions and other declarations used in this driver are in cy_rtc.h. You can include cy_pdl.h to get access to all functions and declarations in the PDL.

Use the RTC driver when the system requires the current time or date. You can also use the RTC when you do not need the current time and date but you do need accurate timing of events with one-second resolution.

The RTC driver provides these features:

The RTC driver provides access to the HW real-time clock. The HW RTC is located in the Backup domain. You need to choose the clock source for the Backup domain using the Cy_SysClk_ClkBakSetSource() function. If the clock for the Backup domain is set and enabled, the RTC automatically starts counting.

The RTC driver keeps track of second, minute, hour, day of the week, day of the month, month, and year.

DST may be enabled and supports any start and end date. The start and end dates can be a fixed date (like 24 March) or a relative date (like the second Sunday in March).

The RTC has two alarms that you can configure to generate an interrupt. You specify the match value for the time when you want the alarm to occur. Your interrupt handler then handles the response. The alarm flexibility supports periodic alarms (such as every minute), or a single alarm (13:45 on 28 September, 2043).

Clock Source

The Backup domain can be driven by:

The WCO is the recommended clock source for the RTC, if it is present in design. For setting the Backup domain clock source, refer to the SysClk (System Clock) driver.

Note
If the WCO is enabled, it should source the Backup domain directly. Do not route the WCO through the Clk_LF. This is because Clk_LF is not available in all low-power modes.

Configuration Considerations

Before RTC set up, ensure that the Backup domain is clocked with the desired clock source.

To set up an RTC, provide the configuration parameters in the cy_stc_rtc_config_t structure. Then call Cy_RTC_Init(). You can also set the date and time at runtime. Call Cy_RTC_SetDateAndTime() using the filled cy_stc_rtc_config_t structure, or call Cy_RTC_SetDateAndTimeDirect() with valid time and date values.

RTC Interrupt Handling

The RTC driver provides three interrupt handler functions: Cy_RTC_Alarm1Interrupt(), Cy_RTC_Alarm2Interrupt(), and Cy_RTC_CenturyInterrupt(). All three functions are blank functions with the WEAK attribute. For any interrupt you use, redefine the interrupt handler in your source code.

When an interrupt occurs, call the Cy_RTC_Interrupt() function. The RTC hardware provides a single interrupt line to the NVIC for the three RTC interrupts. This function checks the interrupt register to determine which interrupt (out of the three) was generated. It then calls the appropriate handler.

Warning
The Cy_RTC_Alarm2Interrupt() is not called if the DST feature is enabled. If DST is enabled, the Cy_RTC_Interrupt() function redirects that interrupt to manage daylight savings time using Cy_RTC_DstInterrupt(). In general, the RTC interrupt handler function the Cy_RTC_DstInterrupt() function is called instead of Cy_RTC_Alarm2Interrupt().

For RTC interrupt handling, the user should:

  1. Implement strong interrupt handling function(s) for the required events (see above). If DST is enabled, then Alarm2 is not available. The DST handler is built into the PDL.
  2. Implement an RTC interrupt handler and call Cy_RTC_Interrupt() from there.
  3. Configure the RTC interrupt:
    • Set the mask for RTC required interrupt using Cy_RTC_SetInterruptMask().
    • Initialize the RTC interrupt by setting priority and the RTC interrupt vector using the Cy_SysInt_Init() function.
    • Enable the RTC interrupt using the CMSIS core function NVIC_EnableIRQ().

Alarm functionality

To set up an alarm, enable the required RTC interrupt. Then provide the configuration parameters in the cy_stc_rtc_alarm_t structure. You enable any item you want matched, and provide a match value. You disable any other. You do not need to set match values for disabled elements, as they are ignored.

Note
The alarm itself must be enabled in this structure. When a match occurs, the alarm is triggered and your interrupt handler is called.

An example is the best way to explain how this works. If you want an alarm on every hour, then in the cy_stc_rtc_alarm_t structure, you provide these values:

Alarm_1.sec = 0u
Alarm_1.secEn = CY_RTC_ALARM_ENABLE
Alarm_1.min = 0u
Alarm_1.minEn = CY_RTC_ALARM_ENABLE
Alarm_1.hourEn = CY_RTC_ALARM_DISABLE
Alarm_1.dayOfWeekEn = CY_RTC_ALARM_DISABLE
Alarm_1.dateEn = CY_RTC_ALARM_DISABLE
Alarm_1.monthEn = CY_RTC_ALARM_DISABLE
Alarm_1.almEn = CY_RTC_ALARM_ENABLE
With this setup, every time both the second and minute are zero, Alarm1 is asserted. That happens once per hour. Note that, counterintuitively, to have an alarm every hour, Alarm_1.hourEn is disabled. This is disabled because for an hourly alarm you do not match the value of the hour.

After cy_stc_rtc_alarm_t structure is filled, call the Cy_RTC_SetAlarmDateAndTime(). The alarm can also be set without using the cy_stc_rtc_alarm_t structure. Call Cy_RTC_SetAlarmDateAndTimeDirect() with valid values.

The DST Feature

The DST feature is managed by the PDL using the RTC Alarm2 interrupt. Therefore, you cannot have both DST enabled and use the Alarm2 interrupt.

To set up the DST, route the RTC interrupt to NVIC:

  1. Initialize the RTC interrupt by setting priority and the RTC interrupt vector using Cy_SysInt_Init().
  2. Enable the RTC interrupt using the CMSIS core function NVIC_EnableIRQ().

After this, provide the configuration parameters in the cy_stc_rtc_dst_t structure. This structure consists of two cy_stc_rtc_dst_format_t structures, one for DST Start time and one for DST Stop time. You also specify whether these times are absolute or relative.

After the cy_stc_rtc_dst_t structure is filled, call Cy_RTC_EnableDstTime()

Low Power Support

The RTC provides the callback functions to facilitate the low-power mode transition. The callback Cy_RTC_DeepSleepCallback must be called during execution of Cy_SysPm_CpuEnterDeepSleep, Cy_RTC_HibernateCallback must be called during execution of Cy_SysPm_SystemEnterHibernate. To trigger the callback execution, the callback must be registered before calling the mode transition function. Refer to SysPm (System Power Management) driver for more information about low-power mode transitions.

More Information

For more information on the RTC peripheral, refer to the technical reference manual (TRM).

Changelog

VersionChangesReason for Change
2.100 Minor update in API Cy_RTC_GetInterruptStatus. Code enhancement.
2.90 Updated API Cy_RTC_GetInterruptStatus. Code enhancement.
2.80 Added support for TRAVEO™ II Body Entry devices.
Pre-processor check for MXS40SRSS version now groups ver. 2 with ver. 3. Previously ver. 2 was grouped with ver. 1. Cleaned up redundant and overlapping conditions in pre-processor directives.
Code enhancement and support for new devices.
2.70 Enhanced API's : Cy_RTC_SetDateAndTime(), Cy_RTC_SetDateAndTimeDirect(), Cy_RTC_SetAlarmDateAndTime(), Cy_RTC_SetAlarmDateAndTimeDirect(). Minor Enhancements to the Driver.
2.60 CAT1B, CAT1C, CAT1D devices support.
Newly added API's Cy_RTC_WriteEnable() to Set/Clear writeable option for RTC user registers, Cy_RTC_EnableDstTime() to set the DST time and configure the ALARM2 interrupt register with the appropriate DST time, Cy_RTC_DstInterrupt() to handle the DST event.
Added a delay in Cy_RTC_SyncFromRtc() to check the RTC busy status.
Support for new devices.
2.50 Removed the calls that convert among BCD and Binary. RTC encoding changed from BCD to Binary.
2.40 Fixed/Documented MISRA 2012 violations. MISRA 2012 compliance.
2.30.1 Minor documentation updates. Documentation enhancement.
2.30
  • Collateral Review: user experience enhancement.
  • Bug fix.
2.20.1 Modified header guard CY_IP_MXS40SRSS_RTC. To enable the PDL compilation with wounded out IP blocks.
2.20 Flattened the organization of the driver source code into the single source directory and the single include directory. Driver library directory-structure simplification.
Added register access layer. Use register access macros instead of direct register access using dereferenced pointers. Makes register access device-independent, so that the PDL does not need to be recompiled for each supported part number.
Documentation update. Documentation enhancement.
2.10
2.0 Enhancement and defect fixes:
  • Added input parameter(s) validation to all public functions.
  • Removed "Cy_RTC_" prefixes from the internal functions names.
  • Renamed the elements in the cy_stc_rtc_alarm structure.
  • Changed the type of elements with limited set of values, from uint32_t to enumeration.
1.0 Initial version

API Reference

 Macros
 
 Functions
 
 Data Structures
 
 Enumerated Types