Overview

The MCUXpresso SDK provides a driver for the Real Time Clock (RTC) of MCUXpresso SDK devices.

Function groups

The RTC driver supports operating the module as a time counter.

Initialization and deinitialization

The function RTC_Init() initializes the RTC with specified configurations. The function RTC_GetDefaultConfig() gets the default configurations.

The function RTC_Deinit() disables the RTC timer and disables the module clock.

Set & Get Datetime

The function RTC_SetDatetime() sets the timer period in seconds. Users pass in the details in date & time format by using the below data structure.

Refer to the driver examples codes located at <SDK_ROOT>/boards/<BOARD>/driver_examples/rtc The function RTC_GetDatetime() reads the current timer value in seconds, converts it to date & time format and stores it into a datetime structure passed in by the user.

Set & Get Alarm

The function RTC_SetAlarm() sets the alarm time period in seconds. Users pass in the details in date & time format by using the datetime data structure.

The function RTC_GetAlarm() reads the alarm time in seconds, converts it to date & time format and stores it into a datetime structure passed in by the user.

Start & Stop timer

The function RTC_StartTimer() starts the RTC time counter.

The function RTC_StopTimer() stops the RTC time counter.

Status

Provides functions to get and clear the RTC status.

Interrupt

Provides functions to enable/disable RTC interrupts and get current enabled interrupts.

RTC Oscillator

Some SoC's allow control of the RTC oscillator through the RTC module.

The function RTC_SetOscCapLoad() allows the user to modify the capacitor load configuration of the RTC oscillator.

Monotonic Counter

Some SoC's have a 64-bit Monotonic counter available in the RTC module.

The function RTC_SetMonotonicCounter() writes a 64-bit to the counter.

The function RTC_GetMonotonicCounter() reads the monotonic counter and returns the 64-bit counter value to the user.

The function RTC_IncrementMonotonicCounter() increments the Monotonic Counter by one.

Typical use case

RTC tick example

Example to set the RTC current time and trigger an alarm. Refer to the driver examples codes located at <SDK_ROOT>/boards/<BOARD>/driver_examples/rtc

Data Structures
struct	_rtc_datetime
	Structure is used to hold the date and time. More...

struct	_rtc_pin_config
	RTC pin config structure. More...

struct	_rtc_config
	RTC config structure. More...

Typedefs
typedef enum _rtc_interrupt_enable	rtc_interrupt_enable_t
	List of RTC interrupts.

typedef enum _rtc_status_flags	rtc_status_flags_t
	List of RTC flags.

typedef enum _rtc_osc_cap_load	rtc_osc_cap_load_t
	List of RTC Oscillator capacitor load settings.

typedef struct _rtc_datetime	rtc_datetime_t
	Structure is used to hold the date and time.

typedef struct _rtc_pin_config	rtc_pin_config_t
	RTC pin config structure.

typedef struct _rtc_config	rtc_config_t
	RTC config structure. More...

Enumerations
enum	_rtc_interrupt_enable { kRTC_TimeInvalidInterruptEnable = (1U << 0U), kRTC_TimeOverflowInterruptEnable = (1U << 1U), kRTC_AlarmInterruptEnable = (1U << 2U), kRTC_MonotonicOverflowInterruptEnable = (1U << 3U), kRTC_SecondsInterruptEnable = (1U << 4U) }
	List of RTC interrupts. More...

enum	_rtc_status_flags { kRTC_TimeInvalidFlag = (1U << 0U), kRTC_TimeOverflowFlag = (1U << 1U), kRTC_AlarmFlag = (1U << 2U), kRTC_MonotonicOverflowFlag = (1U << 3U), kRTC_TamperInterruptDetectFlag = (1U << 4U) }
	List of RTC flags. More...

enum	_rtc_osc_cap_load { kRTC_Capacitor_2p = RTC_CR_SC2P_MASK, kRTC_Capacitor_4p = RTC_CR_SC4P_MASK, kRTC_Capacitor_8p = RTC_CR_SC8P_MASK, kRTC_Capacitor_16p = RTC_CR_SC16P_MASK }
	List of RTC Oscillator capacitor load settings. More...

Functions
static uint32_t	RTC_GetTamperTimeSeconds (RTC_Type *base)
	Get the RTC tamper time seconds. More...

static void	RTC_SetOscCapLoad (RTC_Type *base, uint32_t capLoad)
	This function sets the specified capacitor configuration for the RTC oscillator. More...

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

