Real Time 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)
fsp_err_t	R_RTC_TimeCaptureSet (rtc_ctrl_t *const p_ctrl, rtc_time_capture_t *const p_time_capture)
fsp_err_t	R_RTC_TimeCaptureGet (rtc_ctrl_t *const p_ctrl, rtc_time_capture_t *const p_time_capture)

Detailed Description

Driver for the RTC peripheral on RZ microprocessor. 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 two different interrupt types:

• An alarm interrupt generated on a match of combination of day of the week, hour and minute
• A periodic interrupt generated every 1 month, 1 day, 1 hour, 1 minute, 1 second, 1/2 second, or 1/4 second

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 when using the calendarTimeSet API, the 'day of the week' field is automatically calculated and updated by the driver for the provided date.

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.
Multiplex Interrupt	Enabled Disabled	Disabled	Enable multiplex interrupt for a single driver.

Configurations for Timers > Realtime Clock (r_rtc)

This module can be added to the Stacks tab via New Stack > Timers > Realtime Clock (r_rtc).

Configuration	Options	Default	Description
Name	Name must be a valid C symbol	g_rtc0	Module name.
Frequency Comparison Value	195311 195312	195311	Frequency comparison value. This value is set in the register as it is.
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 Priority	MCU Specific Options		Select the alarm interrupt priority.
Period Interrupt Priority	MCU Specific Options		Select the period interrupt priority.

Note

See section "RTCA0SCMP : RTC Sub Count Compare Register" of the RZ microprocessor manual for more details

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.

Clock Configuration

The RTC HAL module uses the following clock sources:

• Main-clock oscillator

Pin Configuration

This module does not use I/O pins.

Usage Notes

System Initialization

• Even when only running in Periodic Interrupt mode R_RTC_CalendarTimeSet must be called successfully to start the RTC.

rtc_alarm_time_t when Setting Calendar Alarm

• time, min_match, hour_match, sunday_match, ..., or suturday_match is used to set alarm. If other xxx_match flags is set to true, a error is returned when parameter check is enabled.
• To set minute and hour, time, min_match, and hour_match is used. For time, tm_min and tm_hour is only used. Other members of time is ignored. min_match and hour_match must be set to true. If min_match or hour_match is set to false, alarm is set to disabled.
• To set day of the week, sunday_match, ..., or saturday_match is used. Set to true the flag for which you want to set an alarm. If all these flags are set to false, alarm is set to disabled.

rtc_alarm_time_t when Getting Calendar Alarm

• For xxx_match flag, sunday_match, ..., and saturday_match are returned with true in the xxx_match corresponding to the day of the week for which the alarm is set, and false in the xxx_match corresponding to the day of the week for which the alarm is not set. Return hour_match and min_match with true if valid hour and minute are set, and false if invalid hour and minute are set, respectively. Other members are returned with false.
• For time, tm_min and tm_hour are returned with the alarm setting values. Other members are returned with what the user passes as is.

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 = 5,
    .tm_mon  = 11,
    .tm_year = YEARS_SINCE_1900,
};

rtc_time_t get_time;

void rtc_example ()
{
    fsp_err_t err = FSP_SUCCESS;


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


    /* Handle any errors. This function should be defined by the user. */
    handle_error(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;

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

    /* Handle any errors. This function should be defined by the user. */
    handle_error(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;

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

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

    R_RTC_CalendarTimeSet(&g_rtc0_ctrl, &set_time);


    R_RTC_CalendarAlarmSet(&g_rtc0_ctrl, &set_time1);


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

Data Structures
struct	rtc_instance_ctrl_t

---

Data Structure Documentation

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.

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.

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

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

)

rtc_api_t::clockSourceSet is not supported on the RTC.

Return values

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.

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.

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.

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
FSP_ERR_INVALID_ARGUMENT	Invalid periodic IRQ rate value

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
	)

rtc_api_t::errorAdjustmentSet is not supported on the RTC.

Return values

FSP_ERR_UNSUPPORTED

Function not supported in this implementation.

R_RTC_InfoGet()

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

Get RTC clock source and running status information and store it in provided pointer p_rtc_info. Before or immediately after the first call to R_RTC_CalendarTimeSet, RTC_STATUS_STOPPED will be returned. Two PCLKRTC after the first call to R_RTC_CalendarTimeSet, RTC_STATUS_RUNNING will be returned.

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	Callback updated successfully.
FSP_ERR_ASSERTION	A required pointer is NULL.
FSP_ERR_NOT_OPEN	The control block has not been opened

R_RTC_TimeCaptureSet()

fsp_err_t R_RTC_TimeCaptureSet	(	rtc_ctrl_t *const	p_ctrl,
		rtc_time_capture_t *const	p_time_capture
	)

rtc_api_t::timeCaptureSet is not supported on the RTC.

Return values

FSP_ERR_UNSUPPORTED

Function not supported in this implementation.

R_RTC_TimeCaptureGet()

fsp_err_t R_RTC_TimeCaptureGet	(	rtc_ctrl_t *const	p_ctrl,
		rtc_time_capture_t *const	p_time_capture
	)

rtc_api_t::timeCaptureGet is not supported on the RTC.

Return values

FSP_ERR_UNSUPPORTED

Function not supported in this implementation.