Overview

This section describes the programming interface of the RTC Peripheral Driver. The RTC Peripheral driver sets and gets the RTC clock, sets and reads the RTC alarm time, and receives notifications when an alarm is triggered.

RTC Peripheral Driver Initialization

To initialize, the user calls the RTC_DRV_Init() function with the RTC instance number. Most SoCs have only one RTC instance. Therefore, the instance number is zero. The driver initialization function un-gates the RTC module clock, initializes the RTC HAL layer driver, and enables the RTC interrupts.

This is an example how to create the rtc_init() function.

// init the rtc module //

RTC_DRV_Init(0);

IRTCS Setting and reading the IRTC time

The RTC driver uses an instantiation of the rtc_datetime_t structure either to configure or read the date and time. Call the RTC_DRV_SetDatetime() function to configure the current date and time and call the RTC_DRV_GetDatetime() function to read the current date and time at a later time. This example shows how to use these functions.

rtc_datetime_t datetimeToSet;
RTC_DRV_Init(0);
datetimeToSet.year = 2013;
datetimeToSet.month = 10;
datetimeToSet.day = 13;
datetimeToSet.hour = 18;
datetimeToSet.minute = 55;
datetimeToSet.second = 30;
// set the datetime //
result = RTC_DRV_SetDatetime(0, &datetime);
// get datetime  //
RTC_DRV_GetDatetime(0, &datetime);
printf("Current datetime: %04hd-%02hd-%02hd %02hd:%02hd:%02hd\r\n",
          datetime.year, datetime.month, datetime.day,
          datetime.hour, datetime.minute, datetime.second);

RTC Triggering an Alarm

Call the RTC_DRV_SetAlarm() function to set the alarm time and call the RTC_DRV_GetAlarm() function to read the configured alarm time. Set the current time using the steps mentioned earlier prior to using the call to set the alarm time. The user can enable the option to trigger an interrupt when an alarm occurs. This is done by either calling the RTC_DRV_SetAlarmIntCmd() function or through an argument to the RTC_DRV_SetAlarm() function. This is an example to set an RTC alarm. This example causes an alarm interrupt to be triggered after 5 minutes.

rtc_datetime_t datetimeToSet;
rtc_datetime_t alrmTimeToSet;
RTC_DRV_Init(0);
datetimeToSet.year = 2013;
datetimeToSet.month = 10;
datetimeToSet.day = 13;
datetimeToSet.hour = 18;
datetimeToSet.minute = 55;
datetimeToSet.second = 30;
RTC_DRV_SetDatetime(0, &datetimeToSet);
alrmTimeToSet.year = datetimeToSet.year;
alrmTimeToSet.month = datetimeToSet.month;
alrmTimeToSet.day = datetimeToSet.day;
alrmTimeToSet.minute = datetimeToSet.minute + 5;
alrmTimeToSet.second = datetimeToSet.second;
RTC_DRV_SetAlarm(0, &alrmTimeToSet, true);

RTC Repeated alarm

To request a repeated alarm, a configuration structure is available to configure the repeat alarm information. These are the structure details:

typedef struct RtcRepeatAlarmState
{
    rtc_datetime_t alarmTime;         
    rtc_datetime_t alarmRepTime;   
} rtc_repeat_alarm_state_t;

Call the RTC_DRV_InitRepeatAlarm() function and provide the repeat alarm configuration structure to the RTC driver. The user should not free this structure because the RTC driver stores the pointer to this structure to configure the future alarm times.

This is an example to set a RTC repeat alarm. The alarm interrupt is triggered after 5 minutes and every minute after that.

