/** * \file * * \brief SAM RTC Driver (Calendar Mode) * * Copyright (C) 2012-2016 Atmel Corporation. All rights reserved. * * \asf_license_start * * \page License * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions are met: * * 1. Redistributions of source code must retain the above copyright notice, * this list of conditions and the following disclaimer. * * 2. Redistributions in binary form must reproduce the above copyright notice, * this list of conditions and the following disclaimer in the documentation * and/or other materials provided with the distribution. * * 3. The name of Atmel may not be used to endorse or promote products derived * from this software without specific prior written permission. * * 4. This software may only be redistributed and used in connection with an * Atmel microcontroller product. * * THIS SOFTWARE IS PROVIDED BY ATMEL "AS IS" AND ANY EXPRESS OR IMPLIED * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT ARE * EXPRESSLY AND SPECIFICALLY DISCLAIMED. IN NO EVENT SHALL ATMEL BE LIABLE FOR * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE * POSSIBILITY OF SUCH DAMAGE. * * \asf_license_stop * */ /* * Support and FAQ: visit Atmel Support */ #ifndef RTC_CALENDAR_H_INCLUDED #define RTC_CALENDAR_H_INCLUDED /** * \defgroup asfdoc_sam0_rtc_calendar_group SAM RTC Calendar (RTC CAL) Driver * * 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 * \if RTC_CALENDAR_CALLBACK_MODE * - Callback APIs * \endif * * 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 * * The outline of this documentation is as follows: * - \ref asfdoc_sam0_rtc_calendar_prerequisites * - \ref asfdoc_sam0_rtc_calendar_module_overview * - \ref asfdoc_sam0_rtc_calendar_special_considerations * - \ref asfdoc_sam0_rtc_calendar_extra_info * - \ref asfdoc_sam0_rtc_calendar_examples * - \ref asfdoc_sam0_rtc_calendar_api_overview * * * \section asfdoc_sam0_rtc_calendar_prerequisites Prerequisites * * There are no prerequisites for this module. * * * \section asfdoc_sam0_rtc_calendar_module_overview 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 * * \subsection asfdoc_sam0_rtc_calendar_features Driver Feature Macro Definition * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
Driver Feature MacroSupported devices
FEATURE_RTC_PERIODIC_INTSAM L21/L22/C20/C21/R30
FEATURE_RTC_PRESCALER_OFFSAM L21/L22/C20/C21/R30
FEATURE_RTC_CLOCK_SELECTIONSAM L21/L22/C20/C21/R30
FEATURE_RTC_GENERAL_PURPOSE_REGSAM L21/L22/R30
FEATURE_RTC_CONTINUOUSLY_UPDATEDSAM D20, SAM D21, SAM R21, SAM D10, SAM D11, SAM DA1, SAM HA1
FEATURE_RTC_TAMPER_DETECTIONSAM L22
* \note The specific features are only available in the driver when the * selected device supports those features. * * \subsection asfdoc_sam0_rtc_calendar_module_overview_alarms 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: * * \f[ COUNT_{MAX} = 2^{32}-1 \f] * * 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. * * \subsection asfdoc_sam0_rtc_calendar_module_overview_periodic 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[ f_{PERIODIC}=\frac{f_{ASY}}{2^{n+3}} \f] * * Where \f$f_{ASY}\f$ refers to the \e 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 \b 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 * \ref asfdoc_sam0_rtc_calendar_module_rtc_hz "the table below". * * \anchor asfdoc_sam0_rtc_calendar_module_rtc_hz * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
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 * \ref asfdoc_sam0_events_group "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. * * \subsection asfdoc_sam0_rtc_calendar_module_overview_correction 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: * * \f[ Correction(PPM) = \frac{VALUE}{999424}10^6 \f] * * The RTC clock will tick faster if provided with a positive correction value, * and slower when given a negative correction value. * * * \subsection asfdoc_sam0_rtc_calendar_module_overview_tamper_detect RTC Tamper Detect * See \ref asfdoc_sam0_rtc_tamper_detect. * * \section asfdoc_sam0_rtc_calendar_special_considerations Special Considerations * * \subsection asfdoc_sam0_rtc_calendar_special_considerations_year 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: * * \f[ [YEAR_{START}, YEAR_{START}+64] \f] * * \subsection asfdoc_sam0_rtc_calendar_special_considerations_clock Clock Setup * \subsubsection asfdoc_sam0_rtc_calendar_clock_samd_r 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. * \ref asfdoc_sam0_rtc_calendar_rtc_out_freq "The table below" lists the * available RTC frequencies for each possible GCLK and RTC input prescaler * options. * * \anchor asfdoc_sam0_rtc_calendar_rtc_out_freq * * * * * * * * * * * * * * * * * * * * * * *
RTC Output Frequencies from Allowable Input Clocks
End-frequencyGCLK prescalerRTC prescaler
32KHz11
1KHz321
1Hz321024
* * The overall RTC module clocking scheme is shown in * \ref asfdoc_sam0_rtc_calendar_rtc_clock_fig "the figure below". * * \anchor asfdoc_sam0_rtc_calendar_rtc_clock_fig * \dot * digraph clocking_scheme { * rankdir=LR; * GCLK [shape="record", label=" GCLK | RTC_GCLK", * bgcolor="lightgray", style="filled"]; * RTCPRE [shape="record" label=" RTC | RTC PRESCALER"]; * RTC [shape="record", label=" RTC | RTC CLOCK"]; * * GCLK:f1 -> RTCPRE:f1; * RTCPRE:f1 -> RTC:f1; * } * \enddot * * \note For the calendar to operate correctly, an asynchronous clock of 1Hz * should be used. * * \subsubsection asfdoc_sam0_rtc_calendar_clock_saml 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. * * \ref asfdoc_sam0_rtc_calendar_rtc_clk lists the available RTC clock. * * \anchor asfdoc_sam0_rtc_calendar_rtc_clk * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
RTC Clocks Source
RTC clock frequencyClock sourceDescription
1.024kHzULP1K1.024kHz from 32KHz internal ULP oscillator
32.768kHzULP32K32.768kHz from 32KHz internal ULP oscillator
1.024kHzOSC1K1.024kHz from 32KHz internal oscillator
32.768kHzOSC32K32.768kHz from 3KkHz internal oscillator
1.024kHzXOSC1K1.024kHz from 32KHz internal oscillator
32.768kHzXOSC32K32.768kHz from 32KHz external crystal oscillator
* * \note For the calendar to operate correctly, an asynchronous clock of 1Hz * should be used. * * \section asfdoc_sam0_rtc_calendar_extra_info Extra Information * * For extra information, see \ref asfdoc_sam0_rtc_calendar_extra. This includes: * - \ref asfdoc_sam0_rtc_calendar_extra_acronyms * - \ref asfdoc_sam0_rtc_calendar_extra_dependencies * - \ref asfdoc_sam0_rtc_calendar_extra_errata * - \ref asfdoc_sam0_rtc_calendar_extra_history * * * \section asfdoc_sam0_rtc_calendar_examples Examples * * For a list of examples related to this driver, see * \ref asfdoc_sam0_rtc_calendar_exqsg. * * * \section asfdoc_sam0_rtc_calendar_api_overview API Overview * @{ */ #include #if RTC_CALENDAR_ASYNC == true # include #endif #ifdef __cplusplus extern "C" { #endif /** * Define port features set according to different device family * @{ */ #if (SAML21) || (SAML22) || (SAMC20) || (SAMC21) || (SAMR30) || defined(__DOXYGEN__) /** RTC periodic interval interrupt. */ # define FEATURE_RTC_PERIODIC_INT /** RTC prescaler is off. */ # define FEATURE_RTC_PRESCALER_OFF /** RTC clock selection. */ # define FEATURE_RTC_CLOCK_SELECTION # if !(SAMC20) && !(SAMC21) /** General purpose registers. */ # define FEATURE_RTC_GENERAL_PURPOSE_REG # endif #else /** RTC continuously updated. */ # define FEATURE_RTC_CONTINUOUSLY_UPDATED #endif #if (SAML22) || defined(__DOXYGEN__) /** RTC tamper detection. */ # define FEATURE_RTC_TAMPER_DETECTION #endif /*@}*/ #ifdef FEATURE_RTC_CLOCK_SELECTION /** * \brief Available clock source for RTC. * RTC clock source. */ enum rtc_clock_sel { /** 1.024kHz from 32KHz internal ULP oscillator */ RTC_CLOCK_SELECTION_ULP1K = OSC32KCTRL_RTCCTRL_RTCSEL_ULP1K_Val, /** 32.768kHz from 32KHz internal ULP oscillator */ RTC_CLOCK_SELECTION_ULP32K = OSC32KCTRL_RTCCTRL_RTCSEL_ULP32K_Val, #if !(SAML22) /** 1.024kHz from 32KHz internal oscillator */ RTC_CLOCK_SELECTION_OSC1K = OSC32KCTRL_RTCCTRL_RTCSEL_OSC1K_Val, /** 32.768kHz from 32KHz internal oscillator */ RTC_CLOCK_SELECTION_OSC32K = OSC32KCTRL_RTCCTRL_RTCSEL_OSC32K_Val, #endif /** 1.024kHz from 32KHz internal oscillator */ RTC_CLOCK_SELECTION_XOSC1K = OSC32KCTRL_RTCCTRL_RTCSEL_XOSC1K_Val, /** 32.768kHz from 32.768kHz external crystal oscillator */ RTC_CLOCK_SELECTION_XOSC32K = OSC32KCTRL_RTCCTRL_RTCSEL_XOSC32K_Val, }; #endif #if !defined (RTC_NUM_OF_ALARMS) && defined(RTC_ALARM_NUM) #define RTC_NUM_OF_ALARMS RTC_ALARM_NUM #endif /** * \brief Available alarm channels. * * Available alarm channels. * * \note Not all alarm channels are available on all devices. */ enum rtc_calendar_alarm { /** Alarm channel 0 */ RTC_CALENDAR_ALARM_0 = 0, #if (RTC_NUM_OF_ALARMS > 1) || defined(__DOXYGEN__) /** Alarm channel 1 */ RTC_CALENDAR_ALARM_1 = 1, #endif #if (RTC_NUM_OF_ALARMS > 2) || defined(__DOXYGEN__) /** Alarm channel 2 */ RTC_CALENDAR_ALARM_2 = 2, #endif #if (RTC_NUM_OF_ALARMS > 3) || defined(__DOXYGEN__) /** Alarm channel 3 */ RTC_CALENDAR_ALARM_3 = 3, #endif }; #ifdef FEATURE_RTC_PERIODIC_INT /** * \brief Available periodic interval source. */ enum rtc_calendar_periodic_interval{ /** Periodic interval 0 */ RTC_CALENDAR_PERIODIC_INTERVAL_0 = 0, /** Periodic interval 1 */ RTC_CALENDAR_PERIODIC_INTERVAL_1 = 1, /** Periodic interval 2 */ RTC_CALENDAR_PERIODIC_INTERVAL_2 = 2, /** Periodic interval 3 */ RTC_CALENDAR_PERIODIC_INTERVAL_3 = 3, /** Periodic interval 4 */ RTC_CALENDAR_PERIODIC_INTERVAL_4 = 4, /** Periodic interval 5 */ RTC_CALENDAR_PERIODIC_INTERVAL_5 = 5, /** Periodic interval 6 */ RTC_CALENDAR_PERIODIC_INTERVAL_6 = 6, /** Periodic interval 7 */ RTC_CALENDAR_PERIODIC_INTERVAL_7 = 7, }; #endif #if RTC_CALENDAR_ASYNC == true #ifdef FEATURE_RTC_PERIODIC_INT /** * \brief Callback types. * * The available callback types for the RTC calendar module. */ enum rtc_calendar_callback { /** Callback for Periodic Interval 0 Interrupt */ RTC_CALENDAR_CALLBACK_PERIODIC_INTERVAL_0 = 0, /** Callback for Periodic Interval 1 Interrupt */ RTC_CALENDAR_CALLBACK_PERIODIC_INTERVAL_1, /** Callback for Periodic Interval 2 Interrupt */ RTC_CALENDAR_CALLBACK_PERIODIC_INTERVAL_2, /** Callback for Periodic Interval 3 Interrupt */ RTC_CALENDAR_CALLBACK_PERIODIC_INTERVAL_3, /** Callback for Periodic Interval 4 Interrupt */ RTC_CALENDAR_CALLBACK_PERIODIC_INTERVAL_4, /** Callback for Periodic Interval 5 Interrupt */ RTC_CALENDAR_CALLBACK_PERIODIC_INTERVAL_5, /** Callback for Periodic Interval 6 Interrupt */ RTC_CALENDAR_CALLBACK_PERIODIC_INTERVAL_6, /** Callback for Periodic Interval 7 Interrupt */ RTC_CALENDAR_CALLBACK_PERIODIC_INTERVAL_7, /** Callback for alarm 0 */ RTC_CALENDAR_CALLBACK_ALARM_0, # if (RTC_NUM_OF_ALARMS > 1) || defined(__DOXYGEN__) /** Callback for alarm 1 */ RTC_CALENDAR_CALLBACK_ALARM_1, # endif # if (RTC_NUM_OF_ALARMS > 2) || defined(__DOXYGEN__) /** Callback for alarm 2 */ RTC_CALENDAR_CALLBACK_ALARM_2, # endif # if (RTC_NUM_OF_ALARMS > 3) || defined(__DOXYGEN__) /** Callback for alarm 3 */ RTC_CALENDAR_CALLBACK_ALARM_3, # endif #ifdef FEATURE_RTC_TAMPER_DETECTION /** Callback for tamper */ RTC_CALENDAR_CALLBACK_TAMPER, #endif /** Callback for overflow */ RTC_CALENDAR_CALLBACK_OVERFLOW, # if !defined(__DOXYGEN__) /** Total number of callbacks */ _RTC_CALENDAR_CALLBACK_N # endif }; #else /** * \brief Callback types. * * The available callback types for the RTC calendar module. */ enum rtc_calendar_callback { /** Callback for alarm 0 */ RTC_CALENDAR_CALLBACK_ALARM_0 = 0, # if (RTC_NUM_OF_ALARMS > 1) || defined(__DOXYGEN__) /** Callback for alarm 1 */ RTC_CALENDAR_CALLBACK_ALARM_1, # endif # if (RTC_NUM_OF_ALARMS > 2) || defined(__DOXYGEN__) /** Callback for alarm 2 */ RTC_CALENDAR_CALLBACK_ALARM_2, # endif # if (RTC_NUM_OF_ALARMS > 3) || defined(__DOXYGEN__) /** Callback for alarm 3 */ RTC_CALENDAR_CALLBACK_ALARM_3, # endif #ifdef FEATURE_RTC_TAMPER_DETECTION /** Callback for tamper */ RTC_CALENDAR_CALLBACK_TAMPER, #endif /** Callback for overflow */ RTC_CALENDAR_CALLBACK_OVERFLOW, # if !defined(__DOXYGEN__) /** Total number of callbacks */ _RTC_CALENDAR_CALLBACK_N # endif }; #endif # if !defined(__DOXYGEN__) typedef void (*rtc_calendar_callback_t)(void); # endif #endif #ifdef FEATURE_RTC_PRESCALER_OFF /** * \brief RTC input clock prescaler settings. * * The available input clock prescaler values for the RTC calendar module. */ enum rtc_calendar_prescaler { /** RTC prescaler is off, and the input clock frequency is prescaled by a factor of 1 */ RTC_CALENDAR_PRESCALER_OFF = RTC_MODE2_CTRLA_PRESCALER_OFF, /** RTC input clock frequency is prescaled by a factor of 1 */ RTC_CALENDAR_PRESCALER_DIV_1 = RTC_MODE2_CTRLA_PRESCALER_DIV1, /** RTC input clock frequency is prescaled by a factor of 2 */ RTC_CALENDAR_PRESCALER_DIV_2 = RTC_MODE2_CTRLA_PRESCALER_DIV2, /** RTC input clock frequency is prescaled by a factor of 4 */ RTC_CALENDAR_PRESCALER_DIV_4 = RTC_MODE2_CTRLA_PRESCALER_DIV4, /** RTC input clock frequency is prescaled by a factor of 8 */ RTC_CALENDAR_PRESCALER_DIV_8 = RTC_MODE2_CTRLA_PRESCALER_DIV8, /** RTC input clock frequency is prescaled by a factor of 16 */ RTC_CALENDAR_PRESCALER_DIV_16 = RTC_MODE2_CTRLA_PRESCALER_DIV16, /** RTC input clock frequency is prescaled by a factor of 32 */ RTC_CALENDAR_PRESCALER_DIV_32 = RTC_MODE2_CTRLA_PRESCALER_DIV32, /** RTC input clock frequency is prescaled by a factor of 64 */ RTC_CALENDAR_PRESCALER_DIV_64 = RTC_MODE2_CTRLA_PRESCALER_DIV64, /** RTC input clock frequency is prescaled by a factor of 128 */ RTC_CALENDAR_PRESCALER_DIV_128 = RTC_MODE2_CTRLA_PRESCALER_DIV128, /** RTC input clock frequency is prescaled by a factor of 256 */ RTC_CALENDAR_PRESCALER_DIV_256 = RTC_MODE2_CTRLA_PRESCALER_DIV256, /** RTC input clock frequency is prescaled by a factor of 512 */ RTC_CALENDAR_PRESCALER_DIV_512 = RTC_MODE2_CTRLA_PRESCALER_DIV512, /** RTC input clock frequency is prescaled by a factor of 1024 */ RTC_CALENDAR_PRESCALER_DIV_1024 = RTC_MODE2_CTRLA_PRESCALER_DIV1024, }; #else /** * \brief RTC input clock prescaler settings. * * The available input clock prescaler values for the RTC calendar module. */ enum rtc_calendar_prescaler { /** RTC input clock frequency is prescaled by a factor of 1 */ RTC_CALENDAR_PRESCALER_DIV_1 = RTC_MODE2_CTRL_PRESCALER_DIV1, /** RTC input clock frequency is prescaled by a factor of 2 */ RTC_CALENDAR_PRESCALER_DIV_2 = RTC_MODE2_CTRL_PRESCALER_DIV2, /** RTC input clock frequency is prescaled by a factor of 4 */ RTC_CALENDAR_PRESCALER_DIV_4 = RTC_MODE2_CTRL_PRESCALER_DIV4, /** RTC input clock frequency is prescaled by a factor of 8 */ RTC_CALENDAR_PRESCALER_DIV_8 = RTC_MODE2_CTRL_PRESCALER_DIV8, /** RTC input clock frequency is prescaled by a factor of 16 */ RTC_CALENDAR_PRESCALER_DIV_16 = RTC_MODE2_CTRL_PRESCALER_DIV16, /** RTC input clock frequency is prescaled by a factor of 32 */ RTC_CALENDAR_PRESCALER_DIV_32 = RTC_MODE2_CTRL_PRESCALER_DIV32, /** RTC input clock frequency is prescaled by a factor of 64 */ RTC_CALENDAR_PRESCALER_DIV_64 = RTC_MODE2_CTRL_PRESCALER_DIV64, /** RTC input clock frequency is prescaled by a factor of 128 */ RTC_CALENDAR_PRESCALER_DIV_128 = RTC_MODE2_CTRL_PRESCALER_DIV128, /** RTC input clock frequency is prescaled by a factor of 256 */ RTC_CALENDAR_PRESCALER_DIV_256 = RTC_MODE2_CTRL_PRESCALER_DIV256, /** RTC input clock frequency is prescaled by a factor of 512 */ RTC_CALENDAR_PRESCALER_DIV_512 = RTC_MODE2_CTRL_PRESCALER_DIV512, /** RTC input clock frequency is prescaled by a factor of 1024 */ RTC_CALENDAR_PRESCALER_DIV_1024 = RTC_MODE2_CTRL_PRESCALER_DIV1024, }; #endif #if !defined(__DOXYGEN__) /** * \brief Device structure. */ struct rtc_module { /** RTC hardware module */ Rtc *hw; /** If clock mode 24h */ bool clock_24h; #ifdef FEATURE_RTC_CONTINUOUSLY_UPDATED /** If continuously update clock register */ bool continuously_update; #endif /** Initial year for counter value 0 */ uint16_t year_init_value; # if RTC_CALENDAR_ASYNC == true /** Pointers to callback functions */ volatile rtc_calendar_callback_t callbacks[_RTC_CALENDAR_CALLBACK_N]; /** Mask for registered callbacks */ volatile uint16_t registered_callback; /** Mask for enabled callbacks */ volatile uint16_t enabled_callback; # endif }; #endif /** * \brief Available mask options for alarms. * * Available mask options for alarms. */ enum rtc_calendar_alarm_mask { /** Alarm disabled */ RTC_CALENDAR_ALARM_MASK_DISABLED = RTC_MODE2_MASK_SEL_OFF, /** Alarm match on second */ RTC_CALENDAR_ALARM_MASK_SEC = RTC_MODE2_MASK_SEL_SS, /** Alarm match on second and minute */ RTC_CALENDAR_ALARM_MASK_MIN = RTC_MODE2_MASK_SEL_MMSS, /** Alarm match on second, minute, and hour */ RTC_CALENDAR_ALARM_MASK_HOUR = RTC_MODE2_MASK_SEL_HHMMSS, /** Alarm match on second, minute, hour, and day */ RTC_CALENDAR_ALARM_MASK_DAY = RTC_MODE2_MASK_SEL_DDHHMMSS, /** Alarm match on second, minute, hour, day, and month */ RTC_CALENDAR_ALARM_MASK_MONTH = RTC_MODE2_MASK_SEL_MMDDHHMMSS, /** Alarm match on second, minute, hour, day, month, and year */ RTC_CALENDAR_ALARM_MASK_YEAR = RTC_MODE2_MASK_SEL_YYMMDDHHMMSS, }; /** * \brief RTC Calendar event enable/disable structure. * * Event flags for the \ref rtc_calendar_enable_events() and * \ref rtc_calendar_disable_events(). */ struct rtc_calendar_events { /** Generate an output event on each overflow of the RTC count */ bool generate_event_on_overflow; /** Generate an output event on an alarm channel match against the RTC * count */ bool generate_event_on_alarm[RTC_NUM_OF_ALARMS]; /** Generate an output event periodically at a binary division of the RTC * counter frequency */ bool generate_event_on_periodic[8]; #ifdef FEATURE_RTC_TAMPER_DETECTION /** Generate an output event on every tamper input */ bool generate_event_on_tamper; /** Tamper input event and capture the CLOCK value */ bool on_event_to_tamper; #endif }; /** * \brief Time structure. * * Time structure containing the time given by or set to the RTC calendar. * The structure uses seven values to give second, minute, hour, PM/AM, day, * month, and year. It should be initialized via the * \ref rtc_calendar_get_time_defaults() function before use. */ struct rtc_calendar_time { /** Second value */ uint8_t second; /** Minute value */ uint8_t minute; /** Hour value */ uint8_t hour; /** PM/AM value, \c true for PM, or \c false for AM */ bool pm; /** Day value, where day 1 is the first day of the month */ uint8_t day; /** Month value, where month 1 is January */ uint8_t month; /** Year value */ uint16_t year; }; /** * \brief Alarm structure. * * Alarm structure containing time of the alarm and a mask to determine when * the alarm will trigger. */ struct rtc_calendar_alarm_time { /** Alarm time */ struct rtc_calendar_time time; /** Alarm mask to determine on what precision the alarm will match */ enum rtc_calendar_alarm_mask mask; }; /** * \brief RTC configuration structure. * * Configuration structure for the RTC instance. This structure should * be initialized using the \ref rtc_calendar_get_config_defaults() before any * user configurations are set. */ struct rtc_calendar_config { /** Input clock prescaler for the RTC module */ enum rtc_calendar_prescaler prescaler; /** If \c true, clears the clock on alarm match */ bool clear_on_match; #ifdef FEATURE_RTC_CONTINUOUSLY_UPDATED /** If \c true, the digital counter registers will be continuously updated * so that internal synchronization is not needed when reading the current * count */ bool continuously_update; #endif /** If \c true, time is represented in 24 hour mode */ bool clock_24h; /** Initial year for counter value 0 */ uint16_t year_init_value; #if (SAML21XXXB) || (SAML22) || (SAMC20) || (SAMC21) || (SAMR30) /** Enable count read synchronization. The CLOCK value requires * synchronization when reading. Disabling the synchronization * will prevent the CLOCK value from displaying the current value. */ bool enable_read_sync; #endif /** Alarm values */ struct rtc_calendar_alarm_time alarm[RTC_NUM_OF_ALARMS]; }; /** * \name Configuration and Initialization * @{ */ /** * \brief Initialize a \c 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). * * \param[out] time Time structure to initialize */ static inline void rtc_calendar_get_time_defaults( struct rtc_calendar_time *const time) { time->second = 0; time->minute = 0; time->hour = 0; time->pm = 0; time->day = 1; time->month = 1; time->year = 2000; } /** * \brief 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 * * \param[out] config Configuration structure to be initialized to default * values */ static inline void rtc_calendar_get_config_defaults( struct rtc_calendar_config *const config) { /* Sanity check argument */ Assert(config); /* Initialize and set time structure to default */ struct rtc_calendar_time time; rtc_calendar_get_time_defaults(&time); /* Set defaults into configuration structure */ config->prescaler = RTC_CALENDAR_PRESCALER_DIV_1024; config->clear_on_match = false; #ifdef FEATURE_RTC_CONTINUOUSLY_UPDATED config->continuously_update = false; #endif config->clock_24h = false; config->year_init_value = 2000; #if (SAML21XXXB) || (SAML22) || (SAMC20) || (SAMC21) || (SAMR30) config->enable_read_sync = true; #endif for (uint8_t i = 0; i < RTC_NUM_OF_ALARMS; i++) { config->alarm[i].time = time; config->alarm[i].mask = RTC_CALENDAR_ALARM_MASK_YEAR; } } void rtc_calendar_reset(struct rtc_module *const module); void rtc_calendar_enable(struct rtc_module *const module); void rtc_calendar_disable(struct rtc_module *const module); #if (RTC_INST_NUM > 1) && !defined(__DOXYGEN__) /** * \internal Find the index of given RTC module instance. * * \param[in] hw RTC module instance pointer * * \return Index of the given RTC module instance. */ uint8_t _rtc_get_inst_index( Rtc *const hw) { /* List of available RTC modules */ static Rtc *const rtc_modules[RTC_INST_NUM] = RTC_INSTS; /* Find index for RTC instance */ for (uint32_t i = 0; i < RTC_INST_NUM; i++) { if (hw == rtc_modules[i]) { return i; } } /* Invalid data given */ Assert(false); return 0; } #endif /* (RTC_INST_NUM > 1) && !defined(__DOXYGEN__) */ void rtc_calendar_init( struct rtc_module *const module, Rtc *const hw, const struct rtc_calendar_config *const config); void rtc_calendar_swap_time_mode(struct rtc_module *const module); enum status_code rtc_calendar_frequency_correction( struct rtc_module *const module, const int8_t value); /** @} */ /** \name Time and Alarm Management * @{ */ uint32_t rtc_calendar_time_to_register_value( struct rtc_module *const module, const struct rtc_calendar_time *const time); void rtc_calendar_register_value_to_time( struct rtc_module *const module, const uint32_t register_value, struct rtc_calendar_time *const time); void rtc_calendar_set_time( struct rtc_module *const module, const struct rtc_calendar_time *const time); void rtc_calendar_get_time( struct rtc_module *const module, struct rtc_calendar_time *const time); 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); 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); /** @} */ /** \name Status Flag Management * @{ */ /** * \brief 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. * * \param[in,out] module Pointer to the software instance struct * * \return Overflow state of the RTC module. * * \retval true If the RTC count value has overflowed * \retval false If the RTC count value has not overflowed */ static inline bool rtc_calendar_is_overflow(struct rtc_module *const module) { /* Sanity check arguments */ Assert(module); Assert(module->hw); Rtc *const rtc_module = module->hw; /* Return status of flag */ return (rtc_module->MODE2.INTFLAG.reg & RTC_MODE2_INTFLAG_OVF); } /** * \brief Clears the RTC overflow flag. * * \param[in,out] module Pointer to the software instance struct * * Clears the RTC module counter overflow flag, so that new overflow conditions * can be detected. */ static inline void rtc_calendar_clear_overflow(struct rtc_module *const module) { /* Sanity check arguments */ Assert(module); Assert(module->hw); Rtc *const rtc_module = module->hw; /* Clear flag */ rtc_module->MODE2.INTFLAG.reg = RTC_MODE2_INTFLAG_OVF; } #ifdef FEATURE_RTC_PERIODIC_INT /** * \brief Check if an RTC periodic interval interrupt has occurred. * * Checks the periodic interval flag in the RTC. * * \param[in,out] module RTC hardware module * \param[in] n RTC periodic interval interrupt * * \return Periodic interval interrupt state of the RTC module. * * \retval true RTC periodic interval interrupt occur * \retval false RTC periodic interval interrupt doesn't occur */ static inline bool rtc_calendar_is_periodic_interval(struct rtc_module *const module, enum rtc_calendar_periodic_interval n) { /* Sanity check arguments */ Assert(module); Assert(module->hw); Rtc *const rtc_module = module->hw; /* Return status of flag */ return (rtc_module->MODE2.INTFLAG.reg & RTC_MODE2_INTFLAG_PER(1 << n)); } /** * \brief Clears the RTC periodic interval flag. * * Clears the RTC module counter periodic interval flag, so that new periodic * interval conditions can be detected. * * \param[in,out] module RTC hardware module * \param[in] n RTC periodic interval interrupt */ static inline void rtc_calendar_clear_periodic_interval(struct rtc_module *const module, enum rtc_calendar_periodic_interval n) { /* Sanity check arguments */ Assert(module); Assert(module->hw); Rtc *const rtc_module = module->hw; /* Clear periodic interval flag */ rtc_module->MODE2.INTFLAG.reg = RTC_MODE2_INTFLAG_PER(1 << n); } #endif /** * \brief 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. * * \param[in,out] module Pointer to the software instance struct * \param[in] alarm_index Index of the alarm to check * * \returns Match status of the specified alarm. * * \retval true If the specified alarm has matched the current time * \retval false If the specified alarm has not matched the current time */ static inline bool rtc_calendar_is_alarm_match( struct rtc_module *const module, const enum rtc_calendar_alarm alarm_index) { /* Sanity check arguments */ Assert(module); Assert(module->hw); Rtc *const rtc_module = module->hw; /* Sanity check */ if ((uint32_t)alarm_index > RTC_NUM_OF_ALARMS) { Assert(false); return false; } /* Return int flag status */ return (rtc_module->MODE2.INTFLAG.reg & RTC_MODE2_INTFLAG_ALARM(1 << alarm_index)); } /** * \brief Clears the RTC alarm match flag. * * Clear the requested alarm match flag, so that future alarm matches can be * determined. * * \param[in,out] module Pointer to the software instance struct * \param[in] alarm_index The index of the alarm match to clear * * \return Status of the alarm match clear operation. * * \retval STATUS_OK If flag was cleared correctly * \retval STATUS_ERR_INVALID_ARG If invalid argument(s) were provided */ static inline enum status_code rtc_calendar_clear_alarm_match( struct rtc_module *const module, const enum rtc_calendar_alarm alarm_index) { /* Sanity check arguments */ Assert(module); Assert(module->hw); Rtc *const rtc_module = module->hw; /* Sanity check */ if ((uint32_t)alarm_index > RTC_NUM_OF_ALARMS) { Assert(false); return STATUS_ERR_INVALID_ARG; } /* Clear flag */ rtc_module->MODE2.INTFLAG.reg = RTC_MODE2_INTFLAG_ALARM(1 << alarm_index); return STATUS_OK; } /** @} */ /** * \name Event Management * @{ */ /** * \brief Enables an RTC event output. * * Enables one or more output events from the RTC module. See * \ref rtc_calendar_events for a list of events this module supports. * * \note Events cannot be altered while the module is enabled. * * \param[in,out] module Pointer to the software instance struct * \param[in] events Struct containing flags of events to enable */ static inline void rtc_calendar_enable_events( struct rtc_module *const module, struct rtc_calendar_events *const events) { /* Sanity check arguments */ Assert(module); Assert(module->hw); Rtc *const rtc_module = module->hw; uint32_t event_mask = 0; /* Check if the user has requested an overflow event */ if (events->generate_event_on_overflow) { event_mask |= RTC_MODE2_EVCTRL_OVFEO; } /* Check if the user has requested any alarm events */ for (uint8_t i = 0; i < RTC_NUM_OF_ALARMS; i++) { if (events->generate_event_on_alarm[i]) { event_mask |= RTC_MODE2_EVCTRL_ALARMEO(1 << i); } } /* Check if the user has requested any periodic events */ for (uint8_t i = 0; i < 8; i++) { if (events->generate_event_on_periodic[i]) { event_mask |= RTC_MODE2_EVCTRL_PEREO(1 << i); } } #ifdef FEATURE_RTC_TAMPER_DETECTION /* Check if the user has requested a tamper event output */ if (events->generate_event_on_tamper) { event_mask |= RTC_MODE2_EVCTRL_TAMPEREO; } /* Check if the user has requested a tamper event input */ if (events->on_event_to_tamper) { event_mask |= RTC_MODE2_EVCTRL_TAMPEVEI; } #endif /* Enable given event(s) */ rtc_module->MODE2.EVCTRL.reg |= event_mask; } /** * \brief Disables an RTC event output. * * Disabled one or more output events from the RTC module. See * \ref rtc_calendar_events for a list of events this module supports. * * \note Events cannot be altered while the module is enabled. * * \param[in,out] module Pointer to the software instance struct * \param[in] events Struct containing flags of events to disable */ static inline void rtc_calendar_disable_events( struct rtc_module *const module, struct rtc_calendar_events *const events) { /* Sanity check arguments */ Assert(module); Assert(module->hw); Rtc *const rtc_module = module->hw; uint32_t event_mask = 0; /* Check if the user has requested an overflow event */ if (events->generate_event_on_overflow) { event_mask |= RTC_MODE2_EVCTRL_OVFEO; } /* Check if the user has requested any alarm events */ for (uint8_t i = 0; i < RTC_NUM_OF_ALARMS; i++) { if (events->generate_event_on_alarm[i]) { event_mask |= RTC_MODE2_EVCTRL_ALARMEO(1 << i); } } /* Check if the user has requested any periodic events */ for (uint8_t i = 0; i < 8; i++) { if (events->generate_event_on_periodic[i]) { event_mask |= RTC_MODE2_EVCTRL_PEREO(1 << i); } } #ifdef FEATURE_RTC_TAMPER_DETECTION /* Check if the user has requested a tamper event output */ if (events->generate_event_on_tamper) { event_mask |= RTC_MODE2_EVCTRL_TAMPEREO; } /* Check if the user has requested a tamper event input */ if (events->on_event_to_tamper) { event_mask |= RTC_MODE2_EVCTRL_TAMPEVEI; } #endif /* Disable given event(s) */ rtc_module->MODE2.EVCTRL.reg &= ~event_mask; } /** @} */ #ifdef FEATURE_RTC_GENERAL_PURPOSE_REG /** * \name RTC General Purpose Registers * @{ */ /** * \brief Write a value into general purpose register. * * \param[in] module Pointer to the software instance struct * \param[in] n General purpose type * \param[in] index General purpose register index (0..3) * */ static inline void rtc_write_general_purpose_reg( struct rtc_module *const module, const uint8_t index, uint32_t value) { /* Sanity check arguments */ Assert(module); Assert(module->hw); Assert(index <= 3); Rtc *const rtc_module = module->hw; rtc_module->MODE0.GP[index].reg = value; } /** * \brief Read the value from general purpose register. * * \param[in] module Pointer to the software instance struct * \param[in] index General purpose register index (0..3) * * \return Value of general purpose register. */ static inline uint32_t rtc_read_general_purpose_reg( struct rtc_module *const module, const uint8_t index) { /* Sanity check arguments */ Assert(module); Assert(module->hw); Assert(index <= 3); Rtc *const rtc_module = module->hw; return rtc_module->MODE0.GP[index].reg; } /** @} */ #endif #ifdef FEATURE_RTC_TAMPER_DETECTION #include "rtc_tamper.h" /** * \brief Get the tamper stamp value. * * \param[in,out] module Pointer to the software instance struct * \param[out] time Pointer to value that filled with tamper stamp time */ void rtc_tamper_get_stamp (struct rtc_module *const module, struct rtc_calendar_time *const time); #endif /** @} */ #ifdef __cplusplus } #endif /** * \page asfdoc_sam0_rtc_calendar_extra Extra Information for RTC (CAL) Driver * * \section asfdoc_sam0_rtc_calendar_extra_acronyms Acronyms * Below is a table listing the acronyms used in this module, along with their * intended meanings. * * * * * * * * * * * * * * * * *
Acronym * Description *
RTCReal Time Counter
PPMPart Per Million
RCResistor/Capacitor
* * * \section asfdoc_sam0_rtc_calendar_extra_dependencies Dependencies * This driver has the following dependencies: * * - None * * * \section asfdoc_sam0_rtc_calendar_extra_errata Errata * There are no errata related to this driver. * * * \section asfdoc_sam0_rtc_calendar_extra_history Module History * An overview of the module history is presented in the table below, with * details on the enhancements and fixes made to the module since its first * release. The current version of this corresponds to the newest version in * the table. * * * * * * * * * * * * * * * * * *
Changelog
Added support for RTC tamper feature
Added driver instance parameter to all API function calls, except * get_config_defaults
Updated initialization function to also enable the digital interface * clock to the module if it is disabled
Initial release
*/ /** * \page asfdoc_sam0_rtc_calendar_exqsg Examples for RTC CAL Driver * * This is a list of the available Quick Start guides (QSGs) and example * applications for \ref asfdoc_sam0_rtc_calendar_group. QSGs are simple * examples with step-by-step instructions to configure and use this driver in a * selection of use cases. Note that a QSG can be compiled as a standalone * application or be added to the user application. * * - \subpage asfdoc_sam0_rtc_calendar_basic_use_case * \if RTC_CALENDAR_CALLBACK_MODE * - \subpage asfdoc_sam0_rtc_calendar_callback_use_case * \endif * * \page asfdoc_sam0_rtc_calendar_document_revision_history Document Revision History * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
Doc. Rev. * Date * Comments *
42126E12/2015Added support for SAM L21/L22, SAMR30, SAM C21, SAM D09, and SAM DA1
42126D12/2014Added support for SAM R21 and SAM D10/D11
42126C01/2014Added support for SAM D21
42126B06/2013Added additional documentation on the event system. Corrected * documentation typos
42126A06/2013Initial document release
*/ #endif /* RTC_CALENDAR_H_INCLUDED */