Realtime Clock (r_rtc)

Functions
fsp_err_t	R_RTC_Open (rtc_ctrl_t *const p_ctrl, rtc_cfg_t const *const p_cfg)
fsp_err_t	R_RTC_Close (rtc_ctrl_t *const p_ctrl)
fsp_err_t	R_RTC_ClockSourceSet (rtc_ctrl_t *const p_ctrl)
fsp_err_t	R_RTC_CalendarTimeSet (rtc_ctrl_t *const p_ctrl, rtc_time_t *const p_time)
fsp_err_t	R_RTC_CalendarTimeGet (rtc_ctrl_t *const p_ctrl, rtc_time_t *const p_time)
fsp_err_t	R_RTC_CalendarAlarmSet (rtc_ctrl_t *const p_ctrl, rtc_alarm_time_t *const p_alarm)
fsp_err_t	R_RTC_CalendarAlarmGet (rtc_ctrl_t *const p_ctrl, rtc_alarm_time_t *const p_alarm)
fsp_err_t	R_RTC_PeriodicIrqRateSet (rtc_ctrl_t *const p_ctrl, rtc_periodic_irq_select_t const rate)
fsp_err_t	R_RTC_ErrorAdjustmentSet (rtc_ctrl_t *const p_ctrl, rtc_error_adjustment_cfg_t const *const err_adj_cfg)
fsp_err_t	R_RTC_InfoGet (rtc_ctrl_t *const p_ctrl, rtc_info_t *const p_rtc_info)
fsp_err_t	R_RTC_CallbackSet (rtc_ctrl_t *const p_ctrl, void(*p_callback)(rtc_callback_args_t *), void const *const p_context, rtc_callback_args_t *const p_callback_memory)

Detailed Description

Driver for the RTC peripheral on RZ MPUs. This module implements the RTC Interface.

Overview

The RTC HAL module configures the RTC module and controls clock, calendar and alarm functions. A callback can be used to respond to the alarm and periodic interrupt.

Features

• RTC time and date get and set.
• RTC time and date alarm get and set.
• RTC alarm and periodic event notification.

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/2, 1/4, 1/8, 1/16, 1/32, 1/64, or 1/128 second(s)
• A carry interrupt is used internally when reading time from the RTC calender to get accurant time readings.

  Note

  See section "Reading 64-Hz Counter and Time" of the User's Manual for more details.
  

  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 alarm and periodic interrupt. 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.

Date and Time validation

"Parameter Checking" needs to be enabled if date and time validation is required for calendarTimeSet and 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 the 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.

Clock error adjustment (Time Error Adjustment Function)

The time error adjustment function is used to correct errors, running fast or slow, in the time caused by variation in the precision of oscillation by the clock oscillator. Because 32,768 cycles of the clock oscillator constitute 1 second of operation when the clock oscillator is selected, the clock runs fast if the clock frequency is high and slow if the clock frequency is low. The time error adjustment functions include:

• Automatic adjustment
• Adjustment by software

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

Note

RTC driver configurations do not do error adjustment internally while initiliazing the driver. Application must make calls to the error adjustment api's for desired adjustment. See section "Time Error Adjustment Function" of the User's Manual for more details on this feature

External Clock Bypass Mode

This MPU supports bypassing the RTC's oscillator circuit, which typically requires an AC clock signal from a crystal oscillator. However, a DC clock signal can be directly input via the RTXIN pin. Therefore the clock mode for the RTC can be changed as the follows:

• Crystal Oscillator Mode
• External Clock Bypass Mode

Configuration

Build Time Configurations for r_rtc

The following build time configurations are defined in fsp_cfg/r_rtc_cfg.h:

Configuration	Options	Default	Description
Parameter Checking	Default (BSP) Enabled Disabled	Default (BSP)	If selected code for parameter checking is included in the build.

Configurations for Timers > Realtime Clock (r_rtc)

This module can be added to the Stacks tab via New Stack > Timers > Realtime Clock (r_rtc). Non-secure callable guard functions can be generated for this module by right clicking the module in the RA Configuration tool and checking the "Non-secure Callable" box.