rtc_repeat_alarm_state_t alrm_state;
rtc_datetime_t alrmTimeToSet;
rtc_datetime_t alrmReptime;
rtc_datetime_t datetimeToSet;
RTC_DRV_Init(0);
RTC_DRV_InitRepeatAlarm(0, &alrm_state);
RTC_DRV_SetDatetime(0, &datetimeToSet);
alrmTimeToSet.minute = datetimeToSet.minute + 5;
alrmReptime.year = 0;
alrmReptime.month = 0;
alrmReptime.day = 0;
alrmReptime.hour = 0;
alrmReptime.minute = 1;
if(!RTC_DRV_SetAlarmRepeat(0, &alrmTimeToSet, &alrmReptime))
{
    exit_error();
}

RTC Enable and Disable Alarm Interrupts

Call the RTC_DRV_SetAlarmIntCmd() function to enable or disable the RTC alarm interrupt. Call the RTC_DRV_GetAlarmIntCmd() function to get the state of the RTC alarm interrupt bit.

RTC Interrupt handler

The RTC driver provides an interrupt handler for the seconds and alarm interrupts. These handlers clear the status bits. When the repeated alarm is requested, the alarm interrupt handler uses the information provided in the rtc_repeat_alarm_state_t structure to schedule the next alarm.

To add more actions to the default handler, add calls to the functions inside the interrupt handlers RTC_IRQHandler() and RTC_Seconds_IRQHandler() functions.

Data Structures
struct	rtc_repeat_alarm_state_t
	RTC repeated alarm information used by the RTC driver. More...

Functions
bool	RTC_DRV_IsCounterEnabled (uint32_t instance)
	Checks whether the RTC is enabled. More...

void	RTC_DRV_SetSecsIntCmd (uint32_t instance, bool secondsEnable)
	Enables or disables the RTC seconds interrupt. More...

void	RTC_DRV_SetAlarmIntCmd (uint32_t instance, bool alarmEnable)
	Enables or disables the alarm interrupt. More...

bool	RTC_DRV_GetAlarmIntCmd (uint32_t instance)
	Reads the alarm interrupt. More...

bool	RTC_DRV_IsAlarmPending (uint32_t instance)
	Reads the alarm status to see if the alarm is triggered. More...

void	RTC_DRV_SetTimeCompensation (uint32_t instance, uint32_t compensationInterval, uint32_t compensationTime)
	Writes the compensation value to the RTC compensation register. More...

void	RTC_DRV_GetTimeCompensation (uint32_t instance, uint32_t compensationInterval, uint32_t compensationTime)
	Reads the compensation value from the RTC compensation register. More...

void	RTC_DRV_AlarmIntAction (uint32_t instance)
	Action to take when an RTC alarm interrupt is triggered. More...

void	RTC_DRV_SecsIntAction (uint32_t instance)
	Action to take when an RTC seconds interrupt is triggered. More...

Variables
RTC_Type *const	g_rtcBase [RTC_INSTANCE_COUNT]
	Table of base addresses for RTC instances. More...

const IRQn_Type	g_rtcIrqId [RTC_INSTANCE_COUNT]
	Table to save RTC Alarm IRQ numbers for RTC instances. More...

const IRQn_Type	g_rtcSecondsIrqId [RTC_INSTANCE_COUNT]
	Table to save RTC Seconds IRQ numbers for RTC instances. More...

Initialization and Deinitialization
rtc_status_t	RTC_DRV_Init (uint32_t instance)
	Initializes the RTC module. More...

void	RTC_DRV_Deinit (uint32_t instance)
	Disables the RTC module clock gate control. More...

RTC datetime set and get
bool	RTC_DRV_SetDatetime (uint32_t instance, rtc_datetime_t *datetime)
	Sets the RTC date and time according to the given time structure. More...

void	RTC_DRV_GetDatetime (uint32_t instance, rtc_datetime_t *datetime)
	Gets the RTC time and stores it in the given time structure. More...

RTC alarm
bool	RTC_DRV_SetAlarm (uint32_t instance, rtc_datetime_t *alarmTime, bool enableAlarmInterrupt)
	Sets the RTC alarm time and enables the alarm interrupt. More...

