Overview

This section describes the programming interface of the RTC HAL driver. The RTC HAL driver initializes the RTC registers and provides functions to read or modify the RTC registers. These are mostly invoked by the RTC Peripheral driver.

RTC Initialization

The HAL driver provides an initialization function (RTC_HAL_Init()) to reset the RTC module.

RTC Setting and reading the RTC time

The HAL driver provides RTC_HAL_SetDatetime() and RTC_HAL_GetDatetime() functions to set and read the date and time using an instantiation of the rtc_datetime_t structure. These are the structure details:

typedef struct RtcDatetime
{
   uint16_t year;    
   uint16_t month;   
   uint16_t day;     
   uint16_t hour;    
   uint16_t minute;  
   uint8_t second;   
} rtc_datetime_t;

The HAL driver also provides the ability to set and read the date and time in seconds using the RTC_HAL_SetDatetimeInsecs() and RTC_HAL_GetDatetimeInsecs() functions.

Note that, if the RTC counter clock is not 32 KHz, the RTC_HAL_SetDatetime() and RTC_HAL_GetDatetime() functions do not provide accurate results. On such boards, use the RTC_HAL_SetDatetimeInsecs() and RTC_HAL_GetDatetimeInsecs() functions and adjust the second calculation taking into account the clock source difference. The RTC peripheral driver adjusts its seconds calculation if the clock feeding RTC counter clock is not 32 KHz. Use the peripheral driver instead of calling the HAL functions directly.

IRTC Setting and reading the Alarm

The HAL driver provides RTC_HAL_SetAlarm() and RTC_HAL_GetAlarm() functions to set an alarm and read back the alarm time.

Data Structures
struct	rtc_datetime_t
	Structure is used to hold the time in a simple "date" format. More...

Enumerations
enum	rtc_status_t { kStatusRtcSuccess = 0x00U, kStatusRtcFail = 0x01U }
	Error codes for RTC driver. More...

RTC HAL API Functions
void	RTC_HAL_Init (RTC_Type *base)
	Clears all interrupts. More...

void	RTC_HAL_ConvertSecsToDatetime (const uint32_t seconds, rtc_datetime_t datetime)
	Converts seconds to date time format data structure. More...

bool	RTC_HAL_IsDatetimeCorrectFormat (const rtc_datetime_t *datetime)
	Checks whether the date time structure elements have the information that is within the range. More...

void	RTC_HAL_ConvertDatetimeToSecs (const rtc_datetime_t datetime, uint32_t seconds)
	Converts the date time format data structure to seconds. More...

void	RTC_HAL_SetDatetime (RTC_Type base, const rtc_datetime_t datetime)
	Sets the RTC date and time according to a given time structure. More...

void	RTC_HAL_SetDatetimeInsecs (RTC_Type *base, const uint32_t seconds)
	Sets the RTC date and time according to the given time provided in seconds. More...

void	RTC_HAL_GetDatetime (RTC_Type base, rtc_datetime_t datetime)
	Gets the RTC time and stores it in the given time structure. More...

void	RTC_HAL_GetDatetimeInSecs (RTC_Type base, uint32_t seconds)
	Gets the RTC time and returns it in seconds. More...

void	RTC_HAL_GetAlarm (RTC_Type base, rtc_datetime_t date)
	Reads the value of the time alarm. More...

bool	RTC_HAL_SetAlarm (RTC_Type base, const rtc_datetime_t date)
	Sets the RTC alarm time and enables the alarm interrupt. More...

RTC register access functions
static uint32_t	RTC_HAL_GetSecsReg (RTC_Type *base)
	Reads the value of the time seconds counter. More...

static void	RTC_HAL_SetSecsReg (RTC_Type *base, const uint32_t seconds)
	Writes to the time seconds counter. More...

static void	RTC_HAL_SetAlarmReg (RTC_Type *base, const uint32_t seconds)
	Sets the time alarm and clears the time alarm flag. More...

static uint32_t	RTC_HAL_GetAlarmReg (RTC_Type *base)
	Gets the time alarm register contents. More...

static uint16_t	RTC_HAL_GetPrescaler (RTC_Type *base)
	Reads the value of the time prescaler. More...

