This driver for Atmel® | SMART ARM®-based microcontrollers provides an interface for the configuration and management of the device's Real Time Clock functionality in Calendar operating mode, for the configuration and retrieval of the current time and date as maintained by the RTC module.

The following driver API modes are covered by this manual:

Polled APIs
Callback APIs

The following peripheral is used by this module:

RTC (Real Time Clock)

The following devices can use this module:

Atmel | SMART SAM D20/D21
Atmel | SMART SAM R21
Atmel | SMART SAM D09/D10/D11
Atmel | SMART SAM L21/L22
Atmel | SMART SAM DA1
Atmel | SMART SAM C20/C21
Atmel | SMART SAM HA1
Atmel | SMART SAM R30
Atmel | SMART SAM R34
Atmel | SMART SAM R35

The outline of this documentation is as follows:

Prerequisites

There are no prerequisites for this module.

Module Overview

The RTC module in the SAM devices is a 32-bit counter, with a 10-bit programmable prescaler. Typically, the RTC clock is run continuously, including in the device's low-power sleep modes, to track the current time and date information. The RTC can be used as a source to wake up the system at a scheduled time or periodically using the alarm functions.

In this driver, the RTC is operated in Calendar mode. This allows for an easy integration of a real time clock and calendar into a user application to track the passing of time and/or perform scheduled tasks.

Whilst operating in Calendar mode, the RTC features:

Time tracking in seconds, minutes, and hours
12 or 24 hour mode
Date tracking in day, month, and year
Automatic leap year correction

Driver Feature Macro Definition

Driver Feature Macro	Supported devices
FEATURE_RTC_PERIODIC_INT	SAM L21/L22/C20/C21/R30
FEATURE_RTC_PRESCALER_OFF	SAM L21/L22/C20/C21/R30
FEATURE_RTC_CLOCK_SELECTION	SAM L21/L22/C20/C21/R30
FEATURE_RTC_GENERAL_PURPOSE_REG	SAM L21/L22/R30
FEATURE_RTC_CONTINUOUSLY_UPDATED	SAM D20, SAM D21, SAM R21, SAM D10, SAM D11, SAM DA1, SAM HA1
FEATURE_RTC_TAMPER_DETECTION	SAM L22

Note: The specific features are only available in the driver when the selected device supports those features.

Alarms and Overflow

The RTC has up to four independent hardware alarms that can be configured by the user application. These alarms will be triggered on match with the current clock value, and can be set up to trigger an interrupt, event, or both. The RTC can also be configured to clear the clock value on alarm match, resetting the clock to the original start time.

If the RTC is operated in clock-only mode (i.e. with calendar disabled), the RTC counter value will instead be cleared on overflow once the maximum count value has been reached:

\[ COUNT_{MAX} = 2^{32}-1 \]

When the RTC is operated with the calendar enabled and run using a nominal 1Hz input clock frequency, a register overflow will occur after 64 years.

Periodic Events

The RTC can generate events at periodic intervals, allowing for direct peripheral actions without CPU intervention. The periodic events can be generated on the upper eight bits of the RTC prescaler, and will be generated on the rising edge transition of the specified bit. The resulting periodic frequency can be calculated by the following formula:

\[ f_{PERIODIC}=\frac{f_{ASY}}{2^{n+3}} \]

Where \(f_{ASY}\) refers to the asynchronous clock set up in the RTC module configuration. For the RTC to operate correctly in calendar mode, this frequency must be 1KHz, while the RTC's internal prescaler should be set to divide by 1024. The n parameter is the event source generator index of the RTC module. If the asynchronous clock is operated at the recommended 1KHz, the formula results in the values shown in the table below.

RTC Event Frequencies for Each Prescaler Bit Using a 1KHz Clock
n	Periodic event
7	1Hz
6	2Hz
5	4Hz
4	8Hz
3	16Hz
2	32Hz
1	64Hz
0	128Hz

Note: The connection of events between modules requires the use of the SAM Event System Driver (EVENTS) to route output event of one module to the input event of another. For more information on event routing, refer to the event driver documentation.

Digital Frequency Correction

The RTC module contains Digital Frequency Correction logic to compensate for inaccurate source clock frequencies which would otherwise result in skewed time measurements. The correction scheme requires that at least two bits in the RTC module prescaler are reserved by the correction logic. As a result of this implementation, frequency correction is only available when the RTC is running from a 1Hz reference clock.

The correction procedure is implemented by subtracting or adding a single cycle from the RTC prescaler every 1024 RTC Generic Clock (GCLK) cycles. The adjustment is applied the specified number of time (maximum 127) over 976 of these periods. The corresponding correction in parts per million (PPM) will be given by:

\[ Correction(PPM) = \frac{VALUE}{999424}10^6 \]

The RTC clock will tick faster if provided with a positive correction value, and slower when given a negative correction value.

RTC Tamper Detect

See RTC Tamper Detect.

Special Considerations

Year Limit

The RTC module has a year range of 63 years from the starting year configured when the module is initialized. Dates outside the start to end year range described below will need software adjustment:

\[ [YEAR_{START}, YEAR_{START}+64] \]

Clock Setup

SAM D20/D21/R21/D10/D11/DA1/HA1 Clock Setup.

The RTC is typically clocked by a specialized GCLK generator that has a smaller prescaler than the others. By default the RTC clock is on, selected to use the internal 32KHz Resistor/Capacitor (RC)-oscillator with a prescaler of 32, giving a resulting clock frequency of 1024Hz to the RTC. When the internal RTC prescaler is set to 1024, this yields an end-frequency of 1Hz for correct time keeping operations.

The implementer also has the option to set other end-frequencies. The table below lists the available RTC frequencies for each possible GCLK and RTC input prescaler options.

RTC Output Frequencies from Allowable Input Clocks
End-frequency	GCLK prescaler	RTC prescaler
32KHz	1	1
1KHz	32	1
1Hz	32	1024

The overall RTC module clocking scheme is shown in the figure below.

Note: For the calendar to operate correctly, an asynchronous clock of 1Hz should be used.

