diff --git a/boards/posix/native_posix/native_posix.yaml b/boards/posix/native_posix/native_posix.yaml index 063cf78feb97..b74534f1eca0 100644 --- a/boards/posix/native_posix/native_posix.yaml +++ b/boards/posix/native_posix/native_posix.yaml @@ -17,5 +17,6 @@ supported: - i2c - spi - gpio + - rtc testing: default: true diff --git a/boards/posix/native_posix/native_posix_64.yaml b/boards/posix/native_posix/native_posix_64.yaml index 0a112c71e6ea..b503ff2241b6 100644 --- a/boards/posix/native_posix/native_posix_64.yaml +++ b/boards/posix/native_posix/native_posix_64.yaml @@ -15,3 +15,4 @@ supported: - usb_device - adc - gpio + - rtc diff --git a/doc/hardware/peripherals/rtc.rst b/doc/hardware/peripherals/rtc.rst index e6cd52c19f5b..c279c7c79131 100644 --- a/doc/hardware/peripherals/rtc.rst +++ b/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 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 -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. diff --git a/doc/releases/release-notes-3.4.rst b/doc/releases/release-notes-3.4.rst index b404c68cdfbb..1cfd9243a797 100644 --- a/doc/releases/release-notes-3.4.rst +++ b/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 ****** diff --git a/dts/bindings/rtc/rtc-device.yaml b/dts/bindings/rtc/rtc-device.yaml index 07f12aacaab9..cb231a8795b5 100644 --- a/dts/bindings/rtc/rtc-device.yaml +++ b/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. diff --git a/include/zephyr/drivers/rtc.h b/include/zephyr/drivers/rtc.h index 48da6170dab8..3cd704c7c89d 100644 --- a/include/zephyr/drivers/rtc.h +++ b/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 * @{ */ diff --git a/tests/drivers/rtc/rtc_api_helpers/testcase.yaml b/tests/drivers/rtc/rtc_api_helpers/testcase.yaml index 2224276c98d0..5848e28b4d6b 100644 --- a/tests/drivers/rtc/rtc_api_helpers/testcase.yaml +++ b/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