Renesas RTC HAL Application Note

Application Note
Renesas Synergy™ Platform

RTC HAL Module Guide

Introduction

This module guide will enable you to effectiv ely use a module in your own design. Upon completion of this
guide, you will be able to add this module to your own design, configure it correctly for the target application
and write code, using the included application project code as a reference and efficient starting point.
References to more detailed API descriptions and suggestions of other application projects that illustrate
more adv anced uses of the module are av ailable in the Renesas Synergy Knowledge Base (as described in
the References section at the end of this document), and should be valuable resources for creating more
complex designs.

The Real-Time Clock (RT C) HAL module is a high-lev el API for RTC applications and is implement ed on
r_rtc. The RT C HAL module configures the RTC module and controls clock, calendar, and alarm functio n s .

The RTC uses the real-time clock module on the Synergy MCU. A user-defined callback can be created to
respond to any of the three supported interrupt types: alarm, periodic, or carry.

R11AN0059EU0103 Rev.1.03 Page 1 of 14
Mar.20.19

Renesas Synergy™ Platform RTC HA L Module Guide

Contents

1. RTC HAL Module Features ...................................................................................................3

2. RTC APIs Overview ..............................................................................................................3

3. RTC HAL M odule Ope rational Ove rvi ew ................................................................................4

3.1 RTC HAL Module Important Operational Notes and Limitations..................................................... 4

3.1.1 RTC HAL Module Operational Notes....................................................................................... 4

3.1.2 RTC HAL Module Limit ations ................................................................................................. 5

4. Including the RTC HAL Module in an Application ...................................................................5

5. Configuring the RTC HAL Module..........................................................................................5

5.1 RTC HAL Module Clock Configuration ...................................................................................... 7

5.2 RTC HAL Module Pin Configuration .......................................................................................... 7

6. Using the RTC HAL Module in an Application ........................................................................7

7. The RTC HAL Module Application Project..............................................................................8

8. Customizing the RTC HAL Module for a Target Application ..................................................10

8.1 Change interrupt type ........................................................................................................... 10

8.2 Set periodic interrupt rate ...................................................................................................... 10

8.3 Set Alarm interrupt ............................................................................................................... 10

9. Running the RTC HAL Module Application Project ...............................................................10

10. RTC HAL Module Conclusion ..............................................................................................11

11. RTC HAL Module Next Steps ..............................................................................................11

12. RTC HAL Module Reference Information .............................................................................12

Revisio n History .........................................................................................................................14

R11AN0059EU0103 Rev.1.03 Page 2 of 14
Mar.20.19

Renesas Synergy™ Platform RTC HA L Module Guide

Function N ame

Example API Call and Des cription

.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.

.calendarTimeSet

g_rtc0.p_api->calendarTimeSet(g_rtc0.p_ctrl,

Set the calendar time.

.calendarTimeGet

g_rtc0.p_api->calendarTimeGet(g_rtc0.p_ctrl,

Get the calendar time.

.calendarAlarmSet

g_rtc0.p_api->calendarAlarmSet(g_rtc0.p_ctrl,

.calendarAlarmGet

g_rtc0.p_api->calendarAlarmGet(g_rtc0.p_ctrl,

1. RTC HA L Module Features

The RT C HAL module supports the following functions of the real-time clock:

• RT C peripheral configuration

• RT C time and date get and set

• RT C time and date alarm get and set

• RT C time counter start and stop

• RT C alarm, periodic and carry event notification

• RT C ev ent type enable and disable

• RTC event rat e configuration

• RT C clock source get and set

Figure 1. RTC HAL Module Block Diagram

2. RTC APIs Overvi ew

The RTC HAL module defines APIs for opening, closing, setting alarms, starting, and stopping RT C
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 all applicable status return v alues follows the API summary table.

Table 1. RTC H AL Module API Summary

&start_ti me _struc t_ in, true );

¤t_time_struct_out);

&in_alarm_time_struct_in, true);

Set the calendar alarm time.

&get_alarm_time_struct_out);

Get the calendar alarm time.

R11AN0059EU0103 Rev.1.03 Page 3 of 14
Mar.20.19

Renesas Synergy™ Platform RTC HA L Module Guide