SAM L21/C20/C21/R30 Clock Setup

The RTC clock can be selected from OSC32K, XOSC32K, or OSCULP32K. A 32KHz or 1KHz oscillator clock frequency is required. This clock must be configured and enabled in the 32KHz oscillator controller before using the RTC.

asfdoc_sam0_rtc_calendar_rtc_clk lists the available RTC clock.

RTC Clocks Source
RTC clock frequency	Clock source	Description
1.024kHz	ULP1K	1.024kHz from 32KHz internal ULP oscillator
32.768kHz	ULP32K	32.768kHz from 32KHz internal ULP oscillator
1.024kHz	OSC1K	1.024kHz from 32KHz internal oscillator
32.768kHz	OSC32K	32.768kHz from 3KkHz internal oscillator
1.024kHz	XOSC1K	1.024kHz from 32KHz internal oscillator
32.768kHz	XOSC32K	32.768kHz from 32KHz external crystal oscillator

Note: For the calendar to operate correctly, an asynchronous clock of 1Hz should be used.

Extra Information

For extra information, see Extra Information for RTC (CAL) Driver. This includes:

Examples

For a list of examples related to this driver, see Examples for RTC CAL Driver.

API Overview

RTC Tamper Detect

The RTC provides several selectable polarity external inputs (INn) that can be used for tamper detection. When detect, tamper inputs support the four actions:

Off
Wake
Capture
Active layer protection

Note: The Active Layer Protection is a means of detecting broken traces on the PCB provided by RTC. In this mode an RTC output signal is routed over critical components on the board and fed back to one of the RTC inputs. The input and output signals are compared and a tamper condition is detected when they do not match.

Separate debouncers are embedded for each external input. The detection time depends on whether the debouncer operates synchronously or asynchronously, and whether majority detection is enabled or not. For details, refer to the section "Tamper Detection" of datasheet.

Data Structures
struct	rtc_calendar_alarm_time
	Alarm structure. More...

struct	rtc_calendar_config
	RTC configuration structure. More...

struct	rtc_calendar_events
	RTC Calendar event enable/disable structure. More...

struct	rtc_calendar_time
	Time structure. More...

struct	rtc_tamper_config
	RTC Tamper configuration structure. More...

struct	rtc_tamper_input_config
	RTC tamper input configuration structure. More...

Macros
#define	RTC_TAMPER_DETECT_EVT (1UL << 5)
	RTC tamper input event detection bitmask. More...

#define	RTC_TAMPER_DETECT_ID0 (1UL << 0)
	RTC tamper ID0 detection bitmask. More...

#define	RTC_TAMPER_DETECT_ID1 (1UL << 1)
	RTC tamper ID1 detection bitmask. More...

#define	RTC_TAMPER_DETECT_ID2 (1UL << 2)
	RTC tamper ID2 detection bitmask. More...

#define	RTC_TAMPER_DETECT_ID3 (1UL << 3)
	RTC tamper ID3 detection bitmask. More...

#define	RTC_TAMPER_DETECT_ID4 (1UL << 4)
	RTC tamper ID4 detection bitmask. More...

Enumerations
enum	rtc_calendar_alarm { RTC_CALENDAR_ALARM_0 = 0, RTC_CALENDAR_ALARM_1 = 1, RTC_CALENDAR_ALARM_2 = 2, RTC_CALENDAR_ALARM_3 = 3 }
	Available alarm channels. More...

enum	rtc_calendar_alarm_mask { RTC_CALENDAR_ALARM_MASK_DISABLED = RTC_MODE2_MASK_SEL_OFF, RTC_CALENDAR_ALARM_MASK_SEC = RTC_MODE2_MASK_SEL_SS, RTC_CALENDAR_ALARM_MASK_MIN = RTC_MODE2_MASK_SEL_MMSS, RTC_CALENDAR_ALARM_MASK_HOUR = RTC_MODE2_MASK_SEL_HHMMSS, RTC_CALENDAR_ALARM_MASK_DAY = RTC_MODE2_MASK_SEL_DDHHMMSS, RTC_CALENDAR_ALARM_MASK_MONTH = RTC_MODE2_MASK_SEL_MMDDHHMMSS, RTC_CALENDAR_ALARM_MASK_YEAR = RTC_MODE2_MASK_SEL_YYMMDDHHMMSS }
	Available mask options for alarms. More...

enum	rtc_calendar_callback { RTC_CALENDAR_CALLBACK_ALARM_0 = 0, RTC_CALENDAR_CALLBACK_ALARM_1, RTC_CALENDAR_CALLBACK_ALARM_2, RTC_CALENDAR_CALLBACK_ALARM_3, RTC_CALENDAR_CALLBACK_OVERFLOW }
	Callback types. More...

enum	rtc_calendar_prescaler { RTC_CALENDAR_PRESCALER_DIV_1 = RTC_MODE2_CTRL_PRESCALER_DIV1, RTC_CALENDAR_PRESCALER_DIV_2 = RTC_MODE2_CTRL_PRESCALER_DIV2, RTC_CALENDAR_PRESCALER_DIV_4 = RTC_MODE2_CTRL_PRESCALER_DIV4, RTC_CALENDAR_PRESCALER_DIV_8 = RTC_MODE2_CTRL_PRESCALER_DIV8, RTC_CALENDAR_PRESCALER_DIV_16 = RTC_MODE2_CTRL_PRESCALER_DIV16, RTC_CALENDAR_PRESCALER_DIV_32 = RTC_MODE2_CTRL_PRESCALER_DIV32, RTC_CALENDAR_PRESCALER_DIV_64 = RTC_MODE2_CTRL_PRESCALER_DIV64, RTC_CALENDAR_PRESCALER_DIV_128 = RTC_MODE2_CTRL_PRESCALER_DIV128, RTC_CALENDAR_PRESCALER_DIV_256 = RTC_MODE2_CTRL_PRESCALER_DIV256, RTC_CALENDAR_PRESCALER_DIV_512 = RTC_MODE2_CTRL_PRESCALER_DIV512, RTC_CALENDAR_PRESCALER_DIV_1024 = RTC_MODE2_CTRL_PRESCALER_DIV1024 }
	RTC input clock prescaler settings. More...