static void	RTC_EnableWakeUpPin (RTC_Type *base, bool enable)
	Enables or disables the RTC Wakeup Pin Operation. More...

Driver version
#define	FSL_RTC_DRIVER_VERSION (MAKE_VERSION(2, 3, 0))
	Version 2.3.0.

Initialization and deinitialization
void	RTC_Init (RTC_Type base, const rtc_config_t config)
	Ungates the RTC clock and configures the peripheral for basic operation. More...

static void	RTC_Deinit (RTC_Type *base)
	Stops the timer and gate the RTC clock. More...

void	RTC_GetDefaultConfig (rtc_config_t *config)
	Fills in the RTC config struct with the default settings. More...

Current Time & Alarm
status_t	RTC_SetDatetime (RTC_Type base, const rtc_datetime_t datetime)
	Sets the RTC date and time according to the given time structure. More...

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

status_t	RTC_SetAlarm (RTC_Type base, const rtc_datetime_t alarmTime)
	Sets the RTC alarm time. More...

void	RTC_GetAlarm (RTC_Type base, rtc_datetime_t datetime)
	Returns the RTC alarm time. More...

Interrupt Interface
void	RTC_EnableInterrupts (RTC_Type *base, uint32_t mask)
	Enables the selected RTC interrupts. More...

void	RTC_DisableInterrupts (RTC_Type *base, uint32_t mask)
	Disables the selected RTC interrupts. More...

uint32_t	RTC_GetEnabledInterrupts (RTC_Type *base)
	Gets the enabled RTC interrupts. More...

Status Interface
uint32_t	RTC_GetStatusFlags (RTC_Type *base)
	Gets the RTC status flags. More...

void	RTC_ClearStatusFlags (RTC_Type *base, uint32_t mask)
	Clears the RTC status flags. More...

Clock Source Configuration
static void	RTC_EnableOscillatorClock (RTC_Type *base, bool enable)
	Enable/Disable RTC 32kHz Oscillator clock. More...

static void	RTC_SetClockSource (RTC_Type *base)
	Set RTC clock source. More...

static void	RTC_EnableLPOClock (RTC_Type *base, bool enable)
	Enable/Disable RTC 1kHz LPO clock. More...

Timer Start and Stop
static void	RTC_StartTimer (RTC_Type *base)
	Starts the RTC time counter. More...

static void	RTC_StopTimer (RTC_Type *base)
	Stops the RTC time counter. More...

Monotonic counter functions
void	RTC_GetMonotonicCounter (RTC_Type base, uint64_t counter)
	Reads the values of the Monotonic Counter High and Monotonic Counter Low and returns them as a single value. More...

void	RTC_SetMonotonicCounter (RTC_Type *base, uint64_t counter)
	Writes values Monotonic Counter High and Monotonic Counter Low by decomposing the given single value. More...

status_t	RTC_IncrementMonotonicCounter (RTC_Type *base)
	Increments the Monotonic Counter by one. More...

Data Structure Documentation

struct _rtc_datetime

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

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

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

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

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

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

Field Documentation

uint16_t _rtc_datetime::year

uint8_t _rtc_datetime::month

uint8_t _rtc_datetime::day

uint8_t _rtc_datetime::hour

uint8_t _rtc_datetime::minute

uint8_t _rtc_datetime::second

struct _rtc_pin_config

Data Fields
bool	inputLogic
	true: Tamper pin input data is logic one. More...

bool	pinActiveLow
	true: Tamper pin is active low. More...

bool	filterEnable
	true: Input filter is enabled on the tamper pin. More...

bool	pullSelectNegate
	true: Tamper pin pull resistor direction will negate the tamper pin. More...

bool	pullEnable
	true: Pull resistor is enabled on tamper pin. More...

Field Documentation

bool _rtc_pin_config::inputLogic

false: Tamper pin input data is logic zero.

bool _rtc_pin_config::pinActiveLow

false: Tamper pin is active high.

bool _rtc_pin_config::filterEnable

false: Input filter is disabled on the tamper pin.

bool _rtc_pin_config::pullSelectNegate

false: Tamper pin pull resistor direction will assert the tamper pin.

bool _rtc_pin_config::pullEnable

false: Pull resistor is disabled on tamper pin.

struct _rtc_config

This structure holds the configuration settings for the RTC peripheral. To initialize this structure to reasonable defaults, call the RTC_GetDefaultConfig() function and pass a pointer to your config structure instance.

The config struct can be made const so it resides in flash

Data Fields
bool	wakeupSelect
	true: Wakeup pin outputs the 32 KHz clock; false:Wakeup pin used to wakeup the chip

