b557a1d711
This commit adds the rtc.h header file which contains API functions for real-time-clocks, which are low power devices which track and represent broken-down time. It also changes one line of doxygen documentation in the maxim_ds3132.h file to place it in its own group. The handlers for use of the API from userspace is also added with this commit. The API is split into one mandatory section, setting and getting time, and three optional sections, alarms, update event callback, and clock calibration. Signed-off-by: Bjarki Arge Andreasen <baa@trackunit.com>
61 lines
1.8 KiB
ReStructuredText
61 lines
1.8 KiB
ReStructuredText
.. _rtc_api:
|
|
|
|
Real-Time Clock (RTC)
|
|
#####################
|
|
|
|
Overview
|
|
********
|
|
|
|
.. list-table:: **Glossary**
|
|
:widths: 30 80
|
|
:header-rows: 1
|
|
|
|
* - Word
|
|
- Definition
|
|
* - Real-time clock
|
|
- Low power device tracking time using broken-down time
|
|
* - Real-time counter
|
|
- Low power counter which can be used to track time
|
|
* - RTC
|
|
- Acronym for real-time clock
|
|
|
|
An RTC is a low power device which tracks time using broken-down time.
|
|
It should not be confused with low-power counters which sometimes share
|
|
the same name, acronym, or both.
|
|
|
|
RTCs are usually optimized for low energy consumption and are usually
|
|
kept running even when the system is in a low power state.
|
|
|
|
RTCs usually contain one or more alarms which can be configured to
|
|
trigger at a given time. These alarms are commonly used to wake up the
|
|
system from a low power state.
|
|
|
|
History of RTCs in Zephyr
|
|
*************************
|
|
|
|
RTCs have been supported before this API was created, using the
|
|
:ref:`counter_api` API. The unix timestamp was used to convert
|
|
between broken-down time and the unix timestamp within the RTC
|
|
drivers, which internally used the broken-down time representation.
|
|
|
|
The disadvantages of this approach where that hardware counters can
|
|
not be set to a specific count, requiring all RTCs to use device
|
|
specific APIs to set the time, converting from unix time to
|
|
broken-down time, unnecessarily in some cases, and some common
|
|
features missing, like input clock calibration and the update
|
|
callback.
|
|
|
|
Configuration Options
|
|
*********************
|
|
|
|
Related configuration options:
|
|
|
|
* :kconfig:option:`CONFIG_RTC`
|
|
* :kconfig:option:`CONFIG_RTC_ALARM`
|
|
* :kconfig:option:`CONFIG_RTC_UPDATE`
|
|
* :kconfig:option:`CONFIG_RTC_CALIBRATION`
|
|
|
|
API Reference
|
|
*************
|
|
|
|
.. doxygengroup:: rtc_interface
|