enum	rtc_tamper_active_layer_freq_divider { RTC_TAMPER_ACTIVE_LAYER_FREQ_DIV_2 = RTC_MODE0_CTRLB_ACTF_DIV2, RTC_TAMPER_ACTIVE_LAYER_FREQ_DIV_4 = RTC_MODE0_CTRLB_ACTF_DIV4, RTC_TAMPER_ACTIVE_LAYER_FREQ_DIV_8 = RTC_MODE0_CTRLB_ACTF_DIV8, RTC_TAMPER_ACTIVE_LAYER_FREQ_DIV_16 = RTC_MODE0_CTRLB_ACTF_DIV16, RTC_TAMPER_ACTIVE_LAYER_FREQ_DIV_32 = RTC_MODE0_CTRLB_ACTF_DIV32, RTC_TAMPER_ACTIVE_LAYER_FREQ_DIV_64 = RTC_MODE0_CTRLB_ACTF_DIV64, RTC_TAMPER_ACTIVE_LAYER_FREQ_DIV_128 = RTC_MODE0_CTRLB_ACTF_DIV128, RTC_TAMPER_ACTIVE_LAYER_FREQ_DIV_256 = RTC_MODE0_CTRLB_ACTF_DIV256 }
	RTC tamper active layer frequency divider. More...

enum	rtc_tamper_debounce_freq_divider { RTC_TAMPER_DEBOUNCE_FREQ_DIV_2 = RTC_MODE0_CTRLB_DEBF_DIV2, RTC_TAMPER_DEBOUNCE_FREQ_DIV_4 = RTC_MODE0_CTRLB_DEBF_DIV4, RTC_TAMPER_DEBOUNCE_FREQ_DIV_8 = RTC_MODE0_CTRLB_DEBF_DIV8, RTC_TAMPER_DEBOUNCE_FREQ_DIV_16 = RTC_MODE0_CTRLB_DEBF_DIV16, RTC_TAMPER_DEBOUNCE_FREQ_DIV_32 = RTC_MODE0_CTRLB_DEBF_DIV32, RTC_TAMPER_DEBOUNCE_FREQ_DIV_64 = RTC_MODE0_CTRLB_DEBF_DIV64, RTC_TAMPER_DEBOUNCE_FREQ_DIV_128 = RTC_MODE0_CTRLB_DEBF_DIV128, RTC_TAMPER_DEBOUNCE_FREQ_DIV_256 = RTC_MODE0_CTRLB_DEBF_DIV256 }
	RTC tamper debounce frequency divider. More...

enum	rtc_tamper_debounce_seq { RTC_TAMPER_DEBOUNCE_SYNC, RTC_TAMPER_DEBOUNCE_ASYNC, RTC_TAMPER_DEBOUNCE_MAJORITY }
	RTC tamper debounce sequential. More...

enum	rtc_tamper_input_action { RTC_TAMPER_INPUT_ACTION_OFF = RTC_TAMPCTRL_IN0ACT_OFF, RTC_TAMPER_INPUT_ACTION_WAKE = RTC_TAMPCTRL_IN0ACT_WAKE, RTC_TAMPER_INPUT_ACTION_CAPTURE = RTC_TAMPCTRL_IN0ACT_CAPTURE, RTC_TAMPER_INPUT_ACTION_ACTL = RTC_TAMPCTRL_IN0ACT_ACTL }
	RTC tamper input action. More...

enum	rtc_tamper_level_sel { RTC_TAMPER_LEVEL_FALLING = (0), RTC_TAMPER_LEVEL_RISING = (1) }
	RTC tamper input level select. More...

#define	FEATURE_RTC_CONTINUOUSLY_UPDATED
	Define port features set according to different device family. More...

Configuration and Initialization
static void	rtc_calendar_get_time_defaults (struct rtc_calendar_time *const time)
	Initialize a `time` structure. More...

static void	rtc_calendar_get_config_defaults (struct rtc_calendar_config *const config)
	Gets the RTC default settings. More...

void	rtc_calendar_reset (struct rtc_module *const module)
	Resets the RTC module. More...

void	rtc_calendar_enable (struct rtc_module *const module)
	Enables the RTC module. More...

void	rtc_calendar_disable (struct rtc_module *const module)
	Disables the RTC module. More...

void	rtc_calendar_init (struct rtc_module const module, Rtc const hw, const struct rtc_calendar_config *const config)
	Initializes the RTC module with given configurations. More...

void	rtc_calendar_swap_time_mode (struct rtc_module *const module)
	Swaps between 12h and 24h clock mode. More...

enum status_code	rtc_calendar_frequency_correction (struct rtc_module *const module, const int8_t value)
	Calibrate for too-slow or too-fast oscillator. More...

Time and Alarm Management
uint32_t	rtc_calendar_time_to_register_value (struct rtc_module const module, const struct rtc_calendar_time const time)
	Convert time structure to register_value. More...

void	rtc_calendar_register_value_to_time (struct rtc_module const module, const uint32_t register_value, struct rtc_calendar_time const time)
	Convert register_value to time structure. More...

void	rtc_calendar_set_time (struct rtc_module const module, const struct rtc_calendar_time const time)
	Set the current calendar time to desired time. More...

void	rtc_calendar_get_time (struct rtc_module const module, struct rtc_calendar_time const time)
	Get the current calendar value. More...

enum status_code	rtc_calendar_set_alarm (struct rtc_module const module, const struct rtc_calendar_alarm_time const alarm, const enum rtc_calendar_alarm alarm_index)
	Set the alarm time for the specified alarm. More...

enum status_code	rtc_calendar_get_alarm (struct rtc_module const module, struct rtc_calendar_alarm_time const alarm, const enum rtc_calendar_alarm alarm_index)
	Get the current alarm time of specified alarm. More...