static void	RTC_HAL_SetPrescaler (RTC_Type *base, const uint16_t prescale)
	Sets the time prescaler. More...

static uint32_t	RTC_HAL_GetCompensationReg (RTC_Type *base)
	Reads the time compensation register contents. More...

static void	RTC_HAL_SetCompensationReg (RTC_Type *base, const uint32_t compValue)
	Writes the value to the RTC TCR register. More...

static uint8_t	RTC_HAL_GetCompensationIntervalCounter (RTC_Type *base)
	Reads the current value of the compensation interval counter, which is the field CIC in the RTC TCR register. More...

static uint8_t	RTC_HAL_GetTimeCompensationValue (RTC_Type *base)
	Reads the current value used by the compensation logic for the present second interval. More...

static uint8_t	RTC_HAL_GetCompensationIntervalRegister (RTC_Type *base)
	Reads the compensation interval register. More...

static void	RTC_HAL_SetCompensationIntervalRegister (RTC_Type *base, const uint8_t value)
	Writes the compensation interval. More...

static uint8_t	RTC_HAL_GetTimeCompensationRegister (RTC_Type *base)
	Reads the time compensation value which is the configured number of 32.768 kHz clock cycles in each second. More...

static void	RTC_HAL_SetTimeCompensationRegister (RTC_Type *base, const uint8_t compValue)
	Writes to the field Time Compensation Register (TCR) of the RTC Time Compensation Register (RTC_TCR). More...

static void	RTC_HAL_SetOsc2pfLoadCmd (RTC_Type *base, bool enable)
	Enables/disables the oscillator configuration for the 2pF load. More...

static bool	RTC_HAL_GetOsc2pfLoad (RTC_Type *base)
	Reads the oscillator 2pF load configure bit. More...

static void	RTC_HAL_SetOsc4pfLoadCmd (RTC_Type *base, bool enable)
	Enables/disables the oscillator configuration for the 4pF load. More...

static bool	RTC_HAL_GetOsc4pfLoad (RTC_Type *base)
	Reads the oscillator 4pF load configuration bit. More...

static void	RTC_HAL_SetOsc8pfLoadCmd (RTC_Type *base, bool enable)
	Enables/disables the oscillator configuration for the 8pF load. More...

static bool	RTC_HAL_GetOsc8pfLoad (RTC_Type *base)
	Reads the oscillator 8pF load configuration bit. More...

static void	RTC_HAL_SetOsc16pfLoadCmd (RTC_Type *base, bool enable)
	Enables/disables the oscillator configuration for the 16pF load. More...

static bool	RTC_HAL_GetOsc16pfLoad (RTC_Type *base)
	Reads the oscillator 16pF load configuration bit. More...

static void	RTC_HAL_SetClockOutCmd (RTC_Type *base, bool enable)
	Enables/disables the 32 kHz clock output to other peripherals. More...

static bool	RTC_HAL_GetClockOutCmd (RTC_Type *base)
	Reads the RTC_CR CLKO bit. More...

static void	RTC_HAL_SetOscillatorCmd (RTC_Type *base, bool enable)
	Enables/disables the oscillator. More...

static bool	RTC_HAL_IsOscillatorEnabled (RTC_Type *base)
	Reads the RTC_CR OSCE bit. More...

static void	RTC_HAL_SoftwareReset (RTC_Type *base)
	Performs a software reset on the RTC module. More...

static void	RTC_HAL_SoftwareResetFlagClear (RTC_Type *base)
	Clears the software reset flag. More...

static bool	RTC_HAL_ReadSoftwareResetStatus (RTC_Type *base)
	Reads the RTC_CR SWR bit. More...

static bool	RTC_HAL_IsCounterEnabled (RTC_Type *base)
	Reads the time counter status (enabled/disabled). More...

static void	RTC_HAL_EnableCounter (RTC_Type *base, bool enable)
	Changes the time counter status. More...

static bool	RTC_HAL_HasAlarmOccured (RTC_Type *base)
	Checks whether the configured time alarm has occurred. More...

static bool	RTC_HAL_IsTimeInvalid (RTC_Type *base)
	Checks whether the time has been marked as invalid. More...

static bool	RTC_HAL_IsSecsIntEnabled (RTC_Type *base)
	Checks whether the Time Seconds Interrupt is enabled/disabled. More...

