| =============================== |
| 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 |