RTC Driver

Table of Contents

• RTC HAL Module Introduction
  • RTC HAL Module Features
  • RTC Hardware Support Details
• RTC HAL Module APIs Overview
• RTC HAL Module Operational Overview
  • RTC HAL Module Important Operational Notes and Limitations
    • RTC HAL Module Operational Notes
    • RTC HAL Module Limitations
• Including the RTC HAL Module in an Application
• Configuring the RTC HAL Module
  • RTC HAL Module Clock Configuration
  • RTC HAL Module Pin Configuration
• Using the RTC HAL Module in an Application

RTC HAL Module Introduction

The Real-Time Clock (RTC) HAL module implements a high-level API for real-time timing applications and uses the real-time clock module on a Synergy MCU. The RTC HAL module configures the RTC module and controls clock, calendar and alarm functions. A callback can be used to respond to any of the three supported interrupt types: alarm, periodic, or carry.

RTC HAL Module Features

• RTC peripheral configuration.
• RTC time and date get and set.
• RTC time and date alarm get and set.
• RTC time counter start and stop.
• RTC alarm, periodic, and carry event notification.
• RTC event type enable and disable.
• RTC event rate configuration.
• RTC clock source set and get.
• RTC sub-clock error adjustment.
• RTC status get.

RTC HAL Module Block Diagram

RTC Hardware Support Details

The following hardware features are, or are not, supported by SSP for the RTC.

Legend:

Symbol	Meaning
✓	Available (Tested)
⌧	Not Available (Not tested/not functional or both)
N/A	Not supported by MCU

 

MCU Group	Calendar Mode	Binary Mode	Sub-clock (XCIN) Count Source	LOCO Count Source	12 hours/24 hours	Alarm interrupt (RTC_ALM)
S124	✓	⌧	✓	✓	24 Hours	✓
S128	✓	⌧	✓	✓	24 Hours	✓
S1JA	✓	⌧	✓	✓	24 Hours	✓
S3A1	✓	⌧	✓	✓	24 Hours	✓
S3A3	✓	⌧	✓	✓	24 Hours	✓
S3A6	✓	⌧	✓	✓	24 Hours	✓
S3A7	✓	⌧	✓	✓	24 Hours	✓
S5D3	✓	⌧	✓	✓	24 Hours	✓
S5D5	✓	⌧	✓	✓	24 Hours	✓
S5D9	✓	⌧	✓	✓	24 Hours	✓
S7G2	✓	⌧	✓	✓	24 Hours	✓

MCU Group	Periodic interrupt (RTC_PRD)	Carry interrupt (RTC_CUP)	Time capture function	Event link function through ELC HAL driver	Start/stop function	Clock error correction function
S124	✓	✓	⌧	⌧	✓	✓
S128	✓	✓	⌧	⌧	✓	✓
S1JA	✓	✓	⌧	⌧	✓	✓
S3A1	✓	✓	⌧	⌧	✓	✓
S3A3	✓	✓	⌧	⌧	✓	✓
S3A6	✓	✓	⌧	⌧	✓	✓
S3A7	✓	✓	⌧	⌧	✓	✓
S5D3	✓	✓	⌧	⌧	✓	✓
S5D5	✓	✓	⌧	⌧	✓	✓
S5D9	✓	✓	⌧	⌧	✓	✓
S7G2	✓	✓	⌧	⌧	✓	✓

RTC HAL Module APIs Overview

The RTC HAL module defines APIs for opening, closing, setting alarms and starting and stopping RTC operations. A complete list of the available APIs, an example API call and a short description of each can be found in the following table. A table of status return values follows the API summary table.

RTC HAL Module API Summary