void	RTC_DRV_GetAlarm (uint32_t instance, rtc_datetime_t *date)
	Returns the RTC alarm time. More...

void	RTC_DRV_InitRepeatAlarm (uint32_t instance, rtc_repeat_alarm_state_t *repeatAlarmState)
	Initializes the RTC repeat alarm state structure. More...

bool	RTC_DRV_SetAlarmRepeat (uint32_t instance, rtc_datetime_t alarmTime, rtc_datetime_t alarmRepInterval)
	Sets an alarm that is periodically repeated. More...

void	RTC_DRV_DeinitRepeatAlarm (uint32_t instance)
	Deinitializes the RTC repeat alarm state structure. More...

ISR Functions
void	RTC_IRQHandler (void)
	Implements the RTC alarm handler named in the startup code. More...

void	RTC_Seconds_IRQHandler (void)
	Implements the RTC seconds handler named in the startup code. More...

Data Structure Documentation

struct rtc_repeat_alarm_state_t

Data Fields
rtc_datetime_t	alarmTime
	Sets the RTC alarm time. More...

rtc_datetime_t	alarmRepTime
	Period for alarm to repeat, needs alarm interrupt be enabled. More...

Field Documentation

rtc_datetime_t rtc_repeat_alarm_state_t::alarmTime

rtc_datetime_t rtc_repeat_alarm_state_t::alarmRepTime

Function Documentation

rtc_status_t RTC_DRV_Init ( uint32_t instance )

Enables the RTC clock and interrupts if requested by the user.

Parameters

instance The RTC peripheral instance number.

Returns: kStatusRtcSuccess means success; Otherwise means failed.

void RTC_DRV_Deinit ( uint32_t instance )

Parameters

instance The RTC peripheral instance number.

bool RTC_DRV_IsCounterEnabled ( uint32_t instance )

The function checks the TCE bit in the RTC control register.

Parameters

instance The RTC peripheral instance number.

Returns: true: The RTC counter is enabled
false: The RTC counter is disabled

bool RTC_DRV_SetDatetime	(	uint32_t	instance,
		rtc_datetime_t *	datetime
	)

The RTC counter is started after the time is set.

Parameters

instance	The RTC peripheral instance number.
datetime	[in] pointer to structure where the date and time details to set are stored.

Returns: true: success in setting the time and starting the RTC
false: failure. An error occurs because the datetime format is incorrect.

void RTC_DRV_GetDatetime	(	uint32_t	instance,
		rtc_datetime_t *	datetime
	)

Parameters

instance	The RTC peripheral instance number.
datetime	[out] pointer to structure where the date and time details are stored.

void RTC_DRV_SetSecsIntCmd	(	uint32_t	instance,
		bool	secondsEnable
	)

Parameters

instance	The RTC peripheral instance number.
secondsEnable	Takes true or false true: indicates seconds interrupt should be enabled false: indicates seconds interrupt should be disabled

bool RTC_DRV_SetAlarm	(	uint32_t	instance,
		rtc_datetime_t *	alarmTime,
		bool	enableAlarmInterrupt
	)

The function checks whether the specified alarm time is greater than the present time. If not, the function does not set the alarm and returns an error.

Parameters

instance	The RTC peripheral instance number.
alarmTime	[in] pointer to structure where the alarm time is stored.
enableAlarmInterrupt	Takes true of false true: indicates alarm interrupt should be enabled false: indicates alarm interrupt should be disabled

Returns: true: success in setting the RTC alarm
false: error in setting the RTC alarm. Error occurs because the alarm datetime format is incorrect.

void RTC_DRV_GetAlarm	(	uint32_t	instance,
		rtc_datetime_t *	date
	)

Parameters

instance	The RTC peripheral instance number.
date	[out] pointer to structure where the alarm date and time details are stored.

void RTC_DRV_InitRepeatAlarm	(	uint32_t	instance,
		rtc_repeat_alarm_state_t *	repeatAlarmState
	)

