RTC Interface

Detailed Description

Interface for accessing the Realtime Clock.

Summary

The RTC Interface is for configuring Real Time Clock (RTC) functionality including alarm, periodic notification and error adjustment.

Data Structures
struct	rtc_callback_args_t
struct	rtc_error_adjustment_cfg_t
struct	rtc_alarm_time_t
struct	rtc_time_capture_t
struct	rtc_info_t
struct	rtc_cfg_t
struct	rtc_api_t
struct	rtc_instance_t

Typedefs
typedef struct tm	rtc_time_t
typedef void	rtc_ctrl_t

Enumerations
enum	rtc_event_t
enum	rtc_alarm_channel_t
enum	rtc_clock_source_t
enum	rtc_status_t
enum	rtc_error_adjustment_t
enum	rtc_error_adjustment_mode_t
enum	rtc_error_adjustment_period_t
enum	rtc_periodic_irq_select_t
enum	rtc_time_capture_source_t
enum	rtc_time_capture_mode_t
enum	rtc_time_capture_noise_filter_t

---

Data Structure Documentation

rtc_callback_args_t

struct rtc_callback_args_t

Callback function parameter data

Data Fields
rtc_event_t	event	The event can be used to identify what caused the callback (compare match or error).
void const *	p_context	Placeholder for user data.

rtc_error_adjustment_cfg_t

struct rtc_error_adjustment_cfg_t

Time error adjustment value configuration

Data Fields
rtc_error_adjustment_mode_t	adjustment_mode	Automatic Adjustment Enable/Disable.
rtc_error_adjustment_period_t	adjustment_period	Error Adjustment period.
rtc_error_adjustment_t	adjustment_type	Time error adjustment setting.
uint32_t	adjustment_value	Value of the prescaler for error adjustment.

rtc_alarm_time_t

struct rtc_alarm_time_t

Alarm time setting structure

Data Fields
rtc_time_t	time	Time structure.
bool	sec_match	Enable the alarm based on a match of the seconds field.
bool	min_match	Enable the alarm based on a match of the minutes field.
bool	hour_match	Enable the alarm based on a match of the hours field.
bool	mday_match	Enable the alarm based on a match of the days field.
bool	mon_match	Enable the alarm based on a match of the months field.
bool	year_match	Enable the alarm based on a match of the years field.
bool	dayofweek_match	Enable the alarm based on a match of the dayofweek field.
bool	sunday_match	Enable the alarm on Sunday.
bool	monday_match	Enable the alarm on Monday.
bool	tuesday_match	Enable the alarm on Tuesday.
bool	wednesday_match	Enable the alarm on Wednesday.
bool	thursday_match	Enable the alarm on Thursday.
bool	friday_match	Enable the alarm on Friday.
bool	saturday_match	Enable the alarm on Saturday.
rtc_alarm_channel_t	channel	Select alarm 0 or alarm 1.

rtc_time_capture_t

struct rtc_time_capture_t

Time capture configuration structure

Data Fields
rtc_time_t	time	Time structure.
uint8_t	channel	Capture channel.
rtc_time_capture_source_t	source	Trigger source.
rtc_time_capture_noise_filter_t	noise_filter	Noise filter.
rtc_time_capture_mode_t	mode	Capture mode.

rtc_info_t

struct rtc_info_t

RTC Information Structure for information returned by infoGet()

Data Fields
rtc_clock_source_t	clock_source	Clock source for the RTC block.
rtc_status_t	status	RTC run status.

rtc_cfg_t

struct rtc_cfg_t

User configuration structure, used in open function

Data Fields
rtc_clock_source_t	clock_source
	Clock source for the RTC block.
uint32_t	freq_compare_value
	The frequency comparison value.
rtc_error_adjustment_cfg_t const *const	p_err_cfg
	Pointer to Error Adjustment configuration.
uint8_t	alarm_ipl
	Alarm interrupt priority.
IRQn_Type	alarm_irq
	Alarm interrupt vector.
uint8_t	periodic_ipl
	Periodic interrupt priority.
IRQn_Type	periodic_irq
	Periodic interrupt vector.
uint8_t	carry_ipl
	Carry interrupt priority.
IRQn_Type	carry_irq
	Carry interrupt vector.
void(*	p_callback )(rtc_callback_args_t *p_args)
	Called from the ISR.
void const *	p_context
	User defined context passed into callback function.
void const *	p_extend
	RTC hardware dependant configuration.

rtc_api_t