Function Name	Example API Call and Description
open	g_rtc0.p_api->open(g_rtc0.p_ctrl, g_rtc0.p_cfg); Open the RTC HAL.
close	g_rtc0.p_api->close(g_rtc0.p_ctrl); Close the RTC HAL.
configure	g_rtc0.p_api->configure(g_rtc0.p_ctrl, p_extend);
calendarTimeSet	g_rtc0.p_api->calendarTimeSet(g_rtc0.p_ctrl, &start_time_struct_in, true); Set the calendar time.
calendarTimeGet	g_rtc0.p_api->calendarTimeGet(g_rtc0.p_ctrl, &current_time_struct_out); Get the calendar time.
calendarAlarmSet	g_rtc0.p_api->calendarAlarmSet(g_rtc0.p_ctrl, &in_alarm_time_struct_in, true); Set the calendar alarm time.
calendarAlarmGet	g_rtc0.p_api->calendarAlarmGet(g_rtc0.p_ctrl, &get_alarm_time_struct_out); Get the calendar alarm time.
calendarCounterStart	g_rtc0.p_api->calendarCounterStart(g_rtc0.p_ctrl); Start the calendar counter.
calendarCounterStop	g_rtc0.p_api->calendarCounterStop(g_rtc0.p_ctrl); Stop the calendar counter.
irqEnable	g_rtc0.p_api->irqEnable(g_rtc0.p_ctrl, CALLBACK); Enable the alarm irq.
irqDisable	g_rtc0.p_api->irqDisable(g_rtc0.p_ctrl, CALLBACK); Disable the alarm irq.
periodicIrqRateSet	g_rtc0.p_api->periodicIrqRateSet(g_rtc0.p_ctrl, Rate); Set the periodic irq rate.
infoGet	g_rtc0.p_api->infoGet(g_rtc0.p_ctrl, clk_src); Return the currently configure clock source for the RTC.
errorAdjustmentModeSet
errorAdjustmentSet
versionGet	g_rtc0.p_api->versionGet(&version); Retrieve the API version with the version pointer.

Note

For more complete descriptions of operation and definitions for the function data structures, typedefs, defines, API data, API structures, and function variables, review the SSP User's Manual API References for the associated module.

Status Return Values

Name	Description
SSP_SUCCESS	Function executed successfully.
SSP_ERR_ASSERTION	API dependent error.
SSP_ERR_INVALID MODE	Invalid mode.
SSP_ERR_INVALID_PTR	Invalid parameter.

Note

Lower-level drivers may return common error codes. Refer to the SSP User's Manual API References for the associated module for a definition of all relevant status return values.

RTC HAL Module Operational Overview

The RTC HAL module controls the operation of the real-time clock module on a Synergy MCU. The typical RTC application configures the real-time clock controller periodically based on a system configuration driven by the user. Common operations include setting the time, setting an alarm, configuring a periodic interrupt, and starting or stopping operation. An RTC application usually consists of calls to the RTC HAL module and an optional callback from ISR handler.

• The RTC HAL module can use two main clock sources
  • A Low Speed On-Chip Oscillator (LOCO) with lower power, but with less accuracy
  • A sub-clock oscillator with higher power, increased accuracy, and more cost (external crystal required)
• The RTC HAL module supports three different interrupt types
  • An alarm interrupt generated on a match of any combination of year, month, day, day of the week, hour, minute or second
  • A periodic interrupt generated every 2, 1, ½, ¼, 1/8, 1/16, 1/32, 1/64 ,1/128 or 1/256 second(s)
  • A carry interrupt when either a carry to the second counter occurs or when a carry to the R64CNT counter occurs during a read access to the 64 Hz counter

A user-defined callback function can be registered (in the rtc_api_t::open API call) and will be called from the interrupt service routine (ISR) for any supported interrupt type. When called, it is passed a pointer to a structure (rtc_callback_args_t) that holds a user-defined context pointer and an indication of which type of interrupt was fired.

Note

The carry interrupt priority must be set to avoid an incorrect time returned from the rtc_api_t::calendarTimeGet API during roll-over.

RTC HAL Module Important Operational Notes and Limitations

RTC HAL Module Operational Notes

The RTC HAL module must be opened before any of the other RTC module APIs can be called. A configuration structure is passed to the open call which specifies the clock source, the name of the user callback from ISR handler, and a user-specified context for the callback. Configuration structures can be either manually defined or generated by the ISDE based on user input during the configuration process.

Functions in the driver can be accessed by either making direct calls to the HAL layer or by using the RTC interface structure. The name of this interface structure is based on the name setting entered in the module's configuration. For example, if the name is g_rtc, then the interface structure is called g_rtc_api.

RTC HAL Module Limitations

• The rtc_api_t::calendarTimeGet API must not be called with interrupts disabled globally, as this API internally uses carry interrupt for its processing. The API may return incorrect time if this is done.
• This module has no support for the following functions:
  • Binary-count mode
  • Binary alarm set and get
  • Binary time get and set.
  • LOCO clock-error correction
  • 1-Hz/64-Hz clock output
• Refer to the most recent SSP Release Notes for any additional operational limitations for this module.