Status Flag Management
static bool	rtc_calendar_is_overflow (struct rtc_module *const module)
	Check if an RTC overflow has occurred. More...

static void	rtc_calendar_clear_overflow (struct rtc_module *const module)
	Clears the RTC overflow flag. More...

static bool	rtc_calendar_is_alarm_match (struct rtc_module *const module, const enum rtc_calendar_alarm alarm_index)
	Check the RTC alarm flag. More...

static enum status_code	rtc_calendar_clear_alarm_match (struct rtc_module *const module, const enum rtc_calendar_alarm alarm_index)
	Clears the RTC alarm match flag. More...

Event Management
static void	rtc_calendar_enable_events (struct rtc_module const module, struct rtc_calendar_events const events)
	Enables an RTC event output. More...

static void	rtc_calendar_disable_events (struct rtc_module const module, struct rtc_calendar_events const events)
	Disables an RTC event output. More...

Callbacks
enum status_code	rtc_calendar_register_callback (struct rtc_module *const module, rtc_calendar_callback_t callback, enum rtc_calendar_callback callback_type)
	Registers callback for the specified callback type. More...

enum status_code	rtc_calendar_unregister_callback (struct rtc_module *const module, enum rtc_calendar_callback callback_type)
	Unregisters callback for the specified callback type. More...

void	rtc_calendar_enable_callback (struct rtc_module *const module, enum rtc_calendar_callback callback_type)
	Enables callback. More...

void	rtc_calendar_disable_callback (struct rtc_module *const module, enum rtc_calendar_callback callback_type)
	Disables callback. More...

RTC Tamper Detection
static void	rtc_tamper_get_config_defaults (struct rtc_tamper_config *const config)
	Gets the RTC tamper default configurations. More...

enum status_code	rtc_tamper_set_config (struct rtc_module const module, struct rtc_tamper_config const tamper_cfg)

static uint32_t	rtc_tamper_get_detect_flag (struct rtc_module *const module)
	Retrieves the RTC tamper detection status. More...

static void	rtc_tamper_clear_detect_flag (struct rtc_module *const module, const uint32_t detect_flags)
	Clears RTC tamper detection flag. More...

#define FEATURE_RTC_CONTINUOUSLY_UPDATED

Define port features set according to different device family.

RTC continuously updated.

#define RTC_TAMPER_DETECT_EVT (1UL << 5)

RTC tamper input event detection bitmask.

Referenced by rtc_tamper_clear_detect_flag(), and rtc_tamper_get_detect_flag().

#define RTC_TAMPER_DETECT_ID0 (1UL << 0)

RTC tamper ID0 detection bitmask.

Referenced by rtc_tamper_clear_detect_flag(), and rtc_tamper_get_detect_flag().

#define RTC_TAMPER_DETECT_ID1 (1UL << 1)

RTC tamper ID1 detection bitmask.

Referenced by rtc_tamper_clear_detect_flag(), and rtc_tamper_get_detect_flag().

#define RTC_TAMPER_DETECT_ID2 (1UL << 2)

RTC tamper ID2 detection bitmask.

Referenced by rtc_tamper_clear_detect_flag(), and rtc_tamper_get_detect_flag().

#define RTC_TAMPER_DETECT_ID3 (1UL << 3)

RTC tamper ID3 detection bitmask.

Referenced by rtc_tamper_clear_detect_flag(), and rtc_tamper_get_detect_flag().

#define RTC_TAMPER_DETECT_ID4 (1UL << 4)

RTC tamper ID4 detection bitmask.

Referenced by rtc_tamper_clear_detect_flag(), and rtc_tamper_get_detect_flag().

enum rtc_calendar_alarm

Available alarm channels.

Note: Not all alarm channels are available on all devices.

Enumerator
RTC_CALENDAR_ALARM_0	Alarm channel 0.
RTC_CALENDAR_ALARM_1	Alarm channel 1.
RTC_CALENDAR_ALARM_2	Alarm channel 2.
RTC_CALENDAR_ALARM_3	Alarm channel 3.

enum rtc_calendar_alarm_mask

Available mask options for alarms.

Enumerator
RTC_CALENDAR_ALARM_MASK_DISABLED	Alarm disabled.
RTC_CALENDAR_ALARM_MASK_SEC	Alarm match on second.
RTC_CALENDAR_ALARM_MASK_MIN	Alarm match on second and minute.
RTC_CALENDAR_ALARM_MASK_HOUR	Alarm match on second, minute, and hour.
RTC_CALENDAR_ALARM_MASK_DAY	Alarm match on second, minute, hour, and day.
RTC_CALENDAR_ALARM_MASK_MONTH	Alarm match on second, minute, hour, day, and month.
RTC_CALENDAR_ALARM_MASK_YEAR	Alarm match on second, minute, hour, day, month, and year.

enum rtc_calendar_callback

Callback types.

The available callback types for the RTC calendar module.

Enumerator
RTC_CALENDAR_CALLBACK_ALARM_0	Callback for alarm 0.
RTC_CALENDAR_CALLBACK_ALARM_1	Callback for alarm 1.
RTC_CALENDAR_CALLBACK_ALARM_2	Callback for alarm 2.
RTC_CALENDAR_CALLBACK_ALARM_3	Callback for alarm 3.
RTC_CALENDAR_CALLBACK_OVERFLOW	Callback for overflow.

enum rtc_calendar_prescaler

RTC input clock prescaler settings.

The available input clock prescaler values for the RTC calendar module.