struct rtc_api_t

RTC driver structure. General RTC functions implemented at the HAL layer follow this API.

Data Fields
fsp_err_t(*	open )(rtc_ctrl_t *const p_ctrl, rtc_cfg_t const *const p_cfg)
fsp_err_t(*	close )(rtc_ctrl_t *const p_ctrl)
fsp_err_t(*	clockSourceSet )(rtc_ctrl_t *const p_ctrl)
fsp_err_t(*	calendarTimeSet )(rtc_ctrl_t *const p_ctrl, rtc_time_t *const p_time)
fsp_err_t(*	calendarTimeGet )(rtc_ctrl_t *const p_ctrl, rtc_time_t *const p_time)
fsp_err_t(*	calendarAlarmSet )(rtc_ctrl_t *const p_ctrl, rtc_alarm_time_t *const p_alarm)
fsp_err_t(*	calendarAlarmGet )(rtc_ctrl_t *const p_ctrl, rtc_alarm_time_t *const p_alarm)
fsp_err_t(*	periodicIrqRateSet )(rtc_ctrl_t *const p_ctrl, rtc_periodic_irq_select_t const rate)
fsp_err_t(*	errorAdjustmentSet )(rtc_ctrl_t *const p_ctrl, rtc_error_adjustment_cfg_t const *const err_adj_cfg)
fsp_err_t(*	callbackSet )(rtc_ctrl_t *const p_ctrl, void(*p_callback)(rtc_callback_args_t *), void const *const p_context, rtc_callback_args_t *const p_callback_memory)
fsp_err_t(*	infoGet )(rtc_ctrl_t *const p_ctrl, rtc_info_t *const p_rtc_info)
fsp_err_t(*	timeCaptureSet )(rtc_ctrl_t *const p_ctrl, rtc_time_capture_t *const p_time_capture)
fsp_err_t(*	timeCaptureGet )(rtc_ctrl_t *const p_ctrl, rtc_time_capture_t *const p_time_capture)

Field Documentation

open

fsp_err_t(* rtc_api_t::open) (rtc_ctrl_t *const p_ctrl, rtc_cfg_t const *const p_cfg)

Open the RTC driver.

Parameters

[in]	p_ctrl	Pointer to RTC device handle
[in]	p_cfg	Pointer to the configuration structure

close

fsp_err_t(* rtc_api_t::close) (rtc_ctrl_t *const p_ctrl)

Close the RTC driver.

Parameters

[in]

p_ctrl

Pointer to RTC device handle.

clockSourceSet

fsp_err_t(* rtc_api_t::clockSourceSet) (rtc_ctrl_t *const p_ctrl)

Sets the RTC clock source.

Parameters

[in]

p_ctrl

Pointer to RTC device handle

calendarTimeSet

fsp_err_t(* rtc_api_t::calendarTimeSet) (rtc_ctrl_t *const p_ctrl, rtc_time_t *const p_time)

Set the calendar time and start the calendar counter

Parameters

[in]	p_ctrl	Pointer to RTC device handle
[in]	p_time	Pointer to a time structure that contains the time to set

calendarTimeGet

fsp_err_t(* rtc_api_t::calendarTimeGet) (rtc_ctrl_t *const p_ctrl, rtc_time_t *const p_time)

Get the calendar time.

Parameters

[in]	p_ctrl	Pointer to RTC device handle
[out]	p_time	Pointer to a time structure that contains the time to get

calendarAlarmSet

fsp_err_t(* rtc_api_t::calendarAlarmSet) (rtc_ctrl_t *const p_ctrl, rtc_alarm_time_t *const p_alarm)

Set the calendar alarm time and enable the alarm interrupt.

Parameters

[in]	p_ctrl	Pointer to RTC device handle
[in]	p_alarm	Pointer to an alarm structure that contains the alarm time to set

calendarAlarmGet

fsp_err_t(* rtc_api_t::calendarAlarmGet) (rtc_ctrl_t *const p_ctrl, rtc_alarm_time_t *const p_alarm)

Get the calendar alarm time.

Parameters

[in]	p_ctrl	Pointer to RTC device handle
[out]	p_alarm	Pointer to an alarm structure to fill up with the alarm time

periodicIrqRateSet

fsp_err_t(* rtc_api_t::periodicIrqRateSet) (rtc_ctrl_t *const p_ctrl, rtc_periodic_irq_select_t const rate)

Set the periodic irq rate

Parameters