static void	RTC_HAL_SetSecsIntCmd (RTC_Type *base, bool enable)
	Enables/disables the Time Seconds Interrupt. More...

static bool	RTC_HAL_ReadAlarmInt (RTC_Type *base)
	Checks whether the Time Alarm Interrupt is enabled/disabled. More...

static void	RTC_HAL_SetAlarmIntCmd (RTC_Type *base, bool enable)
	Enables/disables the Time Alarm Interrupt. More...

static void	RTC_HAL_SetTimeOverflowIntCmd (RTC_Type *base, bool enable)
	Enables/disables the Time Overflow Interrupt. More...

static void	RTC_HAL_SetTimeInvalidIntCmd (RTC_Type *base, bool enable)
	Enables/disables the Time Invalid Interrupt. More...

Data Structure Documentation

struct rtc_datetime_t

Data Fields
uint16_t	year
	Range from 1970 to 2099. More...

uint16_t	month
	Range from 1 to 12. More...

uint16_t	day
	Range from 1 to 31 (depending on month). More...

uint16_t	hour
	Range from 0 to 23. More...

uint16_t	minute
	Range from 0 to 59. More...

uint8_t	second
	Range from 0 to 59. More...

Field Documentation

uint16_t rtc_datetime_t::year

uint16_t rtc_datetime_t::month

uint16_t rtc_datetime_t::day

uint16_t rtc_datetime_t::hour

uint16_t rtc_datetime_t::minute

uint8_t rtc_datetime_t::second

Enumeration Type Documentation

enum rtc_status_t

Enumerator
kStatusRtcSuccess	RTC success status.
kStatusRtcFail	RTC error status.

Function Documentation

void RTC_HAL_Init ( RTC_Type * base )

This function initiates a soft-reset of the RTC module if the time invalid flag is set.

Parameters

base	The RTC base address pointer.

void RTC_HAL_ConvertSecsToDatetime	(	const uint32_t *	seconds,
		rtc_datetime_t *	datetime
	)

Parameters

seconds	holds the date and time information in seconds
datetime	holds the converted information from seconds in date and time format

bool RTC_HAL_IsDatetimeCorrectFormat ( const rtc_datetime_t * datetime )

Parameters

datetime holds the date and time information that needs to be converted to seconds

Returns: returns true if the datetime argument has the right format, false otherwise

void RTC_HAL_ConvertDatetimeToSecs	(	const rtc_datetime_t *	datetime,
		uint32_t *	seconds
	)

Parameters

datetime	holds the date and time information that needs to be converted to seconds
seconds	holds the converted date and time in seconds

void RTC_HAL_SetDatetime	(	RTC_Type *	base,
		const rtc_datetime_t *	datetime
	)

The function converts the data from the time structure to seconds and writes the seconds value to the RTC register. The RTC counter is started after setting the time.

Parameters

base	The RTC base address pointer
datetime	[in] Pointer to structure where the date and time details to set are stored.

void RTC_HAL_SetDatetimeInsecs	(	RTC_Type *	base,
		const uint32_t	seconds
	)

The RTC counter is started after setting the time.

Parameters

base	The RTC base address pointer
seconds	[in] Time in seconds

void RTC_HAL_GetDatetime	(	RTC_Type *	base,
		rtc_datetime_t *	datetime
	)

The function reads the value in seconds from the RTC register. It then converts to the time structure which provides the time in date, hour, minutes, and seconds.

Parameters

base	The RTC base address pointer
datetime	[out] pointer to a structure where the date and time details are stored.

void RTC_HAL_GetDatetimeInSecs	(	RTC_Type *	base,
		uint32_t *	seconds
	)

Parameters

base	The RTC base address pointer
seconds	[out] pointer to variable where the RTC time is stored in seconds

void RTC_HAL_GetAlarm	(	RTC_Type *	base,
		rtc_datetime_t *	date
	)

Parameters

base	The RTC base address pointer
date	[out] pointer to a variable where the alarm date and time details are stored.

bool RTC_HAL_SetAlarm	(	RTC_Type *	base,
		const rtc_datetime_t *	date
	)

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

base	The RTC base address pointer.
date	[in] pointer to structure where the alarm date and time details will be stored at.

