[PATCH v10 0/4] virtio-rtc: Add device specification
Peter Hilber <[email protected]>
| Newsgroups | dev.linux.lists.virtio-comment |
|---|---|
| Message-ID | <[email protected]> |
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. 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