RA Flexible Software Package Documentation  Release v5.6.0

 
Realtime Clock (r_rtc_c)

Functions

fsp_err_t R_RTC_C_Open (rtc_ctrl_t *const p_ctrl, rtc_cfg_t const *const p_cfg)
 
fsp_err_t R_RTC_C_Close (rtc_ctrl_t *const p_ctrl)
 
fsp_err_t R_RTC_C_ClockSourceSet (rtc_ctrl_t *const p_ctrl)
 
fsp_err_t R_RTC_C_CalendarTimeSet (rtc_ctrl_t *const p_ctrl, rtc_time_t *const p_time)
 
fsp_err_t R_RTC_C_CalendarTimeGet (rtc_ctrl_t *const p_ctrl, rtc_time_t *const p_time)
 
fsp_err_t R_RTC_C_CalendarAlarmSet (rtc_ctrl_t *const p_ctrl, rtc_alarm_time_t *const p_alarm)
 
fsp_err_t R_RTC_C_CalendarAlarmGet (rtc_ctrl_t *const p_ctrl, rtc_alarm_time_t *const p_alarm)
 
fsp_err_t R_RTC_C_PeriodicIrqRateSet (rtc_ctrl_t *const p_ctrl, rtc_periodic_irq_select_t const rate)
 
fsp_err_t R_RTC_C_InfoGet (rtc_ctrl_t *const p_ctrl, rtc_info_t *const p_rtc_info)
 
fsp_err_t R_RTC_C_ErrorAdjustmentSet (rtc_ctrl_t *const p_ctrl, rtc_error_adjustment_cfg_t const *const err_adj_cfg)
 
fsp_err_t R_RTC_C_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_C_TimeCaptureSet (rtc_ctrl_t *const p_ctrl, rtc_time_capture_t *const p_time_capture)
 
fsp_err_t R_RTC_C_TimeCaptureGet (rtc_ctrl_t *const p_ctrl, rtc_time_capture_t *const p_time_capture)
 

Detailed Description

Driver for the RTC peripheral on RA MCUs. 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

The RTC HAL module supports two different interrupt types:

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. When using the calendarAlarmSet API, minute, hour and day of the week are written to the related registers.

Sub-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 sub-clock oscillator. Because 32,768 cycles of the sub-clock oscillator constitute 1 second of operation when the sub-clock oscillator is selected, the clock runs fast if the sub-clock frequency is high and slow if the sub-clock frequency is low.

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 initializing the driver. Application must make calls to the error adjustment api's for desired adjustment.

Configuration

Build Time Configurations for r_rtc_c

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

ConfigurationOptionsDefaultDescription
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_c)

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

ConfigurationOptionsDefaultDescription
NameName must be a valid C symbolg_rtc0 Module name.
Operation clock
  • FSXP
  • SOSC/256 (128 Hz)
FSXP Select the RTC operation clock. If using 'SOSC/256' as the source for RTCCLK, the FSXP source cannot be LOCO in Clock tab.
CallbackName must be a valid C symbolNULL A user callback function can be provided. If this callback function is provided, it will be called from the interrupt service routine (ISR).
Interrupt PriorityMCU Specific OptionsSelect the period or alarm 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.

Clock Configuration

The RTC HAL module can use the following clock sources(setting in clock page):

Users have to select the right source for their application. Sub-Clock is the default during configuration when it is available.

Pin Configuration

This module does not use I/O pins.

Usage Notes

System Initialization

Warning
The subclock can take seconds to stabilize. The RA startup code does not wait for subclock stabilization unless the subclock is the main clock source. When running AGT or RTC off the subclock, the application must ensure the subclock is stable before starting operation.

Limitations

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

Examples

RTC Basic Example

This is a basic example of minimal use of the RTC_C 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_c_example ()
{
fsp_err_t err = FSP_SUCCESS;
/* Open the RTC module */
err = R_RTC_C_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_C_CalendarTimeSet(&g_rtc0_ctrl, &set_time);
/* Get the calendar time */
R_RTC_C_CalendarTimeGet(&g_rtc0_ctrl, &get_time);
}

RTC Calendar Time Set example

This is an example of setting calendar time in RTC_C.