Configuration	Options	Default	Description
Name	Name must be a valid C symbol	g_rtc0	Module name.
External Clock Bypass Mode	Crystal Oscillator External Clock Bypass	Crystal Oscillator	Receive the clock from either a crystal oscillator or directly from a clock source by inputting it to the RTXIN pin only.
Automatic Adjustment Mode	Enabled Disabled	Enabled	Enable/ Disable the Error Adjustment mode
Automatic Adjustment Period	10 Seconds 1 Minute NONE	10 Seconds	Select the Error Adjustment Period for Automatic Adjustment
Adjustment Type (Plus-Minus)	NONE Addition Subtraction	NONE	Select the Error Adjustment type
Error Adjustment Value	Value must be a positive integer less than equal to 63	0	Specify the Adjustment Value (the number of sub-clock cycles) from the prescaler
Callback	Name must be a valid C symbol	NULL	A user callback function can be provided. If this callback function is provided, it will be called from the interrupt service routine (ISR).
Alarm Interrupt	MCU Specific Options		Enable the Alarm interrupt.
Alarm Interrupt Priority	Value must be a non-negative integer	12	Select the alarm interrupt priority.
Period Interrupt	MCU Specific Options		Enable the Periodic interrupt.
Period Interrupt Priority	Value must be a non-negative integer	12	Select the period interrupt priority.
Carry Interrupt Priority	Value must be a non-negative integer	12	Select the carry interrupt priority.

Interrupt Configuration

To activate interrupts for the RTC module, the desired interrupts must be enabled, The underlying implementation will be expected to handle any interrupts it can support and notify higher layers via callback.

Pin Configuration

This module does not use I/O pins.

Usage Notes

System Initialization

• RTC driver does not start the clock. The application is responsible for ensuring required clocks are started and stable before accessing MCU peripheral registers.

Warning

The 32,768Hz clock oscillator can take seconds to stabilize. The RZ startup code does not wait for the clock oscillator stabilization unless it is the main clock source. The application must ensure the clock oscillator is stable before starting operation.

• Carry interrupt priority must be set to avoid incorrect time returned from calendarTimeGet API during roll-over.
• Even when only running in Periodic Interrupt mode R_RTC_CalendarTimeSet must be called successfully to start the RTC.

Limitations

Developers should be aware of the following limitations when using the RTC:

• R_RTC operates in 24-hour mode.
• Binary-count mode is not supported.
• The R_RTC_CalendarTimeGet() cannot be used from an interrupt that has higher priority than the carry interrupt. Also, it must not be called with interrupts disabled globally, as this API internally uses carry interrupt for its processing. API may return incorrect time if this is done.

Examples

RTC Basic Example

This is a basic example of minimal use of the RTC in an application.

/* rtc_time_t is an alias for the C Standard time.h struct 'tm' */
rtc_time_t set_time =
{
    .tm_sec  = 10,
    .tm_min  = 11,
    .tm_hour = 12,
    .tm_mday = 6,
    .tm_wday = 3,
    .tm_mon  = 11,
    .tm_year = YEARS_SINCE_1900,
};

rtc_time_t get_time;

void rtc_example ()
{
    fsp_err_t err = FSP_SUCCESS;


    /* Open the RTC module */
    err = R_RTC_Open(&g_rtc0_ctrl, &g_rtc0_cfg);


    /* Handle any errors. This function should be defined by the user. */
    assert(FSP_SUCCESS == err);


    /* Set the calendar time */
    R_RTC_CalendarTimeSet(&g_rtc0_ctrl, &set_time);



    /* Get the calendar time */
    R_RTC_CalendarTimeGet(&g_rtc0_ctrl, &get_time);

}

RTC Periodic interrupt example

This is an example of periodic interrupt in RTC.

void rtc_periodic_irq_example ()
{
    fsp_err_t err = FSP_SUCCESS;

    /* Open the RTC module*/
    err = R_RTC_Open(&g_rtc0_ctrl, &g_rtc0_cfg);

    /* Handle any errors. This function should be defined by the user. */
    assert(FSP_SUCCESS == err);

    /* R_RTC_CalendarTimeSet must be called at least once to start the RTC */
    R_RTC_CalendarTimeSet(&g_rtc0_ctrl, &set_time);


    /* Set the periodic interrupt rate to 1 second */
    R_RTC_PeriodicIrqRateSet(&g_rtc0_ctrl, RTC_PERIODIC_IRQ_SELECT_1_SECOND);


    /* Wait for the periodic interrupt */
    while (1)
    {
        /* Wait for interrupt */
    }
}

RTC Alarm interrupt example

This is an example of alarm interrupt in RTC.

void rtc_alarm_irq_example ()
{
    fsp_err_t err = FSP_SUCCESS;

    /*Open the RTC module*/
    err = R_RTC_Open(&g_rtc0_ctrl, &g_rtc0_cfg);

    /* Handle any errors. This function should be defined by the user. */
    assert(FSP_SUCCESS == err);

    R_RTC_CalendarTimeSet(&g_rtc0_ctrl, &set_time1.time);


    R_RTC_CalendarAlarmSet(&g_rtc0_ctrl, &set_time1);


    /* Wait for the Alarm interrupt */
    while (1)
    {
        /* Wait for interrupt */
    }
}