Returns: true: success in setting the RTC alarm false: error in setting the RTC alarm.

static uint32_t RTC_HAL_GetSecsReg ( RTC_Type * base )

inlinestatic

The time counter reads as zero if either the SR[TOF] or the SR[TIF] is set.

Parameters

base	The RTC base address pointer.

Returns: contents of the seconds register.

static void RTC_HAL_SetSecsReg	(	RTC_Type *	base,
		const uint32_t	seconds
	)

inlinestatic

When the time counter is enabled, the TSR is read only and increments once every second provided the SR[TOF] or SR[TIF] is not set. When the time counter is disabled, the TSR can be read or written. Writing to the TSR when the time counter is disabled clears the SR[TOF] and/or the SR[TIF]. Writing to the TSR register with zero is supported, but not recommended, since the TSR reads as zero when either the SR[TIF] or the SR[TOF] is set (indicating the time is invalid).

Parameters

base	The RTC base address pointer.
seconds	[in] seconds value.

static void RTC_HAL_SetAlarmReg	(	RTC_Type *	base,
		const uint32_t	seconds
	)

inlinestatic

When the time counter is enabled, the SR[TAF] is set whenever the TAR[TAR] equals the TSR[TSR] and the TSR[TSR] increments. Writing to the TAR clears the SR[TAF].

Parameters

base	The RTC base address pointer.
seconds	[in] alarm value in seconds.

static uint32_t RTC_HAL_GetAlarmReg ( RTC_Type * base )

inlinestatic

Parameters

base	The RTC base address pointer

Returns: contents of the alarm register.

static uint16_t RTC_HAL_GetPrescaler ( RTC_Type * base )

inlinestatic

The time counter reads as zero when either the SR[TOF] or the SR[TIF] is set.

Parameters

base	The RTC base address pointer

Returns: contents of the time prescaler register.

static void RTC_HAL_SetPrescaler	(	RTC_Type *	base,
		const uint16_t	prescale
	)

inlinestatic

When the time counter is enabled, the TPR is read only and increments every 32.768 kHz clock cycle. When the time counter is disabled, the TPR can be read or written. The TSR[TSR] increments when bit 14 of the TPR transitions from a logic one to a logic zero.

Parameters

base	The RTC base address pointer
prescale	Prescaler value

static uint32_t RTC_HAL_GetCompensationReg ( RTC_Type * base )

inlinestatic

Parameters

base	The RTC base address pointer

Returns: time compensation register contents.

static void RTC_HAL_SetCompensationReg	(	RTC_Type *	base,
		const uint32_t	compValue
	)

inlinestatic

Parameters

base	The RTC base address pointer
compValue	value to be written to the compensation register.

static uint8_t RTC_HAL_GetCompensationIntervalCounter ( RTC_Type * base )

inlinestatic

Parameters

base	The RTC base address pointer.

Returns: compensation interval value.

static uint8_t RTC_HAL_GetTimeCompensationValue ( RTC_Type * base )

inlinestatic

Parameters

base	The RTC base address pointer

Returns: time compensation value

static uint8_t RTC_HAL_GetCompensationIntervalRegister ( RTC_Type * base )

inlinestatic

The value is the configured compensation interval in seconds from 1 to 256 to control how frequently the time compensation register should adjust the number of 32.768 kHz cycles in each second. The value is one less than the number of seconds (for example, zero means a configuration for a compensation interval of one second).

Parameters

base	The RTC base address pointer.

Returns: compensation interval in seconds.

static void RTC_HAL_SetCompensationIntervalRegister	(	RTC_Type *	base,
		const uint8_t	value
	)

inlinestatic

This configures the compensation interval in seconds from 1 to 256 to control how frequently the TCR should adjust the number of 32.768 kHz cycles in each second. The value written should be one less than the number of seconds (for example, write zero to configure for a compensation interval of one second). This register is double buffered and writes do not take affect until the end of the current compensation interval.

Parameters

base	The RTC base address pointer.
value	the compensation interval value.

static uint8_t RTC_HAL_GetTimeCompensationRegister ( RTC_Type * base )

inlinestatic

Parameters

base	The RTC base address pointer

Returns: time compensation value.

