Re: [PATCH v8 0/4] virtio-rtc: Add device specification

[Matias Ezequiel Vara Larsen <mvaralar@redhat.com>]

Hello Peter,

I only now had time to share my comments. I could not cover all the
patches though. These are minor changes. Apologies for the delay.

Matias

On Thu, Mar 06, 2025 at 10:51:08AM +0100, Peter Hilber wrote:
> This iteration of the spec should address multiple review findings from
> Matias Ezequiel Vara Larsen.
> 
> Summary
> -------
> 
> The RTC (Real Time Clock) device provides information about current
> time. The device can provide different clocks, for the UTC or TAI time
> standards, or for physical time elapsed since some past epoch. For UTC
> clocks, the device can also indicate how leap seconds are handled. The
> driver can read the clocks with simple or more accurate methods.
> Optionally, the driver can set an alarm.
> 
> Changelog
> ---------
> 
> v8:
> 
> - Explicitly describe alarm enabled status, where relevant (Matias Ezequiel
>   Vara Larsen).
> 
> - Reword multiple sentences and requirements (Matias Ezequiel Vara Larsen).
> 
> - Drop unnecessary or redundant requirements (Matias Ezequiel Vara Larsen).
> 
> - Change word order from "field X" to "the X field" (Matias Ezequiel Vara
>   Larsen).
> 
> - Change word order from "flag X" to "the X flag" or "X".
> 
> - Move requirements to serve alarm expiration events before requirements
>   about stopping to serve (Matias Ezequiel Vara Larsen).
> 
> v7:
> 
> - Remove leap second and performance indications from struct
>   virtio_rtc_resp_read_cross. Remove backing definitions.
> 
> - Move wording change which was mistakenly placed in last patch to first
>   patch.
> 
> v6:
> 
> - Make leap second status information optional if the clock smears (or
>   might smear) leap seconds.
> 
> - Do not use union for leap second indication.
> 
> - Improve wording.
> 
> - Refer to the new POSIX.1-2024 for UTC epoch definition.
> 
> v5:
> 
> - Change structure and wording to support adding shared memory like
>   vmclock [2].
> 
> - Add dedicated clock types for UTC leap second smearing (David
>   Woodhouse).
> 
> - Extend leap second indications.
> 
> - Replace VIRTIO_RTC_SUBTYPE_ by VIRTIO_RTC_SMEAR_.
> 
> - For Arm Generic Timer, only support Virtual Count Register (David
>   Woodhouse).
> 
> - Rename MONO clock to MONOTONIC clock.
> 
> - Harmonize bit widths with vmclock [2].
> 
> - Change formatting.
> 
> v4:
> 
> - Distinguish UTC clocks with and without leap smearing (David
>   Woodhouse).
> 
> - Add UTC leap second and TAI offset indication (David Woodhouse).
> 
> - Add clock performance information (David Woodhouse).
> 
> - Drop distinction of Arm Generic Timer virtual and physical counter.
> 
> - Change requirements so that driver can reset alarm to clean slate, and
>   document how driver can achieve this (Cornelia Hell, Jason Wang).
> 
> - Device should assume that driver reads clock from first vCPU (David
>   Woodhouse).
> 
> - Driver should read clock to confirm that alarm has expired.
> 
> - Require driver to set unused flags to zero.
> 
> - Require device to support all expressible alarm times.
> 
> - Formatting and wording improvements.
> 
> v3:
> 
> - Address comments from Parav Pandit.
> 
> - Add an optional alarm feature.
> 
> - Various other changes.
> 
> v2:
> 
> - Address comments from Cornelia Huck.
> 
> [1] https://lore.kernel.org/lkml/61364452-bdf5-4bd8-adb1-a9e6236c9d26@opensynergy.com/
> [2] https://lore.kernel.org/lkml/20240708092924.1473461-1-dwmw2@infradead.org/
> [3] https://lore.kernel.org/all/78969a39b51ec00e85551b752767be65f6794b46.camel@infradead.org/
> [4] https://lore.kernel.org/lkml/20241219204208.3160-1-quic_philber@quicinc.com/
> 
> 
> Peter Hilber (4):
>   virtio-rtc: Add initial device specification
>   virtio-rtc: Add initial normative statements
>   virtio-rtc: Add alarm feature
>   virtio-rtc: Add normative statements for alarm feature
> 
>  conformance.tex                         |    2 +
>  content.tex                             |    3 +-
>  device-types/rtc/description.tex        | 1100 +++++++++++++++++++++++
>  device-types/rtc/device-conformance.tex |   13 +
>  device-types/rtc/driver-conformance.tex |   11 +
>  introduction.tex                        |    6 +
>  6 files changed, 1134 insertions(+), 1 deletion(-)
>  create mode 100644 device-types/rtc/description.tex
>  create mode 100644 device-types/rtc/device-conformance.tex
>  create mode 100644 device-types/rtc/driver-conformance.tex
> 
> 
> base-commit: 124fcd0e97f209aab19639e7369116d99ede22a2
> -- 
> 2.43.0
>