Enumerator
RTC_CALENDAR_PRESCALER_DIV_1	RTC input clock frequency is prescaled by a factor of 1.
RTC_CALENDAR_PRESCALER_DIV_2	RTC input clock frequency is prescaled by a factor of 2.
RTC_CALENDAR_PRESCALER_DIV_4	RTC input clock frequency is prescaled by a factor of 4.
RTC_CALENDAR_PRESCALER_DIV_8	RTC input clock frequency is prescaled by a factor of 8.
RTC_CALENDAR_PRESCALER_DIV_16	RTC input clock frequency is prescaled by a factor of 16.
RTC_CALENDAR_PRESCALER_DIV_32	RTC input clock frequency is prescaled by a factor of 32.
RTC_CALENDAR_PRESCALER_DIV_64	RTC input clock frequency is prescaled by a factor of 64.
RTC_CALENDAR_PRESCALER_DIV_128	RTC input clock frequency is prescaled by a factor of 128.
RTC_CALENDAR_PRESCALER_DIV_256	RTC input clock frequency is prescaled by a factor of 256.
RTC_CALENDAR_PRESCALER_DIV_512	RTC input clock frequency is prescaled by a factor of 512.
RTC_CALENDAR_PRESCALER_DIV_1024	RTC input clock frequency is prescaled by a factor of 1024.

enum rtc_tamper_active_layer_freq_divider

RTC tamper active layer frequency divider.

The available prescaler factor for the RTC clock output used during active layer protection.

Enumerator
RTC_TAMPER_ACTIVE_LAYER_FREQ_DIV_2	RTC active layer frequency is prescaled by a factor of 2.
RTC_TAMPER_ACTIVE_LAYER_FREQ_DIV_4	RTC active layer frequency is prescaled by a factor of 4.
RTC_TAMPER_ACTIVE_LAYER_FREQ_DIV_8	RTC active layer frequency is prescaled by a factor of 8.
RTC_TAMPER_ACTIVE_LAYER_FREQ_DIV_16	RTC active layer frequency is prescaled by a factor of 16.
RTC_TAMPER_ACTIVE_LAYER_FREQ_DIV_32	RTC active layer frequency is prescaled by a factor of 32.
RTC_TAMPER_ACTIVE_LAYER_FREQ_DIV_64	RTC active layer frequency is prescaled by a factor of 64.
RTC_TAMPER_ACTIVE_LAYER_FREQ_DIV_128	RTC active layer frequency is prescaled by a factor of 128.
RTC_TAMPER_ACTIVE_LAYER_FREQ_DIV_256	RTC active layer frequency is prescaled by a factor of 256.

enum rtc_tamper_debounce_freq_divider

RTC tamper debounce frequency divider.

The available prescaler factor for the input debouncers.

Enumerator
RTC_TAMPER_DEBOUNCE_FREQ_DIV_2	RTC debounce frequency is prescaled by a factor of 2.
RTC_TAMPER_DEBOUNCE_FREQ_DIV_4	RTC debounce frequency is prescaled by a factor of 4.
RTC_TAMPER_DEBOUNCE_FREQ_DIV_8	RTC debounce frequency is prescaled by a factor of 8.
RTC_TAMPER_DEBOUNCE_FREQ_DIV_16	RTC debounce frequency is prescaled by a factor of 16.
RTC_TAMPER_DEBOUNCE_FREQ_DIV_32	RTC debounce frequency is prescaled by a factor of 32.
RTC_TAMPER_DEBOUNCE_FREQ_DIV_64	RTC debounce frequency is prescaled by a factor of 64.
RTC_TAMPER_DEBOUNCE_FREQ_DIV_128	RTC debounce frequency is prescaled by a factor of 128.
RTC_TAMPER_DEBOUNCE_FREQ_DIV_256	RTC debounce frequency is prescaled by a factor of 256.

enum rtc_tamper_debounce_seq

RTC tamper debounce sequential.

The available sequential for tamper debounce.

Enumerator
RTC_TAMPER_DEBOUNCE_SYNC	Tamper input detect edge with synchronous stability debounce.
RTC_TAMPER_DEBOUNCE_ASYNC	Tamper input detect edge with asynchronous stability debounce.
RTC_TAMPER_DEBOUNCE_MAJORITY	Tamper input detect edge with majority debounce.

enum rtc_tamper_input_action

RTC tamper input action.

The available action taken by the tamper input.

Enumerator
RTC_TAMPER_INPUT_ACTION_OFF	RTC tamper input action is disabled.
RTC_TAMPER_INPUT_ACTION_WAKE	RTC tamper input action is wake and set tamper flag.
RTC_TAMPER_INPUT_ACTION_CAPTURE	RTC tamper input action is capture timestamp and set tamper flag.
RTC_TAMPER_INPUT_ACTION_ACTL	RTC tamper input action is compare IN to OUT, when a mismatch occurs, capture timestamp and set tamper flag.

enum rtc_tamper_level_sel

RTC tamper input level select.

The available edge condition for tamper INn level select.

Enumerator
RTC_TAMPER_LEVEL_FALLING	A falling edge condition will be detected on Tamper input.
RTC_TAMPER_LEVEL_RISING	A rising edge condition will be detected on Tamper input.

static enum status_code rtc_calendar_clear_alarm_match	(	struct rtc_module *const	module,
		const enum rtc_calendar_alarm	alarm_index
	)

inlinestatic

Clears the RTC alarm match flag.

Clear the requested alarm match flag, so that future alarm matches can be determined.

Parameters

[in,out]	module	Pointer to the software instance struct
[in]	alarm_index	The index of the alarm match to clear

Returns: Status of the alarm match clear operation.

Return values

STATUS_OK	If flag was cleared correctly
STATUS_ERR_INVALID_ARG	If invalid argument(s) were provided

References Assert, STATUS_ERR_INVALID_ARG, and STATUS_OK.

Referenced by run_rtc_calendar_interrupt_test(), and run_rtc_calendar_test().

static void rtc_calendar_clear_overflow ( struct rtc_module *const module )

inlinestatic

Clears the RTC overflow flag.

Parameters

[in,out] module Pointer to the software instance struct

Clears the RTC module counter overflow flag, so that new overflow conditions can be detected.

References Assert.

Referenced by run_rtc_calendar_test().

void rtc_calendar_disable ( struct rtc_module *const module )

Disables the RTC module.

Parameters

[in,out] module Pointer to the software instance struct

References Assert, rtc_calendar_is_syncing(), system_interrupt_disable(), and SYSTEM_INTERRUPT_MODULE_RTC.

Referenced by rtc_calendar_reset(), rtc_calendar_swap_time_mode(), run_rtc_calendar_interrupt_test(), and run_rtc_calendar_test().