.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->irqEn ab le(g_r tc 0. p_ctrl , CA LLBACK );

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->infoG et (g_rtc 0. p_ ctrl, cl k_ src);

.versionGet

g_rtc0.p_api->versionGet(&version);

Retrieve the API v ersion with the version pointer.

Name

Description

SSP_SUCCESS

Function executed successfully

SSP_ERR_ASSERTION

API dependent error

SSP_ERR_INVALID MODE

Inval id mode

SSP_ERR_INVALID_PTR

Inval id paramet er

Return the currently configure clock source for the RTC.

Note: For more complete descriptions of operation and definitions for the function data structures, typed efs,

defines, API data, API structures, and f unction var iables, rev iew the SSP User’s Manual API
References for the associated module.

Table 2. Status Return Values

Note: Lower-lev el driv ers may return common error codes. Refer to the SSP User’s Manual API Ref erences

for the associated mod ule for a definition of all relevant status return v alues.

3. RTC HA L Module Operational Overview

The RTC HAL module controls the operation of the real-time clock module on a Synergy MCU. T he typical
RT C application configures the real-time clo ck 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 R T C application usually consists of calls to the RTC HAL module and
an optional callback from the ISR handler.

• T he RTC HAL module can use two main clock sources:

o A Low Speed On-Chip Oscillator (LOCO) with lower power but less accuracy
o A sub-clock oscillator with higher power, increased accuracy and more cost (external crystal require d)

• T he RTC HAL module supports three differ ent interrupt types:

o An alarm interrupt generated on a match of any combination of year, month, day, day of the week,

hour, minute and second

o A periodic interrupt generated ev ery 2, 1, 1/2, 1/4, 1/8, 1/16, 1/32, 1/64, 1/128, or 1/256 second(s)
o A carry interrupt when ei t her a carry to t he 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 open API call) and will be called from the
interrupt serv ice routine (ISR) for any supported interrupt typ e. 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.

3.1 RT C HAL Module Important Ope rational Notes and Limitations

3.1.1 RT C HA L Modul e Ope r at ional Not e s

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 specif ies the clock source, the name of the user

callback from the ISR handler, and a user-specif ied context for the callback. Conf iguration structures can be
either manually defined or generated by the ISDE based on user input during the configuration process.

R11AN0059EU0103 Rev.1.03 Page 4 of 14
Mar.20.19

Renesas Synergy™ Platform RTC HA L Module Guide

Resource

ISDE Tab

Stacks Selection Sequence

r_rtc0 RTC HAL on r_rtc

Threads

New Stack> Driv er> Timers> RTC HAL on r_rtc

Functions in the driv er 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
configuration. For example, if the name is g_rtc, then the interface structure is called g_rtc_api.

3.1.2 RTC HAL Mod ule Limitations

This module has no support for the following functions:

• Binary-count mode

• Binary alarm get and set

• Binary time get and set

• 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.

4. Including the RTC HA L Module in an A pplication

This section describes how to include the RTC HAL module in an application using the SSP configurator.
Note: It is assumed that 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 RT C Driver to an application, simply add it to a thread using the stacks selection sequence giv en
in the following table. (The def ault name for the RTC is r_rtc0. This name can be changed in the associated

Properties window.)
Table 3. RTC Driver Selection Sequence

When the RTC HAL module on r_rtc is added to the thread stack as shown in the following, the configurator
automatically adds any needed lower-lev el modules. Modules with a Gray band are individual modules that
stand alone.

Figure 2. RTC HAL Module Stack

5. Configuring the RTC HA L Module

The RTC HAL module must be configured for the desired operation. The SSP configuration window
automatically identifies (by highlighting the block in red) any required configuration selections, such as
interrupts or operating modes, which must be configured for lower-lev el modules for successful operation.
Also, only those properties that can be changed without causing conflicts are available for modification.
Other properties are ‘locked’ and are not available for changes, and are identified with a lock icon f or the
‘locked’ property in the Properties window in the ISDE. This approach simplifies the configuration process
and makes it much less error-prone than prev ious ‘manual’ approaches to conf iguration. The available
configuration settings and defaults for all the user-accessible properties are giv en in the Properties tab within
the SSP configurator and are shown in the following tables for easy reference.

R11AN0059EU0103 Rev.1.03 Page 5 of 14
Mar.20.19