RTC Error Adjustment example

This is an example of modifying error adjustment in RTC.

void rtc_erroradj_example ()
{
    fsp_err_t err = FSP_SUCCESS;

    /*Open the RTC module*/
    R_RTC_Open(&g_rtc0_ctrl, &g_rtc1_cfg);

    R_RTC_CalendarTimeSet(&g_rtc0_ctrl, &set_time1.time);

    /* Modify Error Adjustment after RTC is running */


    err = R_RTC_ErrorAdjustmentSet(&g_rtc0_ctrl, &err_cfg2);
    assert(FSP_SUCCESS == err);

}

Data Structures
struct	rtc_extended_cfg_t
struct	rtc_instance_ctrl_t

Enumerations
enum	rtc_clock_bypass_mode_t

---

Data Structure Documentation

rtc_extended_cfg_t

struct rtc_extended_cfg_t

RTC extend configuration

Data Fields
uint8_t	alarm1_ipl	Alarm 1 interrupt priority.
IRQn_Type	alarm1_irq	Alarm 1 interrupt vector.
rtc_clock_bypass_mode_t	clock_bypass_mode	Clock Bypass Mode.

rtc_instance_ctrl_t

struct rtc_instance_ctrl_t

Channel control block. DO NOT INITIALIZE. Initialization occurs when rtc_api_t::open is called

Data Fields
uint32_t	open
	Whether or not driver is open.
const rtc_cfg_t *	p_cfg
	Pointer to initial configurations.
volatile bool	carry_isr_triggered
	Was the carry isr triggered.

Enumeration Type Documentation

rtc_clock_bypass_mode_t

enum rtc_clock_bypass_mode_t

RTC Clock Bypass Mode

Function Documentation

R_RTC_Open()

fsp_err_t R_RTC_Open	(	rtc_ctrl_t *const	p_ctrl,
		rtc_cfg_t const *const	p_cfg
	)

Opens and configures the RTC driver module. Implements rtc_api_t::open. Configuration includes clock source, and interrupt callback function.

Example:

    /* Open the RTC module */
    err = R_RTC_Open(&g_rtc0_ctrl, &g_rtc0_cfg);

Return values

FSP_SUCCESS	Initialization was successful and RTC has started.
FSP_ERR_ASSERTION	Invalid p_ctrl or p_cfg pointer.
FSP_ERR_ALREADY_OPEN	Module is already open.
FSP_ERR_INVALID_ARGUMENT	Invalid time parameter field.

R_RTC_Close()

fsp_err_t R_RTC_Close

(

rtc_ctrl_t *const

p_ctrl

)

Close the RTC driver. Implements rtc_api_t::close

Return values

FSP_SUCCESS	De-Initialization was successful and RTC driver closed.
FSP_ERR_ASSERTION	Invalid p_ctrl.
FSP_ERR_NOT_OPEN	Driver not open already for close.

R_RTC_ClockSourceSet()

fsp_err_t R_RTC_ClockSourceSet

(

rtc_ctrl_t *const

p_ctrl

)

Implements rtc_api_t::clockSourceSet. Unsupported.

Return values

FSP_SUCCESS	Initialization was successful and RTC has started.
FSP_ERR_ASSERTION	Invalid p_ctrl or p_cfg pointer.
FSP_ERR_NOT_OPEN	Driver is not opened.
FSP_ERR_INVALID_ARGUMENT	Invalid clock source.
FSP_ERR_UNSUPPORTED	Function not supported in this implementation.

R_RTC_CalendarTimeSet()

fsp_err_t R_RTC_CalendarTimeSet	(	rtc_ctrl_t *const	p_ctrl,
		rtc_time_t *const	p_time
	)

Set the calendar time.

Implements rtc_api_t::calendarTimeSet.

Return values

FSP_SUCCESS	Calendar time set operation was successful.
FSP_ERR_ASSERTION	Invalid input argument.
FSP_ERR_NOT_OPEN	Driver not open already for operation.
FSP_ERR_INVALID_ARGUMENT	Invalid time parameter field.

R_RTC_CalendarTimeGet()

fsp_err_t R_RTC_CalendarTimeGet	(	rtc_ctrl_t *const	p_ctrl,
		rtc_time_t *const	p_time
	)

Get the calendar time.

Warning

Do not call this function from a critical section or from an interrupt with higher priority than the carry interrupt, or the time returned may be inaccurate.