Including the RTC HAL Module in an Application

This section describes how to include the RTC HAL Module in an application using the SSP configurator.

Note

This section assumes you are familiar with creating a project, adding threads, adding a stack to a thread and configuring a block within the stack. If you are unfamiliar with any of these items, refer to the first few chapters of the SSP User's Manual to learn how to manage each of these important steps in creating SSP-based applications.

To add the RTC Driver to an application, simply add it to a thread using the stacks selection sequence given in the following table. (The default name for the RTC Driver is g_rtc0. This name can be changed in the associated Properties window.)

RTC HAL Module Selection Sequence

Resource	ISDE Tab	Stacks Selection Sequence
g_rtc0 RTC HAL on r_rtc	Threads	New Stack> Driver> Timers> RTC HAL on r_rtc

When the RTC Driver on r_rtc is added to the thread stack as shown in the following figure, the configurator automatically adds any needed lower‑level modules. Any modules needing additional configuration information have the box text highlighted in Red. Modules with a Gray band are individual modules that stand alone. Modules with a Blue band are shared or common; they need only be added once and can be used by multiple stacks. Modules with a Pink band can require the selection of lower-level modules; these are either optional or recommended. (This is indicated in the block with the inclusion of this text.) If the addition of lower-level modules is required, the module description include Add in the text. Clicking on any Pink banded modules brings up the New icon and displays possible choices.

RTC HAL Module Stack

Configuring the RTC HAL Module

The RTC HAL Module must be configured by the user for the desired operation. The available configuration settings and defaults for all the user-accessible properties are given in the properties tab within the SSP configurator and are shown in the following tables for easy reference. Only properties that can be changed without causing conflicts are available for modification. Other properties are locked and not available for changes and are identified with a lock icon for the locked property in the Properties window in the ISDE. This approach simplifies the configuration process and makes it much less error-prone than previous manual approaches to configuration. The available configuration settings and defaults for all the user-accessible properties are given in the Properties tab within the SSP Configurator and are shown in the following tables for easy reference.

Note

You may want to open your ISDE, create the module and explore the property settings in parallel with looking over the following configuration table settings. This will help orient you and can be a useful 'hands-on' approach to learning the ins and outs of developing with SSP.

Configuration Settings for the RTC HAL Module on r_rtc

ISDE Property	Value	Description
Parameter Checking	BSP, Enabled, Disabled Default: BSP	Enable or disable parameter error checking.
Name	g_rtc0	The name to be used for the RTC module control block instance. This name is also used as the prefix of the other variable instances. See the example code below.
Clock Source	LOCO, Sub-clock Default: LOCO	Clock source for the RTC block.
Configure RTC hardware in open() call	Yes, No Default: Yes	If enabled, the RTC registers and clock source will be initialized in the open() call. If disabled, the user call must call the configure() api to initialize the hardware.
Error Adjustment Value	0	Warning: Deprecated configuration field. Must be 0.
Error Adjustment Type	None	Warning: Deprecated configuration field. Must be 0.
Callback	NULL	The name of the ISR that is called when one of the three interrupts fire. The argument passed into this ISR has an indication of which interrupt caused it to be called. See the example code below.
Alarm Interrupt Priority	Priority 0 (highest), Priority 1:14 Priority 15 (lowest - not valid if using ThreadX), Disabled Default: Disabled	Alarm interrupt priority selection.
Period Interrupt Priority	Priority 0 (highest), Priority 1:14 Priority 15 (lowest - not valid if using ThreadX), Disabled Default: Disabled	Period interrupt priority selection.
Carry Interrupt Priority	Priority 0 (highest), Priority 1:14 Priority 15 (lowest - not valid if using ThreadX) Default: Priority 12	Carry interrupt priority selection.

Note

The example settings and defaults are for a project using the Synergy S7G2 MCU Group. Other MCUs may have different default values and available configuration settings.

RTC HAL Module Clock Configuration

The RTC HAL module can use the following clock sources:

• LOCO (Low Speed On-Chip Oscillator)
  • Lower-power consumption
  • Less accurate
• Sub-clock oscillator
  • Higher-power consumption
  • More accurate
  • More cost (requires a crystal)

The LOCO is the default selection during configuration.

RTC HAL Module Pin Configuration

The RTC does not currently support outputs, so no output pin selections are available.

Using the RTC HAL Module in an Application

General Usage