The RTC driver uses this user-provided structure to store the alarm state information.

Parameters

instance	The RTC peripheral instance number.
repeatAlarmState	Pointer to structure where the alarm state is stored

bool RTC_DRV_SetAlarmRepeat	(	uint32_t	instance,
		rtc_datetime_t *	alarmTime,
		rtc_datetime_t *	alarmRepInterval
	)

Parameters

instance	The RTC peripheral instance number.
alarmTime	Pointer to structure where the alarm time is provided.
alarmRepInterval	pointer to structure with the alarm repeat interval.

Returns: true: success in setting the RTC alarm
false: error in setting the RTC alarm. Error occurs because the alarm datetime format is incorrect.

void RTC_DRV_DeinitRepeatAlarm ( uint32_t instance )

Parameters

instance The RTC peripheral instance number.

void RTC_DRV_SetAlarmIntCmd	(	uint32_t	instance,
		bool	alarmEnable
	)

Parameters

instance	The RTC peripheral instance number.
alarmEnable	Takes true or false true: indicates alarm interrupt should be enabled false: indicates alarm interrupt should be disabled

bool RTC_DRV_GetAlarmIntCmd ( uint32_t instance )

Parameters

instance The RTC peripheral instance number.

Returns: true: indicates alarm interrupt is enabled
false: indicates alarm interrupt is disabled

bool RTC_DRV_IsAlarmPending ( uint32_t instance )

Parameters

instance The RTC peripheral instance number.

Returns: returns alarm status, for example, returns whether the alarm triggered
true: indicates alarm has occurred
false: indicates alarm has not occurred

void RTC_DRV_SetTimeCompensation	(	uint32_t	instance,
		uint32_t	compensationInterval,
		uint32_t	compensationTime
	)

Parameters

instance	The RTC peripheral instance number.
compensationInterval	User-specified compensation interval that is written to the CIR field in RTC Time Compensation Register (TCR)
compensationTime	User-specified compensation time that is written to the TCR field in RTC Time Compensation Register (TCR)

void RTC_DRV_GetTimeCompensation	(	uint32_t	instance,
		uint32_t *	compensationInterval,
		uint32_t *	compensationTime
	)

Parameters

instance	The RTC peripheral instance number.
compensationInterval	User-specified pointer to store the compensation interval counter. This value is read from the CIC field in RTC Time Compensation Register (TCR)
compensationTime	User-specified pointer to store the compensation time value. This value is read from the TCV field in RTC Time Compensation Register (TCR)

void RTC_IRQHandler ( void )

Handles the RTC alarm interrupt and invokes any callback related to the RTC alarm.

void RTC_Seconds_IRQHandler ( void )

Handles the RTC seconds interrupt and invokes any callback related to the RTC second tick.

void RTC_DRV_AlarmIntAction ( uint32_t instance )

To receive alarms periodically, the RTC_TAR register is updated using the repeat interval.

Parameters

instance The RTC peripheral instance number.

void RTC_DRV_SecsIntAction ( uint32_t instance )

Disables the time seconds interrupt (TSIE) bit.

Parameters

instance The RTC peripheral instance number.

Variable Documentation

RTC_Type* const g_rtcBase[RTC_INSTANCE_COUNT]

const IRQn_Type g_rtcIrqId[RTC_INSTANCE_COUNT]

const IRQn_Type g_rtcSecondsIrqId[RTC_INSTANCE_COUNT]

Overview

RTC Peripheral Driver Initialization

IRTCS Setting and reading the IRTC time

RTC Triggering an Alarm

RTC Repeated alarm

RTC Enable and Disable Alarm Interrupts

RTC Interrupt handler

Data Structures

Functions

Variables

Initialization and Deinitialization

RTC datetime set and get

RTC alarm

ISR Functions

Data Structure Documentation

Data Fields

Field Documentation

Function Documentation

Variable Documentation