void rtc_calendar_disable_callback	(	struct rtc_module *const	module,
		enum rtc_calendar_callback	callback_type
	)

Disables callback.

Disables the callback specified by the callback_type.

Parameters

[in,out]	module	Pointer to the software instance struct
[in]	callback_type	Callback type to disable

References Assert, and RTC_CALENDAR_CALLBACK_OVERFLOW.

Referenced by run_rtc_calendar_interrupt_test().

static void rtc_calendar_disable_events	(	struct rtc_module *const	module,
		struct rtc_calendar_events *const	events
	)

inlinestatic

Disables an RTC event output.

Disabled one or more output events from the RTC module. See rtc_calendar_events for a list of events this module supports.

Note: Events cannot be altered while the module is enabled.

Parameters

[in,out]	module	Pointer to the software instance struct
[in]	events	Struct containing flags of events to disable

References Assert, rtc_calendar_events::generate_event_on_alarm, rtc_calendar_events::generate_event_on_overflow, and rtc_calendar_events::generate_event_on_periodic.

void rtc_calendar_enable ( struct rtc_module *const module )

Enables the RTC module.

Enables the RTC module once it has been configured, ready for use. Most module configuration parameters cannot be altered while the module is enabled.

Parameters

[in,out] module Pointer to the software instance struct

References Assert, rtc_calendar_is_syncing(), system_interrupt_enable(), and SYSTEM_INTERRUPT_MODULE_RTC.

Referenced by rtc_calendar_swap_time_mode(), run_rtc_calendar_interrupt_test(), and run_rtc_calendar_test().

void rtc_calendar_enable_callback	(	struct rtc_module *const	module,
		enum rtc_calendar_callback	callback_type
	)

Enables callback.

Enables the callback specified by the callback_type.

Parameters

[in,out]	module	Pointer to the software instance struct
[in]	callback_type	Callback type to enable

References Assert, and RTC_CALENDAR_CALLBACK_OVERFLOW.

Referenced by run_rtc_calendar_interrupt_test().

static void rtc_calendar_enable_events	(	struct rtc_module *const	module,
		struct rtc_calendar_events *const	events
	)

inlinestatic

Enables an RTC event output.

Enables one or more output events from the RTC module. See rtc_calendar_events for a list of events this module supports.

Note: Events cannot be altered while the module is enabled.

Parameters

[in,out]	module	Pointer to the software instance struct
[in]	events	Struct containing flags of events to enable

References Assert, rtc_calendar_events::generate_event_on_alarm, rtc_calendar_events::generate_event_on_overflow, and rtc_calendar_events::generate_event_on_periodic.

enum status_code rtc_calendar_frequency_correction	(	struct rtc_module *const	module,
		const int8_t	value
	)

Calibrate for too-slow or too-fast oscillator.

When used, the RTC will compensate for an inaccurate oscillator. The RTC module will add or subtract cycles from the RTC prescaler to adjust the frequency in approximately 1 PPM steps. The provided correction value should be between 0 and 127, allowing for a maximum 127 PPM correction in either direction.

If no correction is needed, set value to zero.

Note: Can only be used when the RTC is operated at 1Hz.

Parameters

[in,out]	module	Pointer to the software instance struct
[in]	value	Between -127 and 127 used for the correction

Returns: Status of the calibration procedure.

Return values

STATUS_OK	If calibration was done correctly
STATUS_ERR_INVALID_ARG	If invalid argument(s) were provided

References Assert, rtc_calendar_is_syncing(), STATUS_ERR_INVALID_ARG, and STATUS_OK.

enum status_code rtc_calendar_get_alarm	(	struct rtc_module *const	module,
		struct rtc_calendar_alarm_time *const	alarm,
		const enum rtc_calendar_alarm	alarm_index
	)

Get the current alarm time of specified alarm.

Retrieves the current alarm time for the specified alarm.

Parameters

[in,out]	module	Pointer to the software instance struct
[out]	alarm	Pointer to the struct that will be filled with alarm time and mask of the specified alarm.
[in]	alarm_index	Index of alarm to get alarm time from

Returns: Status of getting alarm.

Return values

STATUS_OK	If alarm was read correctly
STATUS_ERR_INVALID_ARG	If invalid argument(s) were provided

References Assert, rtc_calendar_alarm_time::mask, rtc_calendar_register_value_to_time(), STATUS_ERR_INVALID_ARG, STATUS_OK, and rtc_calendar_alarm_time::time.

Referenced by rtc_calendar_swap_time_mode().

static void rtc_calendar_get_config_defaults ( struct rtc_calendar_config *const config )

inlinestatic

Gets the RTC default settings.

Initializes the configuration structure to the known default values. This function should be called at the start of any RTC initiation.

The default configuration is as follows:

Input clock divided by a factor of 1024
Clear on alarm match off
Continuously sync clock off
12 hour calendar
Start year 2000 (Year 0 in the counter will be year 2000)
Events off
Alarms set to January 1. 2000, 00:00:00
Alarm will match on second, minute, hour, day, month, and year
Clock read synchronization is enabled for SAM L22

Parameters

[out] config Configuration structure to be initialized to default values

References rtc_calendar_config::alarm, Assert, rtc_calendar_config::clear_on_match, rtc_calendar_config::clock_24h, rtc_calendar_config::continuously_update, rtc_calendar_config::enable_read_sync, rtc_calendar_alarm_time::mask, rtc_calendar_config::prescaler, RTC_CALENDAR_ALARM_MASK_YEAR, rtc_calendar_get_time_defaults(), RTC_CALENDAR_PRESCALER_DIV_1024, rtc_calendar_alarm_time::time, and rtc_calendar_config::year_init_value.

Referenced by run_rtc_calendar_test().

void rtc_calendar_get_time	(	struct rtc_module *const	module,
		struct rtc_calendar_time *const	time
	)

Get the current calendar value.

Retrieves the current time of the calendar.

Parameters

[in,out]	module	Pointer to the software instance struct
[out]	time	Pointer to value that will be filled with current time