static void RTC_HAL_SetTimeCompensationRegister	(	RTC_Type *	base,
		const uint8_t	compValue
	)

inlinestatic

Configures the number of 32.768 kHz clock cycles in each second. This register is double buffered and writes do not take affect until the end of the current compensation interval.

Parameters

base	The RTC base address pointer
compValue	value of the time compensation.

static void RTC_HAL_SetOsc2pfLoadCmd	(	RTC_Type *	base,
		bool	enable
	)

inlinestatic

Parameters

base	The RTC base address pointer
enable	can be true or false -true: enables load -false: disables load.

static bool RTC_HAL_GetOsc2pfLoad ( RTC_Type * base )

inlinestatic

Parameters

base	The RTC base address pointer

Returns: true: 2pF additional load enabled. false: 2pF additional load disabled.

static void RTC_HAL_SetOsc4pfLoadCmd	(	RTC_Type *	base,
		bool	enable
	)

inlinestatic

Parameters

base	The RTC base address pointer
enable	can be true or false -true: enables load. -false: disables load

static bool RTC_HAL_GetOsc4pfLoad ( RTC_Type * base )

inlinestatic

Parameters

base	The RTC base address pointer

Returns: true: 4pF additional load enabled. false: 4pF additional load disabled.

static void RTC_HAL_SetOsc8pfLoadCmd	(	RTC_Type *	base,
		bool	enable
	)

inlinestatic

Parameters

base	The RTC base address pointer
enable	can be true or false -true: enables load. -false: disables load.

static bool RTC_HAL_GetOsc8pfLoad ( RTC_Type * base )

inlinestatic

Parameters

base	The RTC base address pointer

Returns: true: 8pF additional load enabled. false: 8pF additional load disabled.

static void RTC_HAL_SetOsc16pfLoadCmd	(	RTC_Type *	base,
		bool	enable
	)

inlinestatic

Parameters

base	The RTC base address pointer
enable	can be true or false -true: enables load. -false: disables load.

static bool RTC_HAL_GetOsc16pfLoad ( RTC_Type * base )

inlinestatic

Parameters

base	The RTC base address pointer

Returns: true: 16pF additional load enabled. false: 16pF additional load disabled.

static void RTC_HAL_SetClockOutCmd	(	RTC_Type *	base,
		bool	enable
	)

inlinestatic

Parameters

base	The RTC base address pointer
enable	can be true or false -true: enables clock out. -false: disables clock out.

static bool RTC_HAL_GetClockOutCmd ( RTC_Type * base )

inlinestatic

Parameters

base	The RTC base address pointer

Returns: true: 32 kHz clock is not output to other peripherals. false: 32 kHz clock is output to other peripherals.

static void RTC_HAL_SetOscillatorCmd	(	RTC_Type *	base,
		bool	enable
	)

inlinestatic

After enabling, waits for the oscillator startup time before enabling the time counter to allow the 32.768 kHz clock time to stabilize.

Parameters

base	The RTC base address pointer
enable	can be true or false -true: enables oscillator. -false: disables oscillator.

static bool RTC_HAL_IsOscillatorEnabled ( RTC_Type * base )

inlinestatic

Parameters

base	The RTC base address pointer

Returns: true: 32.768 kHz oscillator is enabled false: 32.768 kHz oscillator is disabled.

static void RTC_HAL_SoftwareReset ( RTC_Type * base )

inlinestatic

This resets all RTC registers except for the SWR bit and the RTC_WAR and RTC_RAR registers. The SWR bit is cleared after VBAT POR and by software explicitly clearing it. Note that access control features (RTC_WAR and RTC_RAR registers) are not available in all MCUs.

Parameters

base	The RTC base address pointer

static void RTC_HAL_SoftwareResetFlagClear ( RTC_Type * base )

inlinestatic

Parameters

base	The RTC base address pointer

static bool RTC_HAL_ReadSoftwareResetStatus ( RTC_Type * base )

inlinestatic

Parameters

base	The RTC base address pointer

Returns: true: SWR is set. false: SWR is cleared.

static bool RTC_HAL_IsCounterEnabled ( RTC_Type * base )

inlinestatic

Parameters

base	The RTC base address pointer

Returns: -true: time counter is enabled, time seconds register and time prescaler register are not writeable, but increment. -false: time counter is disabled, time seconds register and time prescaler register are writeable, but do not increment.

