RTC API refine documentation and test coverage

boards/posix/native_posix/native_posix.yaml

@@ -17,5 +17,6 @@ supported:
   - i2c
   - spi
   - gpio
+  - rtc
 testing:
   default: true

boards/posix/native_posix/native_posix_64.yaml

@@ -15,3 +15,4 @@ supported:
   - usb_device
   - adc
   - gpio
+  - rtc

doc/hardware/peripherals/rtc.rst

@@ -38,7 +38,7 @@ RTCs have been supported before this API was created, using the
 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
+The disadvantages of this approach were that hardware counters could
 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
@@ -78,33 +78,47 @@ 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
+By default, only the mandatory setting and getting of 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``.
+:kconfig:option:`CONFIG_RTC_ALARM`, :kconfig:option:`CONFIG_RTC_UPDATE`
+and :kconfig:option:`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:
+The following examples build the test suite for the ``native_posix``
+board. To build the test suite for a different board, replace the
+``native_posix`` board with your board.
 
-::
+To build the test application with the default configuration, testing
+only the mandatory features, the following command can be used for
+reference:
 
-    $ west build -p -b <your board> zephyr/tests/drivers/rtc/rtc_api/
+.. zephyr-app-commands::
+   :tool: west
+   :host-os: unix
+   :board: native_posix
+   :zephyr-app: tests/drivers/rtc/rtc_api
+   :goals: build
 
 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 enable the additional features by updating the configuration. The
+following command can be used for reference:
+
+.. zephyr-app-commands::
+   :tool: west
+   :host-os: unix
+   :board: native_posix
+   :zephyr-app: tests/drivers/rtc/rtc_api
+   :goals: menuconfig
+
+Then build the test application using the following command:
+
+.. zephyr-app-commands::
+   :tool: west
+   :host-os: unix
+   :board: native_posix
+   :zephyr-app: tests/drivers/rtc/rtc_api
+   :maybe-skip-config:
+   :goals: build
 
 To run the test suite, flash and run the application on your board, the output will
 be printed to the console.

doc/releases/release-notes-3.4.rst

@@ -172,6 +172,19 @@ New APIs in this release
   :kconfig:option:`CONFIG_FLASH_EX_OP_ENABLED` which depends on
   :kconfig:option:`CONFIG_FLASH_HAS_EX_OP` selected by driver.
 
+* Introduced :ref:`rtc_api` API which adds experimental support for real-time clock
+  devices. These devices previously used the :ref:`counter_api` API combined with
+  conversion between unix-time and broken-down time. The new API adds the mandatory
+  functions :c:func:`rtc_set_time` and :c:func:`rtc_get_time`, the optional functions
+  :c:func:`rtc_alarm_get_supported_fields`, :c:func:`rtc_alarm_set_time`,
+  :c:func:`rtc_alarm_get_time`, :c:func:`rtc_alarm_is_pending` and
+  :c:func:`rtc_alarm_set_callback` are enabled with
+  :kconfig:option:`CONFIG_RTC_ALARM`, the optional function
+  :c:func:`rtc_update_set_callback` is enabled with
+  :kconfig:option:`CONFIG_RTC_UPDATE`, and lastly, the optional functions
+  :c:func:`rtc_set_calibration` and :c:func:`rtc_get_calibration` are enabled with
+  :kconfig:option:`CONFIG_RTC_CALIBRATION`.
+
 Kernel
 ******
 

dts/bindings/rtc/rtc-device.yaml

@@ -3,11 +3,13 @@
 
 include: base.yaml
 
-description: RTC device common bindings
+description: RTC (real-time clock) device common bindings
 
 properties:
   alarms-count:
     type: int
-    required: true
+    default: 0
     description: |
-      Number of alarms supported by RTC device
+      Number of alarms supported by RTC device. The number of
+      alarms defaults to 0, which indicates that the RTC has
+      no alarms.

include/zephyr/drivers/rtc.h

@@ -30,7 +30,8 @@ extern "C" {
 
 /**
  * @brief Mask for alarm time fields to enable when setting alarm time
- * @defgroup rtc_alarm_time_mask RTC Alarm Time Mask
+ * @name RTC Alarm Time Mask
+ * @anchor RTC_ALARM_TIME_MASK
  * @{
  */
 #define RTC_ALARM_TIME_MASK_SECOND	BIT(0)
@@ -87,6 +88,12 @@ typedef void (*rtc_update_callback)(const struct device *dev, void *user_data);
  */
 typedef void (*rtc_alarm_callback)(const struct device *dev, uint16_t id, void *user_data);
 
+/**
+ * @cond INTERNAL_HIDDEN
+ *
+ * For internal driver use only, skip these in public documentation.
+ */
+
 /**
  * @typedef rtc_api_set_time
  * @brief API for setting RTC time
@@ -174,6 +181,8 @@ __subsystem struct rtc_driver_api {
 #endif /* CONFIG_RTC_CALIBRATION */
 };
 
+/** @endcond */
+
 /**
  * @brief API for setting RTC time.
  *
@@ -213,9 +222,7 @@ static inline int z_impl_rtc_get_time(const struct device *dev, struct rtc_time
 }
 
 /**
- * @brief RTC Interface Alarm
- * @defgroup rtc_interface_alarm RTC Interface Alarm
- * @ingroup rtc_interface
+ * @name RTC Interface Alarm
  * @{
  */
 #if defined(CONFIG_RTC_ALARM) || defined(__DOXYGEN__)
@@ -227,7 +234,7 @@ static inline int z_impl_rtc_get_time(const struct device *dev, struct rtc_time
  * @param id Id of the alarm
  * @param mask Mask of fields in the alarm time which are supported
  *
- * @note Bits in the mask param are defined here \ref rtc_alarm_time_mask
+ * @note Bits in the mask param are defined here @ref RTC_ALARM_TIME_MASK.
  *
  * @return 0 if successful
  * @return -EINVAL if id is out of range or time is invalid
@@ -265,7 +272,7 @@ static inline int z_impl_rtc_alarm_get_supported_fields(const struct device *dev
  *
  * @note The timeptr param may be NULL if the mask param is 0
  * @note Only the enabled fields in the timeptr param need to be configured
- * @note Bits in the mask param are defined here \ref rtc_alarm_time_mask
+ * @note Bits in the mask param are defined here @ref RTC_ALARM_TIME_MASK
  *
  * @return 0 if successful
  * @return -EINVAL if id is out of range or time is invalid
@@ -295,7 +302,7 @@ static inline int z_impl_rtc_alarm_set_time(const struct device *dev, uint16_t i
  * @param mask Destination for mask of fields which are enabled in the alarm time
  * @param timeptr Destination for the alarm time
  *
- * @note Bits in the mask param are defined here \ref rtc_alarm_time_mask
+ * @note Bits in the mask param are defined here @ref RTC_ALARM_TIME_MASK
  *
  * @return 0 if successful
  * @return -EINVAL if id is out of range
@@ -392,9 +399,7 @@ static inline int z_impl_rtc_alarm_set_callback(const struct device *dev, uint16
  */
 
 /**
- * @brief RTC Interface Update
- * @defgroup rtc_interface_update RTC Interface Update
- * @ingroup rtc_interface
+ * @name RTC Interface Update
  * @{
  */
 #if defined(CONFIG_RTC_UPDATE) || defined(__DOXYGEN__)
@@ -439,9 +444,7 @@ static inline int z_impl_rtc_update_set_callback(const struct device *dev,
  */
 
 /**
- * @brief RTC Interface Calibration
- * @defgroup rtc_interface_calibration RTC Interface Calibration
- * @ingroup rtc_interface
+ * @name RTC Interface Calibration
  * @{
  */
 #if defined(CONFIG_RTC_CALIBRATION) || defined(__DOXYGEN__)
@@ -504,8 +507,7 @@ static inline int z_impl_rtc_get_calibration(const struct device *dev, int32_t *
  */
 
 /**
- * @brief RTC Interface Helpers
- * @ingroup rtc_interface
+ * @name RTC Interface Helpers
  * @{
  */
 

tests/drivers/rtc/rtc_api_helpers/testcase.yaml

@@ -4,4 +4,3 @@
 tests:
   drivers.rtc.rtc_api:
     tags: drivers rtc api helpers
-    platform_allow: native_posix