RA Flexible Software Package Documentation
Release v5.6.0
|
|
Driver for the RTC peripheral on RA MCUs. This module implements the RTC Interface.
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.
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.
"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.
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.
Configuration | Options | Default | Description |
---|---|---|---|
Parameter Checking |
| Default (BSP) | If selected code for parameter checking is included in the build. |
Configuration | Options | Default | Description |
---|---|---|---|
Name | Name must be a valid C symbol | g_rtc0 | Module name. |
Operation clock |
| FSXP | Select the RTC operation clock. If using 'SOSC/256' as the source for RTCCLK, the FSXP source cannot be LOCO in Clock tab. |
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). |
Interrupt Priority | MCU Specific Options | Select the period or alarm interrupt priority. |
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.
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.
This module does not use I/O pins.
Developers should be aware of the following limitations when using the RTC_C:
This is a basic example of minimal use of the RTC_C in an application.
This is an example of setting calendar time in RTC_C.
This is an example of periodic interrupt in RTC.
This is an example of alarm interrupt in RTC.
This is an example of modifying error adjustment in RTC.
Data Structures | |
struct | rtc_c_extended_cfg |
struct | rtc_c_instance_ctrl_t |
Enumerations | |
enum | rtc_c_subclock_division_t |
struct rtc_c_extended_cfg |
RTC extended configuration
Data Fields | ||
---|---|---|
rtc_c_subclock_division_t | clock_source_div | The sub clock division value. |
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_t * | p_cfg |
Pointer to initial configurations. | |
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:
FSP_SUCCESS | Initialization was successful and RTC has started. |
FSP_ERR_UNSUPPORTED | Invalid clock source. |
FSP_ERR_ALREADY_OPEN | Module is already open. |
FSP_ERR_INVALID_MODE | Subsystem clock should use SOSC before setting realtime clock to SOSC/256. |
FSP_ERR_ASSERTION | Invalid time parameter field. |
fsp_err_t R_RTC_C_Close | ( | rtc_ctrl_t *const | p_ctrl | ) |
Close the RTC driver. Implements rtc_api_t::close
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. |
fsp_err_t R_RTC_C_ClockSourceSet | ( | rtc_ctrl_t *const | p_ctrl | ) |
Setting clock source is not supported on the RTC_C.
FSP_ERR_UNSUPPORTED | Please set clock source in clock page. |
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.
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 parameter field. |
fsp_err_t R_RTC_C_CalendarTimeGet | ( | rtc_ctrl_t *const | p_ctrl, |
rtc_time_t *const | p_time | ||
) |
Get the calendar time.
Implements rtc_api_t::calendarTimeGet
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_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.
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 | Interrupt must be enabled to use the alarm. |
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
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. |
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
Example:
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_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
FSP_SUCCESS | Get information Successful. |
FSP_ERR_ASSERTION | Invalid input argument. |
FSP_ERR_NOT_OPEN | Realtime clock module is stopped. |
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
FSP_SUCCESS | Time error adjustment successful. |
FSP_ERR_ASSERTION | Invalid input argument. |
FSP_ERR_NOT_OPEN | Driver not open for operation. |
FSP_ERR_INVALID_ARGUMENT | Not under sub-clock or invalid error adjustment value. |
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
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_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.
FSP_ERR_UNSUPPORTED | Function not supported in this implementation. |
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.
FSP_ERR_UNSUPPORTED | Function not supported in this implementation. |