[in]	p_ctrl	Pointer to RTC device handle
[in]	rate	Rate of periodic interrupts

errorAdjustmentSet

fsp_err_t(* rtc_api_t::errorAdjustmentSet) (rtc_ctrl_t *const p_ctrl, rtc_error_adjustment_cfg_t const *const err_adj_cfg)

Set time error adjustment.

Parameters

[in]	p_ctrl	Pointer to control handle structure
[in]	err_adj_cfg	Pointer to the Error Adjustment Config

callbackSet

fsp_err_t(* rtc_api_t::callbackSet) (rtc_ctrl_t *const p_ctrl, void(*p_callback)(rtc_callback_args_t *), void const *const p_context, rtc_callback_args_t *const p_callback_memory)

Specify callback function and optional context pointer and working memory pointer.

Parameters

[in]	p_ctrl	Pointer to the RTC control block.
[in]	p_callback	Callback function
[in]	p_context	Pointer to send to callback function
[in]	p_working_memory	Pointer to volatile memory where callback structure can be allocated

infoGet

fsp_err_t(* rtc_api_t::infoGet) (rtc_ctrl_t *const p_ctrl, rtc_info_t *const p_rtc_info)

Return the currently configure clock source for the RTC

Parameters

[in]	p_ctrl	Pointer to control handle structure
[out]	p_rtc_info	Pointer to RTC information structure

timeCaptureSet

fsp_err_t(* rtc_api_t::timeCaptureSet) (rtc_ctrl_t *const p_ctrl, rtc_time_capture_t *const p_time_capture)

Config Time capture

Parameters

[in]	p_ctrl	Pointer to RTC device handle
[in]	p_time_capture	Pointer to a time capture structure that contains the configuration

timeCaptureGet

fsp_err_t(* rtc_api_t::timeCaptureGet) (rtc_ctrl_t *const p_ctrl, rtc_time_capture_t *const p_time_capture)

Get the capture time and clear bit status.

Parameters

[in]	p_ctrl	Pointer to RTC device handle
[out]	p_time_capture	Pointer to a time capture structure to fill up with the time capture

rtc_instance_t

struct rtc_instance_t

This structure encompasses everything that is needed to use an instance of this interface.

Data Fields
rtc_ctrl_t *	p_ctrl	Pointer to the control structure for this instance.
rtc_cfg_t const *	p_cfg	Pointer to the configuration structure for this instance.
rtc_api_t const *	p_api	Pointer to the API structure for this instance.

Typedef Documentation

rtc_time_t

typedef struct tm rtc_time_t

Date and time structure defined in C standard library <time.h>

rtc_ctrl_t

typedef void rtc_ctrl_t

RTC control block. Allocate an instance specific control block to pass into the RTC API calls.

Enumeration Type Documentation

rtc_event_t

enum rtc_event_t

Events that can trigger a callback function

Enumerator
RTC_EVENT_ALARM_IRQ	Real Time Clock ALARM 0 IRQ.
RTC_EVENT_ALARM1_IRQ	Real Time Clock ALARM 1 IRQ.
RTC_EVENT_PERIODIC_IRQ	Real Time Clock PERIODIC IRQ.

rtc_alarm_channel_t

enum rtc_alarm_channel_t

RTC alarm channel

rtc_clock_source_t

enum rtc_clock_source_t

Clock source for the RTC block

Enumerator
RTC_CLOCK_SOURCE_SUBCLK	Sub-clock oscillator.
RTC_CLOCK_SOURCE_LOCO	Low power On Chip Oscillator.
RTC_CLOCK_SOURCE_MAINCLK	Main clock oscillator.

rtc_status_t

enum rtc_status_t

RTC run state

Enumerator
RTC_STATUS_STOPPED	RTC counter is stopped.
RTC_STATUS_RUNNING	RTC counter is running.

rtc_error_adjustment_t

enum rtc_error_adjustment_t

Time error adjustment settings

Enumerator
RTC_ERROR_ADJUSTMENT_NONE	Adjustment is not performed.
RTC_ERROR_ADJUSTMENT_ADD_PRESCALER	Adjustment is performed by the addition to the prescaler.
RTC_ERROR_ADJUSTMENT_SUBTRACT_PRESCALER	Adjustment is performed by the subtraction from the prescaler.

rtc_error_adjustment_mode_t

enum rtc_error_adjustment_mode_t

Time error adjustment mode settings

