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

On Thu, Jul 10, 2025 at 11:06:45AM +0200, Peter Hilber wrote:
> This iteration of the spec fixes merge conflicts with the recently merged
> virtio-media device and adds two missing entries in the Conformance
> section.
> 
> 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.
> 
> The driver-side timekeeping can synchronize precisely to a local clock
> exposed by the RTC device. If supported by the device, the driver can
> obtain a cross-timestamp from the local clock and the system hardware
> counter, in a way similar to the Linux kernel ptp_kvm driver [1].
> 
> The alarm allows the driver side to be woken up from a sleep state at a
> specific time.

Could you please open a voting ballot for these changes?

Fixes: https://github.com/oasis-tcs/virtio-spec/issues/221

Apparently no ballot has been opened for v9. I am now requesting one for
the v10 (with changes as mentioned at the top).

Best regards,

Peter

> 
> Changelog
> ---------
> 
> v10:
> 
> - Add RTC clauses to the "Conformance Targets" section.
> 
> - Fix merge conflicts with recently merged virtio-media device.
> 
> v9:
> 
> - Add motivation to cover letter (Michael S. Tsirkin).
> 
> - Allow more implementation-specific behavior when alarm actions become
>   obsolete (Matias Ezequiel Vara Larsen).
> 
> - Define how device should not change across resets (Michael S. Tsirkin).
> 
> - Document that device converts hardware counter value, accounting for
>   device/driver differences in offset/multiplier (Michael S. Tsirkin).
> 
> - Restrict implementation-specific id ranges to experimental
>   implementations (Michael S. Tsirkin).
> 
> - Mandate that only flags allowed by negotiated features may be accessed
>   (Michael S. Tsirkin).
> 
> - State that an error-free device sets status OK for all requests from a
>   well-behaved driver (Michael S. Tsirkin).
> 
> - Change name to "Real Time Clock" in device type list (Michael S.
>   Tsirkin).
> 
> - Remove unneeded requirement about what to put into device-readable
>   buffers (Matias Ezequiel Vara Larsen).
> 
> - Reword multiple sentences and requirements (Matias Ezequiel Vara Larsen,
>   Michael S. Tsirkin).
> 
> - Move fixes which were mistakenly placed in patch 2 in v8 (Cornelia Huck).
> 
> - Remove statement implying that device MUST NOT check that reserved fields
>   are zero.
> 
> 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://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=a0e136d436ded817c0aade72efdefa56a00b4e5e
> [2] https://lore.kernel.org/lkml/[email protected]/
> 
> 
> 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                         |   12 +-
>  content.tex                             |    3 +-
>  device-types/rtc/description.tex        | 1117 +++++++++++++++++++++++
>  device-types/rtc/device-conformance.tex |   13 +
>  device-types/rtc/driver-conformance.tex |   11 +
>  introduction.tex                        |    6 +
>  6 files changed, 1157 insertions(+), 5 deletions(-)
>  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: c5e5810cb6cb48b673bd3247eb48490d29b1e0fb
> -- 
> 2.43.0
>