static void RTC_HAL_EnableCounter	(	RTC_Type *	base,
		bool	enable
	)

inlinestatic

Parameters

base	The RTC base address pointer
enable	can be true or false -true: enables the time counter -false: disables the time counter.

static bool RTC_HAL_HasAlarmOccured ( RTC_Type * base )

inlinestatic

Reads time alarm flag (TAF). This flag is set when the time alarm register (TAR) equals the time seconds register (TSR) and the TSR increments. This flag is cleared by writing the TAR register.

Parameters

base	The RTC base address pointer.

Returns: -true: time alarm has occurred. -false: no time alarm occurred.

static bool RTC_HAL_IsTimeInvalid ( RTC_Type * base )

inlinestatic

Reads the value of RTC Status Register (RTC_SR), field Time Invalid Flag (TIF). This flag is set on VBAT POR or software reset. The TSR and TPR do not increment and read as zero when this bit is set. This flag is cleared by writing the TSR register when the time counter is disabled.

Parameters

base	The RTC base address pointer.

Returns: -true: time is INVALID and time counter is zero. -false: time is valid.

static bool RTC_HAL_IsSecsIntEnabled ( RTC_Type * base )

inlinestatic

Reads the value of field Time Seconds Interrupt Enable (TSIE)of the RTC Interrupt Enable Register (RTC_IER). The seconds interrupt is an edge-sensitive interrupt with a dedicated interrupt vector. It is generated once a second and requires no software overhead (there is no corresponding status flag to clear).

Parameters

base	The RTC base address pointer

Returns: -true: Seconds interrupt is enabled. -false: Seconds interrupt is disabled.

static void RTC_HAL_SetSecsIntCmd	(	RTC_Type *	base,
		bool	enable
	)

inlinestatic

Writes to the field Time Seconds Interrupt Enable (TSIE) of the RTC Interrupt Enable Register (RTC_IER). Note: The seconds interrupt is an edge-sensitive interrupt with a dedicated interrupt vector. It is generated once a second and requires no software overhead (there is no corresponding status flag to clear).

Parameters

base	The RTC base address pointer
enable	can be true or false -true: Seconds interrupt is enabled. -false: Seconds interrupt is disabled.

static bool RTC_HAL_ReadAlarmInt ( RTC_Type * base )

inlinestatic

Reads the field Time Alarm Interrupt Enable (TAIE) value of the RTC Interrupt Enable Register (RTC_IER).

Parameters

base	The RTC base address pointer

Returns: true: Time alarm flag does generate an interrupt. false: Time alarm flag does not generate an interrupt.

static void RTC_HAL_SetAlarmIntCmd	(	RTC_Type *	base,
		bool	enable
	)

inlinestatic

Writes to the field Time Alarm Interrupt Enable (TAIE) of the RTC Interrupt Enable Register (RTC_IER).

Parameters

base	The RTC base address pointer
enable	can be true or false -true: Time alarm flag does generate an interrupt. -false: Time alarm flag does not generate an interrupt.

static void RTC_HAL_SetTimeOverflowIntCmd	(	RTC_Type *	base,
		bool	enable
	)

inlinestatic

Writes to the field Time Overflow Interrupt Enable (TOIE) of the RTC Interrupt Enable Register (RTC_IER).

Parameters

base	The RTC base address pointer
enable	can be true or false -true: Time overflow flag does generate an interrupt. -false: Time overflow flag does not generate an interrupt.

static void RTC_HAL_SetTimeInvalidIntCmd	(	RTC_Type *	base,
		bool	enable
	)

inlinestatic

Writes to the field Time Invalid Interrupt Enable (TIIE) of the RTC Interrupt Enable Register (RTC_IER).

Parameters

base	The RTC base address pointer
enable	can be true or false -true: Time invalid flag does generate an interrupt. -false: Time invalid flag does not generate an interrupt.

Overview

RTC Initialization

RTC Setting and reading the RTC time

IRTC Setting and reading the Alarm

Data Structures

Enumerations

RTC HAL API Functions

RTC register access functions

Data Structure Documentation

Data Fields

Field Documentation

Enumeration Type Documentation

Function Documentation