References Assert, rtc_calendar_is_syncing(), and rtc_calendar_register_value_to_time().

Referenced by rtc_calendar_swap_time_mode().

static void rtc_calendar_get_time_defaults ( struct rtc_calendar_time *const time )

inlinestatic

Initialize a time structure.

This will initialize a given time structure to the time 00:00:00 (hh:mm:ss) and date 2000-01-01 (YYYY-MM-DD).

Parameters

[out] time Time structure to initialize

References rtc_calendar_time::day, rtc_calendar_time::hour, rtc_calendar_time::minute, rtc_calendar_time::month, rtc_calendar_time::pm, rtc_calendar_time::second, and rtc_calendar_time::year.

Referenced by rtc_calendar_get_config_defaults(), and run_rtc_calendar_test().

void rtc_calendar_init	(	struct rtc_module *const	module,
		Rtc *const	hw,
		const struct rtc_calendar_config *const	config
	)

Initializes the RTC module with given configurations.

Initializes the module, setting up all given configurations to provide the desired functionality of the RTC.

Parameters

[out]	module	Pointer to the software instance struct
[in]	hw	Pointer to hardware instance
[in]	config	Pointer to the configuration structure

References _rtc_calendar_set_config(), _rtc_instance, Assert, rtc_calendar_config::clock_24h, rtc_calendar_reset(), RTC_CLOCK_SOURCE, system_apb_clock_set_mask(), SYSTEM_CLOCK_APB_APBA, and rtc_calendar_config::year_init_value.

Referenced by run_rtc_calendar_test().

static bool rtc_calendar_is_alarm_match	(	struct rtc_module *const	module,
		const enum rtc_calendar_alarm	alarm_index
	)

inlinestatic

Check the RTC alarm flag.

Check if the specified alarm flag is set. The flag is set when there is a compare match between the alarm value and the clock.

Parameters

[in,out]	module	Pointer to the software instance struct
[in]	alarm_index	Index of the alarm to check

Returns: Match status of the specified alarm.

Return values

true	If the specified alarm has matched the current time
false	If the specified alarm has not matched the current time

References Assert.

Referenced by run_rtc_calendar_test().

static bool rtc_calendar_is_overflow ( struct rtc_module *const module )

inlinestatic

Check if an RTC overflow has occurred.

Checks the overflow flag in the RTC. The flag is set when there is an overflow in the clock.

Parameters

[in,out] module Pointer to the software instance struct

Returns: Overflow state of the RTC module.

Return values

true	If the RTC count value has overflowed
false	If the RTC count value has not overflowed

References Assert.

Referenced by run_rtc_calendar_test().

enum status_code rtc_calendar_register_callback	(	struct rtc_module *const	module,
		rtc_calendar_callback_t	callback,
		enum rtc_calendar_callback	callback_type
	)

Registers callback for the specified callback type.

Associates the given callback function with the specified callback type. To enable the callback, the rtc_calendar_enable_callback function must be used.

Parameters

[in,out]	module	Pointer to the software instance struct
[in]	callback	Pointer to the function desired for the specified callback
[in]	callback_type	Callback type to register

Returns: Status of registering callback.

Return values

STATUS_OK	Registering was done successfully
STATUS_ERR_INVALID_ARG	If trying to register, a callback is not available

References RTC_CALENDAR_CALLBACK_OVERFLOW, STATUS_ERR_INVALID_ARG, and STATUS_OK.

Referenced by run_rtc_calendar_interrupt_test().

void rtc_calendar_register_value_to_time	(	struct rtc_module *const	module,
		const uint32_t	register_value,
		struct rtc_calendar_time *const	time
	)

Convert register_value to time structure.

Retrieves the time structure convert by register_value.

Parameters

[in,out]	module	Pointer to the software instance struct
[in]	register_value	The value stored in register
[out]	time	Pointer to the time structure

References rtc_calendar_time::day, rtc_calendar_time::hour, rtc_calendar_time::minute, rtc_calendar_time::month, rtc_calendar_time::pm, rtc_calendar_time::second, and rtc_calendar_time::year.

Referenced by rtc_calendar_get_alarm(), and rtc_calendar_get_time().

void rtc_calendar_reset ( struct rtc_module *const module )

Resets the RTC module.

Resets the RTC module to hardware defaults.

Parameters

[in,out] module Pointer to the software instance struct

References Assert, rtc_calendar_disable(), and rtc_calendar_is_syncing().

Referenced by rtc_calendar_init().

enum status_code rtc_calendar_set_alarm	(	struct rtc_module *const	module,
		const struct rtc_calendar_alarm_time *const	alarm,
		const enum rtc_calendar_alarm	alarm_index
	)

Set the alarm time for the specified alarm.

Sets the time and mask specified to the requested alarm.

Parameters

[in,out]	module	Pointer to the software instance struct
[in]	alarm	The alarm struct to set the alarm with
[in]	alarm_index	The index of the alarm to set

Returns: Status of setting alarm.

Return values

STATUS_OK	If alarm was set correctly
STATUS_ERR_INVALID_ARG	If invalid argument(s) were provided

References Assert, rtc_calendar_alarm_time::mask, rtc_calendar_is_syncing(), rtc_calendar_time_to_register_value(), STATUS_ERR_INVALID_ARG, STATUS_OK, and rtc_calendar_alarm_time::time.

Referenced by _rtc_calendar_set_config(), rtc_calendar_swap_time_mode(), run_rtc_calendar_interrupt_test(), and run_rtc_calendar_test().

void rtc_calendar_set_time	(	struct rtc_module *const	module,
		const struct rtc_calendar_time *const	time
	)

Set the current calendar time to desired time.

Sets the time provided to the calendar.

Parameters

[in,out]	module	Pointer to the software instance struct
[in]	time	The time to set in the calendar

References Assert, rtc_calendar_is_syncing(), and rtc_calendar_time_to_register_value().

Referenced by rtc_calendar_swap_time_mode(), run_rtc_calendar_interrupt_test(), and run_rtc_calendar_test().