Warning
The weekday must be set correctly even when parameter checking is disabled.
/* rtc_time_t is an alias for the C Standard time.h struct 'tm' */
rtc_time_t set_calendar_time =
{
.tm_sec = 10,
.tm_min = 11,
.tm_hour = 12,
.tm_mday = 6,
/* tm_wday value must be set correctly */
.tm_wday = 5,
.tm_mon = 11,
.tm_year = YEARS_SINCE_1900,
};
void rtc_c_calendar_time_set_example ()
{
fsp_err_t err = FSP_SUCCESS;
/* Open the RTC module */
err = R_RTC_C_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 and date */
err = R_RTC_C_CalendarTimeSet(&g_rtc0_ctrl, &set_calendar_time);
/* Handle any errors. This function should be defined by the user. */
assert(FSP_SUCCESS == err);
}

RTC Periodic interrupt example

This is an example of periodic interrupt in RTC.

void rtc_c_periodic_irq_example ()
{
fsp_err_t err = FSP_SUCCESS;
/* Open the RTC module*/
err = R_RTC_C_Open(&g_rtc0_ctrl, &g_rtc0_cfg);
/* Handle any errors. This function should be defined by the user. */
assert(FSP_SUCCESS == err);
/* R_RTC_C_CalendarTimeSet must be called at least once to start the RTC */
R_RTC_C_CalendarTimeSet(&g_rtc0_ctrl, &set_time);
/* Set the periodic interrupt rate to 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_c_alarm_irq_example ()
{
fsp_err_t err = FSP_SUCCESS;
/*Open the RTC module*/
err = R_RTC_C_Open(&g_rtc0_ctrl, &g_rtc0_cfg);
/* Handle any errors. This function should be defined by the user. */
assert(FSP_SUCCESS == err);
R_RTC_C_CalendarTimeSet(&g_rtc0_ctrl, &set_time);
R_RTC_C_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_c_erroradj_example ()
{
fsp_err_t err = FSP_SUCCESS;
/*Open the RTC module*/
R_RTC_C_Open(&g_rtc0_ctrl, &g_rtc1_cfg);
R_RTC_C_CalendarTimeSet(&g_rtc0_ctrl, &set_time);
/* Modify Error Adjustment after RTC is running */
err = R_RTC_C_ErrorAdjustmentSet(&g_rtc0_ctrl, &err_cfg2);
assert(FSP_SUCCESS == err);
}

Data Structures

struct  rtc_c_extended_cfg
 
struct  rtc_c_instance_ctrl_t
 

Enumerations

enum  rtc_c_subclock_division_t
 

Data Structure Documentation

◆ rtc_c_extended_cfg

struct rtc_c_extended_cfg

RTC extended configuration

Data Fields
rtc_c_subclock_division_t clock_source_div The sub clock division value.

◆ rtc_c_instance_ctrl_t

struct rtc_c_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_tp_cfg
 Pointer to initial configurations.
 

Enumeration Type Documentation

◆ rtc_c_subclock_division_t

RTC sub_clock division

Enumerator
RTC_CLOCK_SOURCE_SUBCLOCK_DIV_BY_1 

Using sub_clock for rct_c clock.

RTC_CLOCK_SOURCE_SUBCLOCK_DIV_BY_256 

Using (sub_clock / 256) for rct_c clock.

Function Documentation

◆ R_RTC_C_Open()

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

R_RTC_Open should be called to manipulate the RTC instead of setting register directly.

Example:

/* Open the RTC module */
err = R_RTC_C_Open(&g_rtc0_ctrl, &g_rtc0_cfg);
Return values
FSP_SUCCESSInitialization was successful and RTC has started.
FSP_ERR_UNSUPPORTEDInvalid clock source.
FSP_ERR_ALREADY_OPENModule is already open.
FSP_ERR_INVALID_MODESubsystem clock should use SOSC before setting realtime clock to SOSC/256.
FSP_ERR_ASSERTIONInvalid time parameter field.

◆ R_RTC_C_Close()

fsp_err_t R_RTC_C_Close ( rtc_ctrl_t *const  p_ctrl)

Close the RTC driver. Implements rtc_api_t::close

Return values
FSP_SUCCESSDe-Initialization was successful and RTC driver closed.
FSP_ERR_ASSERTIONInvalid p_ctrl.
FSP_ERR_NOT_OPENDriver not open already for close.

◆ R_RTC_C_ClockSourceSet()

fsp_err_t R_RTC_C_ClockSourceSet ( rtc_ctrl_t *const  p_ctrl)

Setting clock source is not supported on the RTC_C.

Return values
FSP_ERR_UNSUPPORTEDPlease set clock source in clock page.

◆ R_RTC_C_CalendarTimeSet()

fsp_err_t R_RTC_C_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_SUCCESSCalendar time set operation was successful.
FSP_ERR_ASSERTIONInvalid input argument.
FSP_ERR_NOT_OPENDriver not open already for operation.
FSP_ERR_INVALID_ARGUMENTInvalid parameter field.

◆ R_RTC_C_CalendarTimeGet()

fsp_err_t R_RTC_C_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_SUCCESSCalendar time get operation was successful.
FSP_ERR_ASSERTIONInvalid input argument.
FSP_ERR_NOT_OPENDriver not open already for operation.

◆ R_RTC_C_CalendarAlarmSet()

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

Set the calendar alarm time. For the p_alarm, only minutes, hours and weekdays are valid. Minutes 0 to 59. Hours 0 to 23. Weekdays 0 to 127.

Implements rtc_api_t::calendarAlarmSet.

Precondition
The calendar counter must be running before the alarm can be set.
Return values
FSP_SUCCESSCalendar alarm time set operation was successful.
FSP_ERR_INVALID_ARGUMENTInvalid time parameter field.
FSP_ERR_ASSERTIONInvalid input argument.
FSP_ERR_NOT_OPENDriver not open already for operation.
FSP_ERR_IRQ_BSP_DISABLEDInterrupt must be enabled to use the alarm.

◆ R_RTC_C_CalendarAlarmGet()

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

Get the calendar alarm time. For the p_alarm, only minutes, hours and weekdays will be got.

Implements rtc_api_t::calendarAlarmGet

Return values
FSP_SUCCESSCalendar alarm time get operation was successful.
FSP_ERR_ASSERTIONInvalid input argument.
FSP_ERR_NOT_OPENDriver not open already for operation.

◆ R_RTC_C_PeriodicIrqRateSet()

fsp_err_t R_RTC_C_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_C_CalendarTimeSet must be called at least once.

Example:

/* Set the periodic interrupt rate to 1 second */
Return values
FSP_SUCCESSThe periodic interrupt rate was successfully set.
FSP_ERR_ASSERTIONInvalid input argument.
FSP_ERR_NOT_OPENDriver not open already for operation.
FSP_ERR_IRQ_BSP_DISABLEDUser IRQ parameter not valid

◆ R_RTC_C_InfoGet()

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

Get RTC_C running status information ad store it in provided pointer p_rtc_info

Implements rtc_api_t::infoGet

Return values
FSP_SUCCESSGet information Successful.
FSP_ERR_ASSERTIONInvalid input argument.
FSP_ERR_NOT_OPENRealtime clock module is stopped.

◆ R_RTC_C_ErrorAdjustmentSet()

fsp_err_t R_RTC_C_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_SUCCESSTime error adjustment successful.
FSP_ERR_ASSERTIONInvalid input argument.
FSP_ERR_NOT_OPENDriver not open for operation.
FSP_ERR_INVALID_ARGUMENTNot under sub-clock or invalid error adjustment value.

◆ R_RTC_C_CallbackSet()

fsp_err_t R_RTC_C_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_SUCCESSBaud rate was successfully changed.
FSP_ERR_ASSERTIONPointer to RTC control block is NULL or the RTC is not configured to use the internal clock.
FSP_ERR_NOT_OPENThe control block has not been opened

◆ R_RTC_C_TimeCaptureSet()

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

Capture is not supported on the RTC_C.

Return values
FSP_ERR_UNSUPPORTEDFunction not supported in this implementation.

◆ R_RTC_C_TimeCaptureGet()

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

Capture is not supported on the RTC_C.

Return values
FSP_ERR_UNSUPPORTEDFunction not supported in this implementation.