RTC hal

The RTC hal provides a low level interface to the Real Time Counter (RTC) of a target. More...

Modules
	RTC hal tests
	The RTC test validate proper implementation of the RTC hal.

Functions
void	rtc_init (void)
	Initialize the RTC peripheral. More...
void	rtc_free (void)
	Deinitialize RTC. More...
int	rtc_isenabled (void)
	Check if the RTC has the time set and is counting. More...
time_t	rtc_read (void)
	Get the current time from the RTC peripheral. More...
void	rtc_write (time_t t)
	Write the current time in seconds to the RTC peripheral. More...

Detailed Description

The RTC hal provides a low level interface to the Real Time Counter (RTC) of a target.

Defined behaviour

• The function rtc_init is safe to call repeatedly - Verified by test rtc_init_test.
• RTC accuracy is at least 10% - Verified by test rtc_accuracy_test.
• Init/free doesn't stop RTC from counting - Verified by test rtc_persist_test.
• Software reset doesn't stop RTC from counting - Verified by test rtc_reset_test.
• Sleep modes don't stop RTC from counting - Verified by test rtc_sleep_test.
• Shutdown mode doesn't stop RTC from counting - Not verified.
• The functions rtc_write/rtc_read provides availability to set/get RTC time
• Verified by test rtc_write_read_test.
• The functions rtc_isenabled returns 1 if the RTC is counting and the time has been set, 0 otherwise - Verified by test rtc_enabled_test.

Undefined behaviour

• Calling any function other than rtc_init before the initialisation of the RTC

Potential bugs

• Incorrect overflow handling - Verified by rtc_range_test
• Glitches due to ripple counter - Verified by rtc_glitch_test

See also

RTC hal tests

Function Documentation

rtc_init()

void rtc_init

(

void

)

Initialize the RTC peripheral.

Powerup the RTC in perpetration for access. This function must be called before any other RTC functions ares called. This does not change the state of the RTC. It just enables access to it.

Note

This function is safe to call repeatedly - Tested by rtc_init_test

Example Implementation Pseudo Code:

void rtc_init()
{
    // Enable clock gate so processor can read RTC registers
    POWER_CTRL |= POWER_CTRL_RTC_Msk;
 
    // See if the RTC is already setup
    if (!(RTC_STATUS & RTC_STATUS_COUNTING_Msk)) {
 
        // Setup the RTC clock source
        RTC_CTRL |= RTC_CTRL_CLK32_Msk;
    }
}

rtc_free()

void rtc_free

(

void

)

Deinitialize RTC.

Powerdown the RTC in preparation for sleep, powerdown or reset. That should only affect the CPU domain and not the time keeping logic. After this function is called no other RTC functions should be called except for rtc_init.

Note

This function does not stop the RTC from counting - Tested by rtc_persist_test

Example Implementation Pseudo Code:

void rtc_free()
{
    // Disable clock gate since processor no longer needs to read RTC registers
    POWER_CTRL &= ~POWER_CTRL_RTC_Msk;
}

rtc_isenabled()

int rtc_isenabled

(

void

)

Check if the RTC has the time set and is counting.

Return values

0	The time reported by the RTC is not valid
1	The time has been set the RTC is counting

Example Implementation Pseudo Code:

int rtc_isenabled()
{
    if (RTC_STATUS & RTC_STATUS_COUNTING_Msk) {
        return 1;
    } else {
        return 0;
    }
}

rtc_read()

time_t rtc_read

(

void

)

Get the current time from the RTC peripheral.

Returns

The current time in seconds

Note

Some RTCs are not synchronized with the main clock. If this is the case with your RTC then you must read the RTC time in a loop to prevent reading the wrong time due to a glitch. The test rtc_glitch_test is intended to catch this bug.

Example implementation for an unsynchronized ripple counter:

time_t rtc_read()
{
    uint32_t val;
    uint32_t last_val;
 
    // Loop until the same value is read twice
    val = RTC_SECONDS;
    do {
        last_val = val;
        val = RTC_SECONDS;
    } while (last_val != val);
 
    return (time_t)val;
}

rtc_write()

void rtc_write

(

time_t

t

)

Write the current time in seconds to the RTC peripheral.

Parameters

t	The current time to be set in seconds.

Example Implementation Pseudo Code:

void rtc_write(time_t t)
{
    RTC_SECONDS = t;
}