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

@parav I think this has been voted on. Should it be merged in 1.4?

Matias

On Thu, Jul 10, 2025 at 11:16 AM Peter Hilber <[email protected]> wrote:
>
> 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
> >
>