Enumerator
RTC_ERROR_ADJUSTMENT_MODE_MANUAL	Adjustment mode is set to manual.
RTC_ERROR_ADJUSTMENT_MODE_AUTOMATIC	Adjustment mode is set to automatic.

rtc_error_adjustment_period_t

enum rtc_error_adjustment_period_t

Time error adjustment period settings

Enumerator
RTC_ERROR_ADJUSTMENT_PERIOD_1_MINUTE	Adjustment period is set to every one minute.
RTC_ERROR_ADJUSTMENT_PERIOD_10_SECOND	Adjustment period is set to every ten second.
RTC_ERROR_ADJUSTMENT_PERIOD_NONE	Adjustment period not supported in manual mode.
RTC_ERROR_ADJUSTMENT_PERIOD_20_SECOND	Adjustment period is set to every twenty seconds.

rtc_periodic_irq_select_t

enum rtc_periodic_irq_select_t

Periodic Interrupt select

Enumerator
RTC_PERIODIC_IRQ_SELECT_1_DIV_BY_256_SECOND	A periodic irq is generated every 1/256 second.
RTC_PERIODIC_IRQ_SELECT_1_DIV_BY_128_SECOND	A periodic irq is generated every 1/128 second.
RTC_PERIODIC_IRQ_SELECT_1_DIV_BY_64_SECOND	A periodic irq is generated every 1/64 second.
RTC_PERIODIC_IRQ_SELECT_1_DIV_BY_32_SECOND	A periodic irq is generated every 1/32 second.
RTC_PERIODIC_IRQ_SELECT_1_DIV_BY_16_SECOND	A periodic irq is generated every 1/16 second.
RTC_PERIODIC_IRQ_SELECT_1_DIV_BY_8_SECOND	A periodic irq is generated every 1/8 second.
RTC_PERIODIC_IRQ_SELECT_1_DIV_BY_4_SECOND	A periodic irq is generated every 1/4 second.
RTC_PERIODIC_IRQ_SELECT_1_DIV_BY_2_SECOND	A periodic irq is generated every 1/2 second.
RTC_PERIODIC_IRQ_SELECT_1_SECOND	A periodic irq is generated every 1 second.
RTC_PERIODIC_IRQ_SELECT_2_SECOND	A periodic irq is generated every 2 seconds.
RTC_PERIODIC_IRQ_SELECT_1_MINUTE	A periodic irq is generated every 1 minute.
RTC_PERIODIC_IRQ_SELECT_1_HOUR	A periodic irq is generated every 1 hour.
RTC_PERIODIC_IRQ_SELECT_1_DAY	A periodic irq is generated every 1 day.
RTC_PERIODIC_IRQ_SELECT_1_MONTH	A periodic irq is generated every 1 month.

rtc_time_capture_source_t

enum rtc_time_capture_source_t

Time capture trigger source

Enumerator
RTC_TIME_CAPTURE_SOURCE_DISABLED	Disable trigger.
RTC_TIME_CAPTURE_SOURCE_PIN_RISING	Rising edge pin trigger.
RTC_TIME_CAPTURE_SOURCE_PIN_FALLING	Falling edge pin trigger.
RTC_TIME_CAPTURE_SOURCE_PIN_BOTH	Both edges pin trigger.
RTC_TIME_CAPTURE_SOURCE_SOFTWARE	Software trigger.
RTC_TIME_CAPTURE_SOURCE_ELC_EVENT	ELC event trigger.

rtc_time_capture_mode_t

enum rtc_time_capture_mode_t

Time capture trigger mode

Enumerator
RTC_TIME_CAPTURE_MODE_CONTINUOUS	Continuous capturing to all capturing channels.
RTC_TIME_CAPTURE_MODE_ONE_SHOT	Single capture to a particular channel.

rtc_time_capture_noise_filter_t

enum rtc_time_capture_noise_filter_t

Time capture noise filter control

Enumerator
RTC_TIME_CAPTURE_NOISE_FILTER_OFF	Turn noise filter off.
RTC_TIME_CAPTURE_NOISE_FILTER_ON	Turn noise filter on (count source)
RTC_TIME_CAPTURE_NOISE_FILTER_ON_DIVIDER_32	Turn noise filter on (count source by divided by 32)
RTC_TIME_CAPTURE_NOISE_FILTER_ON_DIVIDER_4096	Turn noise filter on (count source by divided by 4096)
RTC_TIME_CAPTURE_NOISE_FILTER_ON_DIVIDER_8192	Turn noise filter on (count source by divided by 8192)