boards/posix/native_posix: Add emulated RTC device driver

The emulated RTC device driver is used to emulate a real
RTC device. Note that it is not a replacement for the
native_rtc module, which is used to control simulated time,
get time from the host system, etc.

Signed-off-by: Bjarki Arge Andreasen <baa@trackunit.com>

Author: Bjarki Arge Andreasen

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/hardware/peripherals/rtc.rst

@@ -63,4 +63,52 @@ API Reference
 RTC device driver test suite
 ****************************
 
-See :ref:`rtc_api_test`
+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/rtc/CMakeLists.txt

@@ -5,4 +5,3 @@ zephyr_library()
 
 zephyr_library_sources_ifdef(CONFIG_USERSPACE rtc_handlers.c)
 zephyr_library_sources_ifdef(CONFIG_RTC_EMUL rtc_emul.c)
-

drivers/rtc/Kconfig

@@ -23,4 +23,6 @@ config RTC_CALIBRATION
 	  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.