The typical RTC application configures the real-time clock controller periodically based on a system configuration driven by the user. Examples include setting the time, setting an alarm, configuring a periodic interrupt, etc. An RTC application consists of calls to the RTC module and an optional callback.

The RTC module must be opened before any of the other APIs can be called. A configuration structure is passed to the open call which specifies the clock source, the name of the callbacks, and user-specified context for the handler. Configuration structures can be either manually defined or generated by the ISDE based on user input during the configuration process. Functions in the module can be accessed by using the RTC interface structure. The name of this interface structure is based on the name setting entered in the module's configuration.

Avoid Drift Issue After Reset

To avoid drift in RTC time across MCU reset, the application needs to follow the following steps:

Make these changes to module configuration settings:

1. Disable the "Configure Subclock Drive On Reset" option in the CGC stack element of the ISDE configurator.
2. Disable the "Configure RTC hardware in open() call" option in the RTC stack element of the ISDE configurator.

Make these calls in the application code:

1. Call the rtc_api_t::open API as usual.
2. Call the RTC rtc_api_t::configure API only on a cold start. This will initialize the RTC only in a cold start condition.

These two steps can be performed by using the following initialization sequence in the application:

   g_rtc.p_api->open(g_rtc.p_ctrl,g_rtc.p_cfg);
   g_rtc.p_api->infoGet(g_rtc.p_ctrl,&info1);
   /* initialize RTC if its status is stopped state i.e. on cold start */
   if(RTC_STATUS_STOPPED == info1.status)
   {
/* if the RTC clock source is sub-clock, stop it so that the sub-clock drive capacity is set correctly in the configure API */
          g_cgc.p_api->clockStop(CGC_CLOCK_SUBCLOCK); 
          g_rtc.p_api->configure(g_rtc.p_ctrl, NULL);
          g_rtc.p_api->calendarTimeSet(g_rtc.p_ctrl,&rt_time,true);
                }

An alternative way to determine cold start condition (instead of status) is to obtain the information from the reset status registers (RSTSRx).

Date and Time Validation

The "Parameter Checking" setting needs to be enabled in the ISDE configurator if date and time validation is required for the rtc_api_t::calendarTimeSet and rtc_api_t::calendarAlarmSet APIs. If "Parameter Checking" is enabled, the 'day of the week' field is automatically calculated and updated by the driver for the provided date. When using rtc_api_t::calendarAlarmSet API, only the fields which have their corresponding match flag set are written to the registers, other register fields are reset to default value.

Sub-Clock Error Adjustment

The rtc_api_t::errorAdjustmentModeSet and rtc_api_t::errorAdjustmentSet APIs can be used to correct the error in the RTC sub-clock source. These APIs can only be used after the RTC is configured and time is set.

The error adjustment is reset every time the RTC is reconfigured or time is set.

There are two common application uses for the RTC HAL module. The first simply uses the RTC to supply the current time as required by the application. A second use of the RTC HAL modules uses the periodic interrupt capability to initiate a process at a regular period. Examples of both uses are provided below.

Note

The configuration property 'Configure RTC hardware in open() call' in the RTC stack of the ISDE configurator controls the behavior of the rtc_api_t::open API. If enabled, the RTC peripheral is configured in the rtc_api_t::open API. If disabled, it is the responsibility of the application to make sure that RTC is configured before usage by using the rtc_api_t::configure API.

The typical steps in using the RTC HAL module in a timing application are:

1. Initialize the RTC using the rtc_api_t::open API
2. Set the time using the rtc_api_t::calendarTimeSet API
3. Set the alarm using the rtc_api_t::calendarAlarmSet API (If required)
4. Start the calendar counter using the rtc_api_t::calendarCounterStart API
5. Get the current time using the rtc_api_t::calendarTimeGet API (as required)

These common steps are illustrated in a typical operational flow diagram in the following figure:

Flow Diagram of a Typical RTC HAL Module Timing Use Application

The typical steps in using the RTC periodic IRQ in an application are:

1. Initialize the RTC using the rtc_api_t::open API.
2. Set periodic IRQ rate using the rtc_api_t::periodicIrqRateSet API.
3. Start calendar counter using the rtc_api_t::calendarCounterStart API.
4. Enable interrupt using the rtc_api_t::irqEnable API.

These common steps are illustrated in a typical operational flow diagram in the following figure:

Flow Diagram of a Typical RTC HAL Module Application