include/drivers: Add RTC support

MAINTAINERS.yml

@@ -1112,6 +1112,18 @@ Release Notes:
   labels:
     - "area: Retained Memory"
 
+"Drivers: RTC":
+  status: maintained
+  maintainers:
+    - bjarki-trackunit
+  files:
+    - drivers/rtc/
+    - tests/drivers/rtc/
+    - doc/hardware/peripherals/rtc.rst
+    - include/zephyr/drivers/rtc.h
+  labels:
+    - "area: RTC"
+
 "Drivers: PCI":
   status: maintained
   maintainers:

boards/posix/native_posix/native_posix.dts

@@ -31,6 +31,7 @@
 		spi-0 = &spi0;
 		led0 = &led0;
 		kscan0 = &sdl_kscan;
+		rtc = &rtc;
 	};
 
 	leds {
@@ -200,4 +201,10 @@
 		sample-point = <875>;
 		bus-speed = <125000>;
 	};
+
+	rtc: rtc {
+		status = "okay";
+		compatible = "zephyr,rtc-emul";
+		alarms-count = <2>;
+	};
 };

doc/develop/api/overview.rst

@@ -245,6 +245,10 @@ between major releases are available in the :ref:`zephyr_release_notes`.
      - Experimental
      - 3.1
 
+   * - :ref:`rtc_api`
+     - Experimental
+     - 3.4
+
    * - :ref:`rtio_api`
      - Experimental
      - 3.2

doc/hardware/peripherals/rtc.rst

@@ -6,11 +6,109 @@ Real-Time Clock (RTC)
 Overview
 ********
 
-This is a placeholder for API specific to real-time clocks.  Currently
-all RTC peripherals are implemented through :ref:`counter_api` with
-device-specific API for counters with real-time support.
+.. 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
+
+RTC device driver test suite
+****************************
+
+The test suite validates the behavior of the RTC device driver. It
+is designed to be portable between boards. It uses the device tree
+alias ``rtc`` to designate the RTC device to test.
+
+This test suite tests the following:
+
+* Setting and getting the time.
+* RTC Time incrementing correctly.
+* Alarms if supported by hardware, with and without callback enabled
+* Calibration if supported by hardware.
+
+The calibration test tests a range of values which are printed to the
+console to be manually compared. The user must review the set and
+gotten values to ensure they are valid.
+
+By default, only the mandatory Setting and getting time is enabled
+for testing. To test the optional alarms, update event callback
+and clock calibration, these must be enabled by selecting
+``CONFIG_RTC_ALARM``, ``CONFIG_RTC_UPDATE`` and
+``CONFIG_RTC_CALIBRATION``.
+
+To build the test application with default settings for a board which
+contains the device tree alias ``rtc``, the following command can be used
+for reference:
+
+::
+
+    $ west build -p -b <your board> zephyr/tests/drivers/rtc/rtc_api/
+
+To build the test with additional RTC features enabled, use menuconfig
+to enable the additional features. The following command can be used
+for reference:
+
+::
+
+    $ west build -p -b <your board> -t menuconfig zephyr/tests/drivers/rtc/rtc_api/
+
+Then build the test application using the following command
+
+::
+
+    $ west build
+
+To run the test suite, flash and run the application on your board, the output will
+be printed to the console.
+
+.. note::
+
+    The tests take up to 30 seconds each if they are testing real hardware.

drivers/CMakeLists.txt

@@ -75,3 +75,4 @@ add_subdirectory_ifdef(CONFIG_VIRTUALIZATION virtualization)
 add_subdirectory_ifdef(CONFIG_W1 w1)
 add_subdirectory_ifdef(CONFIG_WATCHDOG watchdog)
 add_subdirectory_ifdef(CONFIG_WIFI wifi)
+add_subdirectory_ifdef(CONFIG_RTC rtc)

drivers/Kconfig

@@ -79,5 +79,6 @@ source "drivers/w1/Kconfig"
 source "drivers/watchdog/Kconfig"
 source "drivers/wifi/Kconfig"
 source "drivers/xen/Kconfig"
+source "drivers/rtc/Kconfig"
 
 endmenu

drivers/rtc/CMakeLists.txt

@@ -0,0 +1,7 @@
+# Copyright (c) 2022 Bjarki Arge Andreasen
+# SPDX-License-Identifier: Apache-2.0
+
+zephyr_library()
+
+zephyr_library_sources_ifdef(CONFIG_USERSPACE rtc_handlers.c)
+zephyr_library_sources_ifdef(CONFIG_RTC_EMUL rtc_emul.c)

drivers/rtc/Kconfig

@@ -0,0 +1,28 @@
+# Copyright (c) 2022 Bjarki Arge Andreasen
+# SPDX-License-Identifier: Apache-2.0
+
+menuconfig RTC
+	bool "RTC driver support"
+
+if RTC
+
+config RTC_ALARM
+	bool "RTC driver alarm support"
+	help
+	  This is an option which enables driver support for RTC alarms.
+
+config RTC_UPDATE
+	bool "RTC driver update event callback support"
+	help
+	  This is an option which enables driver support for the RTC
+	  update event callback.
+
+config RTC_CALIBRATION
+	bool "RTC driver clock calibration support"
+	help
+	  This is an option which enables driver support for RTC clock
+	  calibration.
+
+source "drivers/rtc/Kconfig.emul"
+
+endif # RTC

drivers/rtc/Kconfig.emul

@@ -0,0 +1,9 @@
+# Copyright (c) 2022 Bjarki Arge Andreasen
+# SPDX-License-Identifier: Apache-2.0
+
+config RTC_EMUL
+	bool "Emulated RTC driver"
+	default y
+	depends on DT_HAS_ZEPHYR_RTC_EMUL_ENABLED
+	help
+	  Enable emulated Real-Time Clock (RTC) driver.