Implements rtc_api_t::calendarTimeGet

Return values

FSP_SUCCESS	Calendar time get operation was successful.
FSP_ERR_ASSERTION	Invalid input argument.
FSP_ERR_NOT_OPEN	Driver not open already for operation.
FSP_ERR_IRQ_BSP_DISABLED	User IRQ parameter not valid

R_RTC_CalendarAlarmSet()

fsp_err_t R_RTC_CalendarAlarmSet	(	rtc_ctrl_t *const	p_ctrl,
		rtc_alarm_time_t *const	p_alarm
	)

Set the calendar alarm time.

Implements rtc_api_t::calendarAlarmSet.

Precondition

The calendar counter must be running before the alarm can be set.

Return values

FSP_SUCCESS	Calendar alarm time set operation was successful.
FSP_ERR_INVALID_ARGUMENT	Invalid time parameter field.
FSP_ERR_ASSERTION	Invalid input argument.
FSP_ERR_NOT_OPEN	Driver not open already for operation.
FSP_ERR_IRQ_BSP_DISABLED	User IRQ parameter not valid

R_RTC_CalendarAlarmGet()

fsp_err_t R_RTC_CalendarAlarmGet	(	rtc_ctrl_t *const	p_ctrl,
		rtc_alarm_time_t *const	p_alarm
	)

Get the calendar alarm time.

Implements rtc_api_t::calendarAlarmGet

Return values

FSP_SUCCESS	Calendar alarm time get operation was successful.
FSP_ERR_ASSERTION	Invalid input argument.
FSP_ERR_NOT_OPEN	Driver not open already for operation.

R_RTC_PeriodicIrqRateSet()

fsp_err_t R_RTC_PeriodicIrqRateSet	(	rtc_ctrl_t *const	p_ctrl,
		rtc_periodic_irq_select_t const	rate
	)

Set the periodic interrupt rate and enable periodic interrupt.

Implements rtc_api_t::periodicIrqRateSet

Note

To start the RTC R_RTC_CalendarTimeSet must be called at least once.

Example:

    /* Set the periodic interrupt rate to 1 second */
    R_RTC_PeriodicIrqRateSet(&g_rtc0_ctrl, RTC_PERIODIC_IRQ_SELECT_1_SECOND);

Return values

FSP_SUCCESS	The periodic interrupt rate was successfully set.
FSP_ERR_ASSERTION	Invalid input argument.
FSP_ERR_NOT_OPEN	Driver not open already for operation.
FSP_ERR_IRQ_BSP_DISABLED	User IRQ parameter not valid

R_RTC_ErrorAdjustmentSet()

fsp_err_t R_RTC_ErrorAdjustmentSet	(	rtc_ctrl_t *const	p_ctrl,
		rtc_error_adjustment_cfg_t const *const	err_adj_cfg
	)

This function sets time error adjustment

Implements rtc_api_t::errorAdjustmentSet

Return values

FSP_SUCCESS	Time error adjustment successful.
FSP_ERR_ASSERTION	Invalid input argument.
FSP_ERR_NOT_OPEN	Driver not open for operation.
FSP_ERR_UNSUPPORTED	The clock source is not sub-clock.
FSP_ERR_INVALID_ARGUMENT	Invalid error adjustment value.

R_RTC_InfoGet()

fsp_err_t R_RTC_InfoGet	(	rtc_ctrl_t *const	p_ctrl,
		rtc_info_t *const	p_rtc_info
	)

Set RTC clock source and running status information ad store it in provided pointer p_rtc_info

Implements rtc_api_t::infoGet

Return values

FSP_SUCCESS	Get information Successful.
FSP_ERR_ASSERTION	Invalid input argument.
FSP_ERR_NOT_OPEN	Driver not open already for operation.

R_RTC_CallbackSet()

fsp_err_t R_RTC_CallbackSet	(	rtc_ctrl_t *const	p_ctrl,
		void(*)(rtc_callback_args_t *)	p_callback,
		void const *const	p_context,
		rtc_callback_args_t *const	p_callback_memory
	)

Updates the user callback and has option of providing memory for callback structure. Implements rtc_api_t::callbackSet

Return values

FSP_SUCCESS	Baud rate was successfully changed.
FSP_ERR_ASSERTION	Pointer to RTC control block is NULL or the RTC is not configured to use the internal clock.
FSP_ERR_NOT_OPEN	The control block has not been opened
FSP_ERR_NO_CALLBACK_MEMORY	p_callback is non-secure and p_callback_memory is either secure or NULL.