ASF: add related RTC files

this add the documentation and (yet unused) RTC definitions so to
by in sync with the ASFv4 upstream library

Change-Id: If3e24ede24b4e8cc2724a796756a5a2aa81119de

sysmoOCTSIM/hal/documentation/calendar.rst

@@ -0,0 +1,72 @@
+===============================
+The Calendar driver (bare-bone)
+===============================
+
+The Calendar driver provides means to set and get current date and time.
+After enabling, an instance of the driver starts counting time from the base date with
+the resolution of one second. The default base date is 00:00:00 1st of January 1970.
+Only the base year of the base date can be changed via the driver API.
+
+The current date and time is kept internally in a relative form as the difference between
+current date and time and the base date and time. This means that changing the base year changes
+current date.
+
+The base date and time defines time "zero" or the earliest possible point in time that the calender driver can describe,
+this means that current time and alarms can not be set to anything earlier than this time.
+
+The Calendar driver provides alarm functionality.
+An alarm is a software trigger which fires on particular date and time with particular periodicity.
+Upon firing the given callback function is called.
+
+An alarm can be in single-shot mode, firing only once at matching time; or in repeating mode, meaning that it will
+reschedule a new alarm automatically based on repeating mode configuration.
+In single-shot mode an alarm is removed from the alarm queue before its callback is called. It allows an application to
+reuse the memory of expired alarm in the callback.
+
+An alarm can be triggered on the following events: match on second, minute, hour, day, month or year.
+Matching on second means that the alarm is triggered when the value of seconds of the current time is equal to
+the alarm's value of seconds. This means repeating alarm with match on seconds is triggered with the period of a minute.
+Matching on minute means that the calendars minute and seconds values has to match the alarms, the rest of the date-time
+value is ignored. In repeating mode this means a new alarm every hour.
+The same logic is applied to match on hour, day, month and year.
+
+Each instance of the Calendar driver supports infinite amount of software alarms, only limited by the amount of RAM available.
+
+Features
+--------
+* Initialization and de-initialization
+* Enabling and disabling
+* Date and time operations
+* Software alarms
+
+Applications
+------------
+* A source of current date and time for an embedded system.
+* Periodical functionality in low-power applications since the driver is designed to use 1Hz clock.
+* Periodical function calls in case if it is more convenient to operate with absolute time.
+
+Dependencies
+------------
+* This driver expects a counter to be increased by one every second to count date and time correctly.
+* Each instance of the driver requires separate hardware timer.
+
+Concurrency
+-----------
+The Calendar driver is an interrupt driven driver.This means that the interrupt that triggers an alarm may occur during
+the process of adding or removing an alarm via the driver's API. In such case the interrupt processing is postponed
+until the alarm adding or removing is complete.
+
+The alarm queue is not protected from the access by interrupts not used by the driver. Due to this
+it is not recommended to add or remove an alarm from such interrupts: in case if a higher priority interrupt supersedes
+the driver's interrupt, adding or removing an alarm may cause unpredictable behavior of the driver.
+
+Limitations
+-----------
+* Only years divisible by 4 are deemed a leap year, this gives a correct result between the years 1901 to 2099.
+* The driver is designed to work outside of an operating system environment, the software alarm queue is therefore processed in interrupt context which may delay execution of other interrupts.
+* If there are a lot of frequently called interrupts with the priority higher than the driver's one, it may cause delay in alarm's triggering.
+* Changing the base year or setting current date or time does not shift alarms' date and time accordingly or expires alarms.
+
+Knows issues and workarounds
+----------------------------
+Not applicable

sysmoOCTSIM/hpl/rtc/hpl_rtc_base.h

@@ -0,0 +1,52 @@
+/**
+ * \file
+ *
+ * \brief RTC
+ *
+ * Copyright (c) 2016-2018 Microchip Technology Inc. and its subsidiaries.
+ *
+ * \asf_license_start
+ *
+ * \page License
+ *
+ * Subject to your compliance with these terms, you may use Microchip
+ * software and any derivatives exclusively with Microchip products.
+ * It is your responsibility to comply with third party license terms applicable
+ * to your use of third party software (including open source software) that
+ * may accompany Microchip software.
+ *
+ * THIS SOFTWARE IS SUPPLIED BY MICROCHIP "AS IS". NO WARRANTIES,
+ * WHETHER EXPRESS, IMPLIED OR STATUTORY, APPLY TO THIS SOFTWARE,
+ * INCLUDING ANY IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY,
+ * AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT WILL MICROCHIP BE
+ * LIABLE FOR ANY INDIRECT, SPECIAL, PUNITIVE, INCIDENTAL OR CONSEQUENTIAL
+ * LOSS, DAMAGE, COST OR EXPENSE OF ANY KIND WHATSOEVER RELATED TO THE
+ * SOFTWARE, HOWEVER CAUSED, EVEN IF MICROCHIP HAS BEEN ADVISED OF THE
+ * POSSIBILITY OR THE DAMAGES ARE FORESEEABLE.  TO THE FULLEST EXTENT
+ * ALLOWED BY LAW, MICROCHIP'S TOTAL LIABILITY ON ALL CLAIMS IN ANY WAY
+ * RELATED TO THIS SOFTWARE WILL NOT EXCEED THE AMOUNT OF FEES, IF ANY,
+ * THAT YOU HAVE PAID DIRECTLY TO MICROCHIP FOR THIS SOFTWARE.
+ *
+ * \asf_license_stop
+ */
+
+#ifndef _HPL_RTC2_V200_H_INCLUDED
+#define _HPL_RTC2_V200_H_INCLUDED
+
+#include <hpl_timer.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * \brief Retrieve timer helper functions
+ *
+ * \return A pointer to set of timer helper functions
+ */
+struct _timer_hpl_interface *_rtc_get_timer(void);
+
+#ifdef __cplusplus
+}
+#endif
+#endif /* _HPL_RTC2_V200_H_INCLUDED */