bool	updateMode
	true: Registers can be written even when locked under certain conditions, false: No writes allowed when registers are locked

bool	supervisorAccess
	true: Non-supervisor accesses are allowed; false: Non-supervisor accesses are not supported

uint32_t	compensationInterval
	Compensation interval that is written to the CIR field in RTC TCR Register.

uint32_t	compensationTime
	Compensation time that is written to the TCR field in RTC TCR Register.

Typedef Documentation

typedef struct _rtc_config rtc_config_t

This structure holds the configuration settings for the RTC peripheral. To initialize this structure to reasonable defaults, call the RTC_GetDefaultConfig() function and pass a pointer to your config structure instance.

The config struct can be made const so it resides in flash

Enumeration Type Documentation

enum _rtc_interrupt_enable

Enumerator
kRTC_TimeInvalidInterruptEnable	Time invalid interrupt.
kRTC_TimeOverflowInterruptEnable	Time overflow interrupt.
kRTC_AlarmInterruptEnable	Alarm interrupt.
kRTC_MonotonicOverflowInterruptEnable	Monotonic Overflow Interrupt Enable.
kRTC_SecondsInterruptEnable	Seconds interrupt.

enum _rtc_status_flags

Enumerator
kRTC_TimeInvalidFlag	Time invalid flag.
kRTC_TimeOverflowFlag	Time overflow flag.
kRTC_AlarmFlag	Alarm flag.
kRTC_MonotonicOverflowFlag	Monotonic Overflow Flag.
kRTC_TamperInterruptDetectFlag	Tamper interrupt detect flag.

enum _rtc_osc_cap_load

Enumerator
kRTC_Capacitor_2p	2 pF capacitor load
kRTC_Capacitor_4p	4 pF capacitor load
kRTC_Capacitor_8p	8 pF capacitor load
kRTC_Capacitor_16p	16 pF capacitor load

Function Documentation

void RTC_Init	(	RTC_Type *	base,
		const rtc_config_t *	config
	)

This function issues a software reset if the timer invalid flag is set.

Note: This API should be called at the beginning of the application using the RTC driver.

Parameters

base	RTC peripheral base address
config	Pointer to the user's RTC configuration structure.

static void RTC_Deinit ( RTC_Type * base )

inlinestatic

Parameters

base	RTC peripheral base address

void RTC_GetDefaultConfig ( rtc_config_t * config )

The default values are as follows.

*    config->wakeupSelect = false;
*    config->updateMode = false;
*    config->supervisorAccess = false;
*    config->compensationInterval = 0;
*    config->compensationTime = 0;
* 

Parameters

config Pointer to the user's RTC configuration structure.

status_t RTC_SetDatetime	(	RTC_Type *	base,
		const rtc_datetime_t *	datetime
	)

The RTC counter must be stopped prior to calling this function because writes to the RTC seconds register fail if the RTC counter is running.

Parameters

base	RTC peripheral base address
datetime	Pointer to the structure where the date and time details are stored.

Returns: kStatus_Success: Success in setting the time and starting the RTC kStatus_InvalidArgument: Error because the datetime format is incorrect

void RTC_GetDatetime	(	RTC_Type *	base,
		rtc_datetime_t *	datetime
	)

Parameters

base	RTC peripheral base address
datetime	Pointer to the structure where the date and time details are stored.

status_t RTC_SetAlarm	(	RTC_Type *	base,
		const rtc_datetime_t *	alarmTime
	)

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	RTC peripheral base address
alarmTime	Pointer to the structure where the alarm time is stored.

Returns: kStatus_Success: success in setting the RTC alarm kStatus_InvalidArgument: Error because the alarm datetime format is incorrect kStatus_Fail: Error because the alarm time has already passed

void RTC_GetAlarm	(	RTC_Type *	base,
		rtc_datetime_t *	datetime
	)

Parameters

base	RTC peripheral base address
datetime	Pointer to the structure where the alarm date and time details are stored.

void RTC_EnableInterrupts	(	RTC_Type *	base,
		uint32_t	mask
	)

Parameters

base	RTC peripheral base address
mask	The interrupts to enable. This is a logical OR of members of the enumeration rtc_interrupt_enable_t

void RTC_DisableInterrupts	(	RTC_Type *	base,
		uint32_t	mask
	)

Parameters

base	RTC peripheral base address
mask	The interrupts to enable. This is a logical OR of members of the enumeration rtc_interrupt_enable_t

