RTC API refine documentation and test coverage #56584

bjarki-andreasen · 2023-04-05T17:35:33Z

This PR is based on the remaining comments from @nordicjm on this PR #52618

The PR performs the following

Updates the release notes to mention the addition of the experimental RTC API
Opens up the RTC API helpers test suite to more test platforms,
Makes RTC API test suite run for native_posix and native_posix_64
Performs some general refinement of the doxygen documentation for the rtc.h header, and the rtc.rst documentation.
Makes the alarms-count dts property optional, with a default value of 0, instead of required.

nordicjm · 2023-04-06T12:24:41Z

doc/releases/release-notes-3.4.rst

+  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` enabled by :kconfig:option:`CONFIG_RTC_ALARM`,


Suggested change

:c:func:`rtc_alarm_set_callback` enabled by :kconfig:option:`CONFIG_RTC_ALARM`,

:c:func:`rtc_alarm_set_callback` are enabled with :kconfig:option:`CONFIG_RTC_ALARM`,

nordicjm · 2023-04-06T12:25:07Z

doc/releases/release-notes-3.4.rst

+  :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` enabled by :kconfig:option:`CONFIG_RTC_ALARM`,
+  theoptional function :c:func:`rtc_update_set_callback` enabled by


Suggested change

theoptional function :c:func:`rtc_update_set_callback` enabled by

the optional function :c:func:`rtc_update_set_callback` is enabled with

nordicjm · 2023-04-06T12:25:21Z

doc/releases/release-notes-3.4.rst

+  :c:func:`rtc_alarm_set_callback` enabled by :kconfig:option:`CONFIG_RTC_ALARM`,
+  theoptional function :c:func:`rtc_update_set_callback` enabled by
+  :kconfig:option:`CONFIG_RTC_UPDATE` and lastly the optional functions
+  :c:func:`rtc_set_calibration` and :c:func:`rtc_get_calibration` enabled by


Suggested change

:c:func:`rtc_set_calibration` and :c:func:`rtc_get_calibration` enabled by

:c:func:`rtc_set_calibration` and :c:func:`rtc_get_calibration` are enabled with

nordicjm · 2023-04-06T12:26:07Z

dts/bindings/rtc/rtc-device.yaml

@@ -8,6 +8,6 @@ description: RTC device common bindings
 properties:
  alarms-count:
    type: int
-    required: true
+    default: 0
    description: |
      Number of alarms supported by RTC device


Needs a description for a default, something like "Default of 0 to indicate that unless set otherwise, the RTC has no alarms"

henrikbrixandersen · 2023-04-19T15:33:23Z

doc/hardware/peripherals/rtc.rst

-    $ west build -p -b <your board> zephyr/tests/drivers/rtc/rtc_api/
+    west build -p -b <your board> zephyr/tests/drivers/rtc/rtc_api/


We should be using zephyr-app-commands:: here.

henrikbrixandersen · 2023-04-19T15:33:40Z

doc/hardware/peripherals/rtc.rst

-    $ west build -p -b <your board> -t menuconfig zephyr/tests/drivers/rtc/rtc_api/
+    west build -p -b <your board> -t menuconfig zephyr/tests/drivers/rtc/rtc_api/


henrikbrixandersen · 2023-04-19T15:33:56Z

doc/hardware/peripherals/rtc.rst

-    $ west build
+    west build


Fixed spelling mistakes, added links in place of highlighted text where appropriate and switched unformatted blocks with bash commands to bash code blocks. Signed-off-by: Bjarki Arge Andreasen <[email protected]>

Added entry for new RTC API in new APIs section of release notes. Signed-off-by: Bjarki Arge Andreasen <[email protected]>

@name

Hid type definitions of API functions from documentation using INTERNAL_HIDDEN condition. Changed nested groups inside rtc_interface group to use @name instead. Use @anchor to reference definitions for RTC_ALARM_TIME_MASK. Signed-off-by: Bjarki Arge Andreasen <[email protected]>

The test suite was limited to the native_posix board, now it is built and run for any board supported by CI. The native_posix yaml files for both 32 and 64 bit boards have been expanded to support rtc, allowing CI to build and test the rtc_api test suite against the native_posix and native_posix_64 boards. Signed-off-by: Bjarki Arge Andreasen <[email protected]>

This commit makes the alarms-count dts property of the rtc-device.yaml optional, setting the default to 0. This simplifies the dts rtc dts node by not requiring the property to be set to 0 if it is not supported. Signed-off-by: Bjarki Arge Andreasen <[email protected]>

bjarki-andreasen force-pushed the rtc_api_refine_docs branch 2 times, most recently from 1aaad4f to dfcf5bd Compare April 5, 2023 18:29

bjarki-andreasen marked this pull request as ready for review April 5, 2023 19:15

bjarki-andreasen requested review from nashif, carlescufi, galak, MaureenHelm, aescolar and daor-oti as code owners April 5, 2023 19:15

zephyrbot added Release Notes To be mentioned in the release notes area: RTC Real Time Clock area: Devicetree Binding PR modifies or adds a Device Tree binding area: native port Host native arch port (native_sim) area: Documentation labels Apr 5, 2023