void rtc_calendar_swap_time_mode ( struct rtc_module *const module )

Swaps between 12h and 24h clock mode.

Swaps the current RTC time mode.

If currently in 12h mode, it will swap to 24h.
If currently in 24h mode, it will swap to 12h.

Note: This will not change setting in user's configuration structure.

Parameters

[in,out] module Pointer to the software instance struct

References Assert, rtc_calendar_time::hour, rtc_calendar_time::pm, rtc_calendar_disable(), rtc_calendar_enable(), rtc_calendar_get_alarm(), rtc_calendar_get_time(), rtc_calendar_set_alarm(), rtc_calendar_set_time(), and rtc_calendar_alarm_time::time.

uint32_t rtc_calendar_time_to_register_value	(	struct rtc_module *const	module,
		const struct rtc_calendar_time *const	time
	)

Convert time structure to register_value.

Retrieves register_value convert by the time structure.

Parameters

[in,out]	module	Pointer to the software instance struct
[in]	time	Pointer to the time structure

Returns: 32-bit value.

References rtc_calendar_time::day, rtc_calendar_time::hour, rtc_calendar_time::minute, rtc_calendar_time::month, rtc_calendar_time::pm, rtc_calendar_time::second, and rtc_calendar_time::year.

Referenced by rtc_calendar_set_alarm(), and rtc_calendar_set_time().

enum status_code rtc_calendar_unregister_callback	(	struct rtc_module *const	module,
		enum rtc_calendar_callback	callback_type
	)

Unregisters callback for the specified callback type.

When called, the currently registered callback for the given callback type will be removed.

Parameters

[in,out]	module	Pointer to the software instance struct
[in]	callback_type	Specifies the callback type to unregister

Returns: Status of unregistering callback.

Return values

STATUS_OK	Unregistering was done successfully
STATUS_ERR_INVALID_ARG	If trying to unregister, a callback is not available

References RTC_CALENDAR_CALLBACK_OVERFLOW, STATUS_ERR_INVALID_ARG, and STATUS_OK.

Referenced by run_rtc_calendar_interrupt_test().

static void rtc_tamper_clear_detect_flag	(	struct rtc_module *const	module,
		const uint32_t	detect_flags
	)

inlinestatic

Clears RTC tamper detection flag.

Clears the given detection flag of the module.

Parameters

[in]	module	Pointer to the TC software instance struct
[in]	detect_flags	Bitmask of detection flags

References Assert, RTC_TAMPER_DETECT_EVT, RTC_TAMPER_DETECT_ID0, RTC_TAMPER_DETECT_ID1, RTC_TAMPER_DETECT_ID2, RTC_TAMPER_DETECT_ID3, and RTC_TAMPER_DETECT_ID4.

static void rtc_tamper_get_config_defaults ( struct rtc_tamper_config *const config )

inlinestatic

Gets the RTC tamper default configurations.

Initializes the configuration structure to default values.

The default configuration is as follows:

Disable backup register reset on tamper
Disable GP register reset on tamper
Active layer clock divided by a factor of 8
Debounce clock divided by a factor of 8
Detect edge on INn with synchronous stability debouncing
Disable DMA on tamper
Enable GP register
Disable debouce, detect on falling edge and no action on INn

Parameters

[out] config Configuration structure to be initialized to default values.

References rtc_tamper_input_config::action, rtc_tamper_config::actl_freq_div, Assert, rtc_tamper_config::bkup_reset_on_tamper, rtc_tamper_config::deb_freq_div, rtc_tamper_config::deb_seq, rtc_tamper_input_config::debounce_enable, rtc_tamper_config::dma_tamper_enable, rtc_tamper_config::gp0_enable, rtc_tamper_config::gp_reset_on_tamper, rtc_tamper_config::in_cfg, rtc_tamper_input_config::level, RTC_TAMPER_ACTIVE_LAYER_FREQ_DIV_8, RTC_TAMPER_DEBOUNCE_FREQ_DIV_8, RTC_TAMPER_DEBOUNCE_SYNC, RTC_TAMPER_INPUT_ACTION_OFF, and RTC_TAMPER_LEVEL_FALLING.

static uint32_t rtc_tamper_get_detect_flag ( struct rtc_module *const module )

inlinestatic

Retrieves the RTC tamper detection status.

Retrieves the detection status of each input pin and the input event.

Parameters

[in] module Pointer to the RTC software instance struct

Returns: Bitmask of detection flags.

Return values

RTC_TAMPER_DETECT_ID0	Tamper condition on IN0 has been detected
RTC_TAMPER_DETECT_ID1	Tamper condition on IN1 has been detected
RTC_TAMPER_DETECT_ID2	Tamper condition on IN2 has been detected
RTC_TAMPER_DETECT_ID3	Tamper condition on IN3 has been detected
RTC_TAMPER_DETECT_ID4	Tamper condition on IN4 has been detected
RTC_TAMPER_DETECT_EVT	Tamper input event has been detected

References Assert, RTC_TAMPER_DETECT_EVT, RTC_TAMPER_DETECT_ID0, RTC_TAMPER_DETECT_ID1, RTC_TAMPER_DETECT_ID2, RTC_TAMPER_DETECT_ID3, and RTC_TAMPER_DETECT_ID4.

enum status_code rtc_tamper_set_config	(	struct rtc_module *const	module,
		struct rtc_tamper_config *const	tamper_cfg
	)

Microchip® Advanced Software Framework

Prerequisites

Module Overview

Driver Feature Macro Definition

Alarms and Overflow

Periodic Events

Digital Frequency Correction

RTC Tamper Detect

Special Considerations

Year Limit

Clock Setup

SAM D20/D21/R21/D10/D11/DA1/HA1 Clock Setup.

SAM L21/C20/C21/R30 Clock Setup

Extra Information

Examples

API Overview

RTC Tamper Detect

Data Structures

Macros

Enumerations

Configuration and Initialization

Time and Alarm Management

Status Flag Management

Event Management

Callbacks

RTC Tamper Detection