| Kévin Redon | b14518c | 2019-06-06 13:54:50 +0200 | [diff] [blame] | 1 | =============================== |
| 2 | The Calendar driver (bare-bone) |
| 3 | =============================== |
| 4 | |
| 5 | The Calendar driver provides means to set and get current date and time. |
| 6 | After enabling, an instance of the driver starts counting time from the base date with |
| 7 | the resolution of one second. The default base date is 00:00:00 1st of January 1970. |
| 8 | Only the base year of the base date can be changed via the driver API. |
| 9 | |
| 10 | The current date and time is kept internally in a relative form as the difference between |
| 11 | current date and time and the base date and time. This means that changing the base year changes |
| 12 | current date. |
| 13 | |
| 14 | The base date and time defines time "zero" or the earliest possible point in time that the calender driver can describe, |
| 15 | this means that current time and alarms can not be set to anything earlier than this time. |
| 16 | |
| 17 | The Calendar driver provides alarm functionality. |
| 18 | An alarm is a software trigger which fires on particular date and time with particular periodicity. |
| 19 | Upon firing the given callback function is called. |
| 20 | |
| 21 | An alarm can be in single-shot mode, firing only once at matching time; or in repeating mode, meaning that it will |
| 22 | reschedule a new alarm automatically based on repeating mode configuration. |
| 23 | In single-shot mode an alarm is removed from the alarm queue before its callback is called. It allows an application to |
| 24 | reuse the memory of expired alarm in the callback. |
| 25 | |
| 26 | An alarm can be triggered on the following events: match on second, minute, hour, day, month or year. |
| 27 | Matching on second means that the alarm is triggered when the value of seconds of the current time is equal to |
| 28 | the alarm's value of seconds. This means repeating alarm with match on seconds is triggered with the period of a minute. |
| 29 | Matching on minute means that the calendars minute and seconds values has to match the alarms, the rest of the date-time |
| 30 | value is ignored. In repeating mode this means a new alarm every hour. |
| 31 | The same logic is applied to match on hour, day, month and year. |
| 32 | |
| 33 | Each instance of the Calendar driver supports infinite amount of software alarms, only limited by the amount of RAM available. |
| 34 | |
| 35 | Features |
| 36 | -------- |
| 37 | * Initialization and de-initialization |
| 38 | * Enabling and disabling |
| 39 | * Date and time operations |
| 40 | * Software alarms |
| 41 | |
| 42 | Applications |
| 43 | ------------ |
| 44 | * A source of current date and time for an embedded system. |
| 45 | * Periodical functionality in low-power applications since the driver is designed to use 1Hz clock. |
| 46 | * Periodical function calls in case if it is more convenient to operate with absolute time. |
| 47 | |
| 48 | Dependencies |
| 49 | ------------ |
| 50 | * This driver expects a counter to be increased by one every second to count date and time correctly. |
| 51 | * Each instance of the driver requires separate hardware timer. |
| 52 | |
| 53 | Concurrency |
| 54 | ----------- |
| 55 | The Calendar driver is an interrupt driven driver.This means that the interrupt that triggers an alarm may occur during |
| 56 | the process of adding or removing an alarm via the driver's API. In such case the interrupt processing is postponed |
| 57 | until the alarm adding or removing is complete. |
| 58 | |
| 59 | The alarm queue is not protected from the access by interrupts not used by the driver. Due to this |
| 60 | it is not recommended to add or remove an alarm from such interrupts: in case if a higher priority interrupt supersedes |
| 61 | the driver's interrupt, adding or removing an alarm may cause unpredictable behavior of the driver. |
| 62 | |
| 63 | Limitations |
| 64 | ----------- |
| 65 | * Only years divisible by 4 are deemed a leap year, this gives a correct result between the years 1901 to 2099. |
| 66 | * 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. |
| 67 | * 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. |
| 68 | * Changing the base year or setting current date or time does not shift alarms' date and time accordingly or expires alarms. |
| 69 | |
| 70 | Knows issues and workarounds |
| 71 | ---------------------------- |
| 72 | Not applicable |