uint32_t RTC_GetEnabledInterrupts ( RTC_Type * base )

Parameters

base	RTC peripheral base address

Returns: The enabled interrupts. This is the logical OR of members of the enumeration rtc_interrupt_enable_t

uint32_t RTC_GetStatusFlags ( RTC_Type * base )

Parameters

base	RTC peripheral base address

Returns: The status flags. This is the logical OR of members of the enumeration rtc_status_flags_t

void RTC_ClearStatusFlags	(	RTC_Type *	base,
		uint32_t	mask
	)

Parameters

base	RTC peripheral base address
mask	The status flags to clear. This is a logical OR of members of the enumeration rtc_status_flags_t

static void RTC_EnableOscillatorClock	(	RTC_Type *	base,
		bool	enable
	)

inlinestatic

Parameters

base	RTC peripheral base address
enable	Enable/Disable RTC 32.768 kHz clock

Note: After setting this bit, wait the oscillator startup time before enabling the time counter to allow the 32.768 kHz clock time to stabilize.

static void RTC_SetClockSource ( RTC_Type * base )

inlinestatic

Deprecated:: Do not use this function. It has been superceded by RTC_EnableOscillatorClock

Parameters

base	RTC peripheral base address

Note: After setting this bit, wait the oscillator startup time before enabling the time counter to allow the 32.768 kHz clock time to stabilize.

static void RTC_EnableLPOClock	(	RTC_Type *	base,
		bool	enable
	)

inlinestatic

Parameters

base	RTC peripheral base address
enable	Enable/Disable RTC 1kHz LPO clock

Note: After setting this bit, RTC prescaler increments using the LPO 1kHz clock and not the RTC 32kHz crystal clock.

static uint32_t RTC_GetTamperTimeSeconds ( RTC_Type * base )

inlinestatic

Parameters

base	RTC peripheral base address

static void RTC_StartTimer ( RTC_Type * base )

inlinestatic

After calling this function, the timer counter increments once a second provided SR[TOF] or SR[TIF] are not set.

Parameters

base	RTC peripheral base address

static void RTC_StopTimer ( RTC_Type * base )

inlinestatic

RTC's seconds register can be written to only when the timer is stopped.

Parameters

base	RTC peripheral base address

static void RTC_SetOscCapLoad	(	RTC_Type *	base,
		uint32_t	capLoad
	)

inlinestatic

Parameters

base	RTC peripheral base address
capLoad	Oscillator loads to enable. This is a logical OR of members of the enumeration rtc_osc_cap_load_t

static void RTC_Reset ( 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 by software explicitly clearing it.

Parameters

base	RTC peripheral base address

void RTC_GetMonotonicCounter	(	RTC_Type *	base,
		uint64_t *	counter
	)

Parameters

base	RTC peripheral base address
counter	Pointer to variable where the value is stored.

void RTC_SetMonotonicCounter	(	RTC_Type *	base,
		uint64_t	counter
	)

The Monotonic Overflow Flag in RTC_SR is cleared due to the API.

Parameters

base	RTC peripheral base address
counter	Counter value

status_t RTC_IncrementMonotonicCounter ( RTC_Type * base )

Increments the Monotonic Counter (registers RTC_MCLR and RTC_MCHR accordingly) by setting the monotonic counter enable (MER[MCE]) and then writing to the RTC_MCLR register. A write to the monotonic counter low that causes it to overflow also increments the monotonic counter high.

Parameters

base	RTC peripheral base address

Returns: kStatus_Success: success kStatus_Fail: error occurred, either time invalid or monotonic overflow flag was found

static void RTC_EnableWakeUpPin	(	RTC_Type *	base,
		bool	enable
	)

inlinestatic

This function enable or disable RTC Wakeup Pin. The wakeup pin is optional and not available on all devices.

Parameters

base	RTC_Type base pointer.
enable	true to enable, false to disable.

Overview

Function groups

Initialization and deinitialization

Set & Get Datetime

Set & Get Alarm

Start & Stop timer

Status

Interrupt

RTC Oscillator

Monotonic Counter

Typical use case

RTC tick example

Data Structures

Typedefs

Enumerations

Functions

Driver version

Initialization and deinitialization

Current Time & Alarm

Interrupt Interface

Status Interface

Clock Source Configuration

Timer Start and Stop

Monotonic counter functions

Data Structure Documentation

Data Fields

Field Documentation

Data Fields

Field Documentation

Data Fields

Typedef Documentation

Enumeration Type Documentation

Function Documentation