zephyrbot requested a review from kartben April 5, 2023 19:16

zephyrbot assigned bjarki-andreasen Apr 5, 2023

bjarki-andreasen assigned nordicjm Apr 5, 2023

bjarki-andreasen changed the title ~~RTC API refine documentation~~ RTC API refine documentation and test coverage Apr 5, 2023

nordicjm reviewed Apr 6, 2023

View reviewed changes

bjarki-andreasen force-pushed the rtc_api_refine_docs branch from dfcf5bd to a0a3c2c Compare April 7, 2023 06:05

bjarki-andreasen requested a review from nordicjm April 7, 2023 06:44

nordicjm previously approved these changes Apr 11, 2023

View reviewed changes

bjarki-andreasen mentioned this pull request Apr 12, 2023

drivers: rtc: rtc_mc146818: Added RTC driver for Motorola MC146818B #56334

Merged

henrikbrixandersen self-requested a review April 14, 2023 05:51

bjarki-andreasen dismissed nordicjm’s stale review via 454de00 April 18, 2023 17:13

bjarki-andreasen force-pushed the rtc_api_refine_docs branch from a0a3c2c to 454de00 Compare April 18, 2023 17:13

jhedberg previously approved these changes Apr 19, 2023

View reviewed changes

henrikbrixandersen requested changes Apr 19, 2023

View reviewed changes

Bjarki Arge Andreasen added 2 commits April 20, 2023 10:07

doc/hardware/peripherals/rtc.rst: Refine docs

ac5c704

Fixed spelling mistakes, added links in place of highlighted text where appropriate and switched unformatted blocks with bash commands to bash code blocks. Signed-off-by: Bjarki Arge Andreasen <[email protected]>

doc/release/release-notes-3.4.rst: Added RTC API entry

93fcaef

Added entry for new RTC API in new APIs section of release notes. Signed-off-by: Bjarki Arge Andreasen <[email protected]>

Bjarki Arge Andreasen added 3 commits April 20, 2023 10:07

bjarki-andreasen dismissed jhedberg’s stale review via c4098f2 April 20, 2023 08:07

bjarki-andreasen force-pushed the rtc_api_refine_docs branch from 454de00 to c4098f2 Compare April 20, 2023 08:07

jhedberg approved these changes Apr 20, 2023

View reviewed changes

henrikbrixandersen requested review from henrikbrixandersen and nordicjm April 20, 2023 08:45

henrikbrixandersen approved these changes Apr 20, 2023

View reviewed changes

nordicjm approved these changes Apr 20, 2023

View reviewed changes

carlescufi merged commit 9eae6fd into zephyrproject-rtos:main Apr 20, 2023

bjarki-andreasen deleted the rtc_api_refine_docs branch April 20, 2023 14:07

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

RTC API refine documentation and test coverage #56584

RTC API refine documentation and test coverage #56584

bjarki-andreasen commented Apr 5, 2023 •

edited

Loading

nordicjm Apr 6, 2023

nordicjm Apr 6, 2023

nordicjm Apr 6, 2023

nordicjm Apr 6, 2023

henrikbrixandersen Apr 19, 2023

henrikbrixandersen Apr 19, 2023

henrikbrixandersen Apr 19, 2023

	:c:func:`rtc_alarm_set_callback` enabled by :kconfig:option:`CONFIG_RTC_ALARM`,
	:c:func:`rtc_alarm_set_callback` are enabled with :kconfig:option:`CONFIG_RTC_ALARM`,

	theoptional function :c:func:`rtc_update_set_callback` enabled by
	the optional function :c:func:`rtc_update_set_callback` is enabled with

	:c:func:`rtc_set_calibration` and :c:func:`rtc_get_calibration` enabled by
	:c:func:`rtc_set_calibration` and :c:func:`rtc_get_calibration` are enabled with

		$ west build -p -b <your board> zephyr/tests/drivers/rtc/rtc_api/
		west build -p -b <your board> zephyr/tests/drivers/rtc/rtc_api/

		$ west build -p -b <your board> -t menuconfig zephyr/tests/drivers/rtc/rtc_api/
		west build -p -b <your board> -t menuconfig zephyr/tests/drivers/rtc/rtc_api/

RTC API refine documentation and test coverage #56584

RTC API refine documentation and test coverage #56584

Conversation

bjarki-andreasen commented Apr 5, 2023 • edited Loading

nordicjm Apr 6, 2023

Choose a reason for hiding this comment

nordicjm Apr 6, 2023

Choose a reason for hiding this comment

nordicjm Apr 6, 2023

Choose a reason for hiding this comment

nordicjm Apr 6, 2023

Choose a reason for hiding this comment

henrikbrixandersen Apr 19, 2023

Choose a reason for hiding this comment

henrikbrixandersen Apr 19, 2023

Choose a reason for hiding this comment

henrikbrixandersen Apr 19, 2023

Choose a reason for hiding this comment

bjarki-andreasen commented Apr 5, 2023 •

edited

Loading