1.. _rtc_api:
2
3Real-Time Clock (RTC)
4#####################
5
6Overview
7********
8
9.. list-table:: **Glossary**
10    :widths: 30 80
11    :header-rows: 1
12
13    * - Word
14      - Definition
15    * - Real-time clock
16      - Low power device tracking time using broken-down time
17    * - Real-time counter
18      - Low power counter which can be used to track time
19    * - RTC
20      - Acronym for real-time clock
21
22An RTC is a low power device which tracks time using broken-down time.
23It should not be confused with low-power counters which sometimes share
24the same name, acronym, or both.
25
26RTCs are usually optimized for low energy consumption and are usually
27kept running even when the system is in a low power state.
28
29RTCs usually contain one or more alarms which can be configured to
30trigger at a given time. These alarms are commonly used to wake up the
31system from a low power state.
32
33Devicetree bindings
34*******************
35
36RTC bindings must include the ``rtc-device.yaml`` binding, which
37includes the ``base.yaml`` binding and the required ``alarms-count``
38property.
39
40.. code-block:: yaml
41
42   include: rtc-device.yaml
43
44Device driver design
45********************
46
47Driver init
48===========
49
50RTCs are never powered off by the system. On init, drivers should
51expect the RTC is either:
52
53* Powered, configured, and running.
54* Powered, unconfigured, and stopped.
55
56On init, drivers shall ensure the RTC is configured correctly, while
57preserving the time, alarms, and running status.
58
59Time is set by calling :c:func:`rtc_set_time`, at which point the
60RTC will start running. Alarms pending status is cleared by
61:c:func:`rtc_alarm_is_pending` or by an alarm callback resulting
62from :c:func:`rtc_alarm_set_callback`.
63
64GPIO routed interrupts
65======================
66
67RTCs with connected interrupt output pins shall configure and enable
68them on init. The host may enable and disable interrupts for its
69GPIOs, but RTC interrupt output pins must remain enabled.
70
71This ensures consistent behavior between internally and externally
72connected RTCs, and allows for system wakeup through GPIO on any
73enabled RTC event like alarms or update.
74
75.. note::
76
77   RTCs with unconnected interrupt output pins are not allowed to
78   periodically poll the RTC to emulate it being connected.
79   :c:func:`rtc_alarm_set_callback` and
80   :c:func:`rtc_update_set_callback` shall return ``-ENOTSUP`` in
81   this case.
82
83Clock output
84============
85
86If supported, the clock output configuration is defined in the
87devicetree. The output is configured by the driver on init.
88
89Configuration Options
90*********************
91
92Related configuration options:
93
94* :kconfig:option:`CONFIG_RTC`
95* :kconfig:option:`CONFIG_RTC_ALARM`
96* :kconfig:option:`CONFIG_RTC_UPDATE`
97* :kconfig:option:`CONFIG_RTC_CALIBRATION`
98
99API Reference
100*************
101
102.. doxygengroup:: rtc_interface
103
104RTC device driver test suite
105****************************
106
107The test suite validates the behavior of the RTC device driver. It
108is designed to be portable between boards. It uses the device tree
109alias ``rtc`` to designate the RTC device to test.
110
111This test suite tests the following:
112
113* Setting and getting the time.
114* RTC Time incrementing correctly.
115* Alarms if supported by hardware, with and without callback enabled
116* Calibration if supported by hardware.
117
118The calibration test tests a range of values which are printed to the
119console to be manually compared. The user must review the set and
120gotten values to ensure they are valid.
121
122By default, only the mandatory setting and getting of time is enabled
123for testing. To test the optional alarms, update event callback
124and clock calibration, these must be enabled by selecting
125:kconfig:option:`CONFIG_RTC_ALARM`, :kconfig:option:`CONFIG_RTC_UPDATE`
126and :kconfig:option:`CONFIG_RTC_CALIBRATION`.
127
128The following examples build the test suite for the ``native_sim``
129board. To build the test suite for a different board, replace the
130``native_sim`` board with your board.
131
132To build the test application with the default configuration, testing
133only the mandatory features, the following command can be used for
134reference:
135
136.. zephyr-app-commands::
137   :tool: west
138   :host-os: unix
139   :board: native_sim
140   :zephyr-app: tests/drivers/rtc/rtc_api
141   :goals: build
142
143To build the test with additional RTC features enabled, use menuconfig
144to enable the additional features by updating the configuration. The
145following command can be used for reference:
146
147.. zephyr-app-commands::
148   :tool: west
149   :host-os: unix
150   :board: native_sim
151   :zephyr-app: tests/drivers/rtc/rtc_api
152   :goals: menuconfig
153
154Then build the test application using the following command:
155
156.. zephyr-app-commands::
157   :tool: west
158   :host-os: unix
159   :board: native_sim
160   :zephyr-app: tests/drivers/rtc/rtc_api
161   :maybe-skip-config:
162   :goals: build
163
164To run the test suite, flash and run the application on your board, the output will
165be printed to the console.
166
167.. note::
168
169    The tests take up to 30 seconds each if they are testing real hardware.
170
171.. _rtc_api_emul_dev:
172
173RTC emulated device
174*******************
175
176The emulated RTC device fully implements the RTC API, and will behave like a real
177RTC device, with the following limitations:
178
179* RTC time is not persistent across application initialization.
180* RTC alarms are not persistent across application initialization.
181* RTC time will drift over time.
182
183Every time an application is initialized, the RTC's time and alarms are reset. Reading
184the time using :c:func:`rtc_get_time` will return ``-ENODATA``, until the time is
185set using :c:func:`rtc_set_time`. The RTC will then behave as a real RTC, until the
186application is reset.
187
188The emulated RTC device driver is built for the compatible
189:dtcompatible:`zephyr,rtc-emul` and will be included if :kconfig:option:`CONFIG_RTC`
190is selected.
191
192History of RTCs in Zephyr
193*************************
194
195RTCs have been supported before this API was created, using the
196:ref:`counter_api` API. The unix timestamp was used to convert
197between broken-down time and the unix timestamp within the RTC
198drivers, which internally used the broken-down time representation.
199
200The disadvantages of this approach were that hardware counters could
201not be set to a specific count, requiring all RTCs to use device
202specific APIs to set the time, converting from unix time to
203broken-down time, unnecessarily in some cases, and some common
204features missing, like input clock calibration and the update
205callback.
206