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

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

[Peter Hilber]

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

[PATCH v8 1/4] virtio-rtc: Add initial device specification

[Peter Hilber]

The virtio-rtc device provides information about current time through
one or more clocks. As such, it is a Real-Time Clock (RTC) device.

The normative statements for this device follow in the next patch.

For this device, there is an RFC Linux kernel driver which is being
upstreamed, and a proprietary device implementation.

Miscellaneous
-------------

The spec does not specify how a driver should interpret clock readings,
esp. also not how to perform clock synchronization.

The device uses the "Timer/Clock" device id which is already part of the
specification. This device id was registered a long time ago and should
be unused according to the author's information. The name "RTC" was
determined to be the best for a device which focuses on current time.

Signed-off-by: Peter Hilber <quic_philber@quicinc.com>
---

Notes:
    v8:
    
    - Change word order from "field X" to "the X field" (Matias Ezequiel
      Vara Larsen).
    
    - Split up sentences about implementation-specific definitions (Matias
      Ezequiel Vara Larsen).
    
    v7:
    
    - Remove leap second and performance indications from struct
      virtio_rtc_resp_read_cross. Remove backing definitions.
    
    - Add wording change which was previously mistakenly placed in last
      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 [8].
    
    - Add dedicated clock types for UTC leap second smearing (David
      Woodhouse).
    
    - Extend leap second indications.
    
    - Split UTC-TAI offset and fractional offset due to smearing (David
      Woodhouse).
    
    - Remove requirement that TAI offset must not be a whole second while
      clock is being smeared.
    
    - Align bit widths, and some names, with '[RFC PATCH v4] ptp: Add
      vDSO-style vmclock support' [8].
    
    - 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.
    
    v4:
    
    - Drop distinction of Arm Generic Timer virtual and physical counter [7].
    
    - Add requirement that device should assume that driver reads clock from
      first vCPU (David Woodhouse) [6].
    
    - Formatting and wording improvements.
    
    v3:
    
    - Address comments from Parav Pandit.
    
    - Split off normative requirements into a second commit [2].
    
    - Merge readq and controlq into requestq [3].
    
    - Don't guard cross-timestamping with feature bit [3].
    
    - Pad request headers to 64 bit [2].
    
    - Rename Virtio status codes to match UNIX error names [2].
    
    - Avoid Virtio status code clashes with net controlq ack values.
    
    - Reword to refer more to "requests", rather than "messages" [2].
    
    - Rephrase some sentences [2].
    
    - Use integer data types without "__" prefixes [2].
    
    - Reduce clock id width to 16 bits [5].
    
    - Make VIRTIO_RTC_FLAG_CROSS_CAP a bit mask rather than a bit index.
    
    v2:
    
    - Address comments from Cornelia Huck.
    
    - Add VIRTIO_RTC_M_CROSS_CAP message [1].
    
    - Fix various minor issues and improve wording [1].
    
    - Add several clarifications regarding device error statuses.
    
    [1] https://lists.oasis-open.org/archives/virtio-comment/202304/msg00523.html
    [2] https://lore.kernel.org/virtio-comment/b59a7dda-06fe-cff9-df61-b90aa4e50836@opensynergy.com/t/#mffb93800fea11d6dda9e151078abedd6ff1c0f1e
    [3] https://lore.kernel.org/virtio-comment/b59a7dda-06fe-cff9-df61-b90aa4e50836@opensynergy.com/t/#m94efd0aa9b9c2b96a246b79ef8bfc3bf64ebe791
    [4] https://lore.kernel.org/lkml/20230630171052.985577-1-peter.hilber@opensynergy.com/T/#m65fa1d715933360498c4e33d7225e4220215a9d6
    [5] https://lore.kernel.org/virtio-comment/b59a7dda-06fe-cff9-df61-b90aa4e50836@opensynergy.com/t/#mf00ce330228c28556d735eb9597469048c5d8b62
    [6] https://lore.kernel.org/lkml/d796d9a5-8eda-4528-a6d8-1c4eba24aa1e@opensynergy.com/
    [7] https://lore.kernel.org/all/20231218064253.9734-2-peter.hilber@opensynergy.com/
    [8] https://lore.kernel.org/lkml/20240708092924.1473461-1-dwmw2@infradead.org/

 content.tex                      |   3 +-
 device-types/rtc/description.tex | 428 +++++++++++++++++++++++++++++++
 introduction.tex                 |   6 +
 3 files changed, 436 insertions(+), 1 deletion(-)
 create mode 100644 device-types/rtc/description.tex

diff --git a/content.tex b/content.tex
index 67b1bf3c35ab..b1d93a8aebb4 100644
--- a/content.tex
+++ b/content.tex
@@ -684,7 +684,7 @@ \chapter{Device Types}\label{sec:Device Types}
 \hline
 16         &   GPU device       \\
 \hline
-17         &   Timer/Clock device \\
+17         &   RTC (Timer/Clock) device \\
 \hline
 18         &   Input device \\
 \hline
@@ -776,6 +776,7 @@ \chapter{Device Types}\label{sec:Device Types}
 \input{device-types/pmem/description.tex}
 \input{device-types/can/description.tex}
 \input{device-types/spi/description.tex}
+\input{device-types/rtc/description.tex}
 
 \chapter{Reserved Feature Bits}\label{sec:Reserved Feature Bits}
 
diff --git a/device-types/rtc/description.tex b/device-types/rtc/description.tex
new file mode 100644
index 000000000000..5d8cf91a6991
--- /dev/null
+++ b/device-types/rtc/description.tex
@@ -0,0 +1,428 @@
+\section{RTC Device}\label{sec:Device Types / RTC Device}
+
+The RTC (Real Time Clock) device provides information about current
+time. The device can provide different clocks, e.g.\ for the UTC or TAI
+time standards, or for physical time elapsed since some past epoch. The
+driver can read the clocks with simple or more accurate methods.
+
+\subsection{Device ID}\label{sec:Device Types / RTC Device / Device ID}
+
+17
+
+\subsection{Virtqueues}\label{sec:Device Types / RTC Device / Virtqueues}
+
+\begin{description}
+\item[0] requestq
+\end{description}
+
+The driver enqueues requests to the requestq.
+
+\subsection{Feature bits}\label{sec:Device Types / RTC Device / Feature bits}
+
+No device-specific feature bits are defined yet.
+
+\subsection{Device configuration layout}\label{sec:Device Types / RTC Device / Device configuration layout}
+
+There is no configuration data for the device.
+
+\subsection{Device Initialization}\label{sec:Device Types / RTC Device / Device Initialization}
+
+The device determines the set of clocks. The device can provide zero or
+more clocks.
+
+\subsection{Device Operation}\label{sec:Device Types / RTC Device / Device Operation}
+
+For the requestq, the driver sends a message with a request, and
+receives the response in the device-writable part of the message. The
+requestq uses common request and response headers.
+
+\begin{lstlisting}
+/* common request header */
+struct virtio_rtc_req_head {
+        le16 msg_type;
+        u8 reserved[6];
+};
+
+/* common response header */
+struct virtio_rtc_resp_head {
+        u8 status;
+        u8 reserved[7];
+};
+\end{lstlisting}
+
+The \field{msg_type} field identifies the message type.
+
+The \field{status} field indicates whether the device successfully
+executed the request. The device sets the \field{status} field to one of
+the following values:
+
+\begin{lstlisting}
+#define VIRTIO_RTC_S_OK         0
+#define VIRTIO_RTC_S_EOPNOTSUPP 2
+#define VIRTIO_RTC_S_ENODEV     3
+#define VIRTIO_RTC_S_EINVAL     4
+#define VIRTIO_RTC_S_EIO        5
+\end{lstlisting}
+
+VIRTIO_RTC_S_OK indicates that the device successfully executed the
+request.
+
+If \field{status} is not VIRTIO_RTC_S_OK, the value of other response
+fields is undefined.
+
+VIRTIO_RTC_S_EOPNOTSUPP indicates that the device could not execute the
+specific request due to an implementation limitation. The device also
+returns status VIRTIO_RTC_S_EOPNOTSUPP for requests with unknown values
+in the fields \field{msg_type} or \field{hw_counter}.
+
+VIRTIO_RTC_S_ENODEV indicates that the \field{clock_id} field value
+supplied with the request does not identify a clock.
+
+VIRTIO_RTC_S_EINVAL indicates that
+
+\begin{itemize}
+\item the driver request values are not allowed by the specification or
+\item the device read-only part of the message, or the device write-only
+        part of the message, is too small to fit the actual message.
+\end{itemize}
+
+VIRTIO_RTC_S_EIO indicates that the device did not execute the request
+due to an error which was not caused by invalid input from the driver.
+
+All \field{reserved} fields are written as zero, and their value is
+ignored.
+
+The set of clocks does not change after feature negotiation completion,
+until device reset. The set of clocks should not change on device reset
+either (similar to negotiated features). Clock identifiers are
+zero-based, dense indices. All fields named \field{clock_id} contain
+clock identifiers.
+
+\subsubsection{Common Definitions}\label{sec:Device Types / RTC Device / Device Operation / Common Definitions}
+
+This section makes common definitions.
+
+\paragraph{Clock Types}\label{sec:Device Types / RTC Device / Device Operation / Common Definitions / Clock Types}
+
+The following clock types are defined:
+
+\begin{lstlisting}
+#define VIRTIO_RTC_CLOCK_UTC                    0
+#define VIRTIO_RTC_CLOCK_TAI                    1
+#define VIRTIO_RTC_CLOCK_MONOTONIC              2
+#define VIRTIO_RTC_CLOCK_UTC_SMEARED            3
+#define VIRTIO_RTC_CLOCK_UTC_MAYBE_SMEARED      4
+\end{lstlisting}
+
+\begin{description}
+
+\item[VIRTIO_RTC_CLOCK_UTC] uses the UTC (Coordinated Universal Time)
+        time standard. This clock uses the time epoch of January 1,
+        1970, 00:00 UTC. This is the same epoch as \emph{Unix time}. The
+        clock's seconds since the epoch are related to UTC time as
+        defined by \hyperref[intro:EPOCH]{EPOCH}.
+
+        This clock observes positive and negative leap seconds as
+        announced by standard bodies. At the start of leap seconds, the
+        clock steps accordingly.
+
+\item[VIRTIO_RTC_CLOCK_TAI] uses the TAI (International Atomic Time)
+        time standard. This clock uses the time epoch of January 1,
+        1970, 00:00 TAI.
+
+\item[VIRTIO_RTC_CLOCK_MONOTONIC] uses monotonic physical time (SI
+        seconds subdivisions) since some unspecified epoch. The epoch is
+        before or during device reset.
+
+\item[VIRTIO_RTC_CLOCK_UTC_SMEARED] deviates from the UTC standard by
+        smearing time in the vicinity of a leap second. This avoids
+        clock steps due to UTC leap seconds. Otherwise, this clock is
+        similar to VIRTIO_RTC_CLOCK_UTC.
+
+\item[VIRTIO_RTC_CLOCK_UTC_MAYBE_SMEARED] This clock
+
+\begin{itemize}
+\item may deviate from the UTC standard by smearing time in the vicinity
+        of a leap second (similar to VIRTIO_RTC_CLOCK_UTC_SMEARED), or
+
+\item may step at the start of leap seconds like VIRTIO_RTC_CLOCK_UTC.
+\end{itemize}
+
+A clock of type VIRTIO_RTC_CLOCK_UTC_MAYBE_SMEARED can change this
+behavior for every leap second.
+
+\end{description}
+
+In the following, \emph{UTC-like clock} designates any clock of type
+VIRTIO_RTC_CLOCK_UTC, VIRTIO_RTC_CLOCK_UTC_SMEARED, or
+VIRTIO_RTC_CLOCK_UTC_MAYBE_SMEARED.
+
+Additional clock types may be standardized in the future.
+Implementation-specific definitions of clock types are not recommended.
+Implementation-specific definitions use ids between 0xF0 and 0xFF.
+
+\paragraph{Smearing Variants}\label{sec:Device Types / RTC Device / Device Operation / Common Definitions / Smearing Variants}
+
+Leap second \emph{smearing variants} describe the deviation from the UTC
+standard in the vicinity of a leap second. The following smearing
+variants are currently defined:
+
+\begin{lstlisting}
+#define VIRTIO_RTC_SMEAR_UNSPECIFIED    0
+#define VIRTIO_RTC_SMEAR_NOON_LINEAR    1
+#define VIRTIO_RTC_SMEAR_UTC_SLS        2
+\end{lstlisting}
+
+\begin{description}
+
+        \item[VIRTIO_RTC_SMEAR_UNSPECIFIED] means that it is unspecified
+                how time is smeared in the vicinity of leap seconds.
+
+        \item[VIRTIO_RTC_SMEAR_NOON_LINEAR] specifies a linear smear
+                from noon prior to the leap second until noon after the
+                leap second.
+
+        \item[VIRTIO_RTC_SMEAR_UTC_SLS] specifies a linear smear as per
+                the \hyperref[intro:UTC-SLS]{UTC-SLS} proposal.
+
+\end{description}
+
+Clocks of type VIRTIO_RTC_CLOCK_UTC_SMEARED always behave according to a
+smearing variant. The smearing variant does not change over the clock's
+lifetime.
+
+For clocks of type VIRTIO_RTC_CLOCK_UTC_MAYBE_SMEARED, it is unspecified
+whether leap seconds are smeared, and how leap seconds are smeared.
+
+Additional smearing variants may be standardized in the future.
+Implementation-specific definitions of smearing variants are not
+recommended. Implementation-specific definitions use ids greater than or
+equal to 0xF0.
+
+In the following, \emph{leap smearing clock} designates
+
+\begin{itemize}
+
+\item any clock of type VIRTIO_RTC_CLOCK_UTC_SMEARED
+
+\item any clock of type VIRTIO_RTC_CLOCK_UTC_MAYBE_SMEARED at any time
+        when the clock is smearing a leap second.
+
+\end{itemize}
+
+\paragraph{Hardware Counters}\label{sec:Device Types / RTC Device / Device Operation / Common Definitions / Hardware Counters}
+
+The following hardware counter identifiers are specified:
+
+\begin{lstlisting}
+/* Arm Generic Timer Counter-timer Virtual Count Register (CNTVCT_EL0) */
+#define VIRTIO_RTC_COUNTER_ARM_VCT      0
+/* x86 Time-Stamp Counter */
+#define VIRTIO_RTC_COUNTER_X86_TSC      1
+/* Invalid */
+#define VIRTIO_RTC_COUNTER_INVALID   0xFF
+\end{lstlisting}
+
+Additional hardware counter identifiers may be standardized in the
+future. Implementation-specific hardware counter identifiers are not
+recommended. Implementation-specific hardware counter identifiers have
+values between 0xF0 and 0xFE.
+
+\subsubsection{Control Requests}\label{sec:Device Types / RTC Device / Device Operation / Control Requests}
+
+Through \emph{control requests}, the driver requests information about
+the device capabilities. The driver enqueues control requests in the
+requestq.
+
+\begin{description}
+
+\item[VIRTIO_RTC_REQ_CFG] discovers the number of clocks.
+
+\begin{lstlisting}
+#define VIRTIO_RTC_REQ_CFG 0x1000 /* message type */
+
+struct virtio_rtc_req_cfg {
+        struct virtio_rtc_req_head head;
+        /* no request params */
+};
+
+struct virtio_rtc_resp_cfg {
+        struct virtio_rtc_resp_head head;
+        le16 num_clocks;
+        u8 reserved[6];
+};
+\end{lstlisting}
+
+Field \field{num_clocks} contains the number of clocks. A device
+provides zero or more clocks. Valid clock ids are those smaller than
+\field{num_clocks}.
+
+\item[VIRTIO_RTC_REQ_CLOCK_CAP] discovers the capabilities of the clock
+identified by the \field{clock_id} field.
+
+\begin{lstlisting}
+#define VIRTIO_RTC_REQ_CLOCK_CAP 0x1001 /* message type */
+
+struct virtio_rtc_req_clock_cap {
+        struct virtio_rtc_req_head head;
+        le16 clock_id;
+        u8 reserved[6];
+};
+
+struct virtio_rtc_resp_clock_cap {
+        struct virtio_rtc_resp_head head;
+        u8 type;
+        u8 leap_second_smearing;
+        u8 reserved[6];
+};
+\end{lstlisting}
+
+The \field{type} field identifies the clock type. A device provides
+zero or more clocks for a clock type.
+
+Clocks of type VIRTIO_RTC_CLOCK_UTC_SMEARED indicate the \emph{smearing
+variant} through field \field{leap_second_smearing}. All other clocks
+set \field{leap_second_smearing} to VIRTIO_RTC_SMEAR_UNSPECIFIED.
+
+\item[VIRTIO_RTC_REQ_CROSS_CAP] discovers whether the device supports
+cross-timestamping for a particular pair of clock and hardware counter.
+
+\begin{lstlisting}
+#define VIRTIO_RTC_REQ_CROSS_CAP 0x1002 /* message type */
+
+struct virtio_rtc_req_cross_cap {
+        struct virtio_rtc_req_head head;
+        le16 clock_id;
+        u8 hw_counter;
+        u8 reserved[5];
+};
+
+
+struct virtio_rtc_resp_cross_cap {
+        struct virtio_rtc_resp_head head;
+#define VIRTIO_RTC_FLAG_CROSS_CAP       (1 << 0)
+        u8 flags;
+        u8 reserved[7];
+};
+\end{lstlisting}
+
+The \field{clock_id} field identifies the clock, and the
+\field{hw_counter} field identifies the hardware counter, for which
+cross-timestamp support is probed. The device sets the
+VIRTIO_RTC_FLAG_CROSS_CAP flag in the \field{flags} field if the clock
+supports cross-timestamping for the particular clock and hardware
+counter, and clears the flag otherwise.
+
+\end{description}
+
+\subsubsection{Read Requests}\label{sec:Device Types / RTC Device / Device Operation / Read Requests}
+
+Through \emph{read requests}, the driver requests clock readings from
+the device. The driver enqueues read requests in the requestq. The
+device obtains device-side clock readings and forwards these clock
+readings to the driver. The driver may enhance and interpret the clock
+readings through methods which are beyond the scope of this
+specification.
+
+Once DRIVER_OK has been set, the device should support reading every
+clock, even when a clock may yet have to be aligned to reference time
+sources.
+
+In general,
+
+\begin{itemize}
+\item clocks may jump backwards or forward, and
+\item the clock frequency may change. Clocks may be \emph{slewed},
+        i.e.\ clocks may run at a frequency other than their current
+        best frequency estimate.
+\end{itemize}
+
+As long as a clock does not jump backwards, the driver clock readings
+through read request responses increase monotonically:
+
+\begin{itemize}
+\item As long as a clock does not jump backwards in-between device-side
+        clock readings, the driver-side readings for that clock increase
+        monotonically as well, in the order in which the driver
+        marks read requests as available.
+
+\item The device marks read requests for the same clock as used in
+        the order in which the messages were marked as available.
+\end{itemize}
+
+For a clock of type VIRTIO_RTC_CLOCK_MONOTONIC, the device always returns
+monotonically increasing clock readings through read request responses.
+
+The unit of all \field{clock_reading} fields is 1
+nanosecond.\footnote{For time epochs in year 1970 or later, this means
+that time until at least year 2553 can be represented in the \field{le64
+clock_reading} fields.}
+
+\begin{description}
+
+\item[VIRTIO_RTC_REQ_READ] reads the clock identified by the
+\field{clock_id} field. The device supports this message for every
+clock.
+
+\begin{lstlisting}
+#define VIRTIO_RTC_REQ_READ 0x0001 /* message type */
+
+struct virtio_rtc_req_read {
+        struct virtio_rtc_req_head head;
+        le16 clock_id;
+        u8 reserved[6];
+};
+
+struct virtio_rtc_resp_read {
+        struct virtio_rtc_resp_head head;
+        le64 clock_reading;
+};
+\end{lstlisting}
+
+\field{clock_reading} is a device-side clock reading obtained after the
+message was marked as available.
+
+\item[VIRTIO_RTC_REQ_READ_CROSS] returns a cross-timestamp for the clock
+identified by the \field{clock_id} field.\footnote{Cross-timestamping
+is similar to the ptp_kvm mechanism in the Linux kernel.} This message
+may yield better performance than using VIRTIO_RTC_REQ_READ.
+
+The driver can determine whether the device supports
+VIRTIO_RTC_REQ_READ_CROSS for a specific clock and \field{hw_counter}
+through VIRTIO_RTC_REQ_CROSS_CAP.
+
+\begin{lstlisting}
+#define VIRTIO_RTC_REQ_READ_CROSS 0x0002 /* message type */
+
+struct virtio_rtc_req_read_cross {
+        struct virtio_rtc_req_head head;
+        le16 clock_id;
+        u8 hw_counter;
+        u8 reserved[5];
+};
+
+struct virtio_rtc_resp_read_cross {
+        struct virtio_rtc_resp_head head;
+        le64 clock_reading;
+        le64 counter_cycles;
+};
+\end{lstlisting}
+
+The \field{hw_counter} field specifies the hardware counter for which
+the driver requests a cross-timestamp.
+
+Cross-timestamping returns a \field{clock_reading}, and an associated
+hardware counter value, \field{counter_cycles}. The
+\field{counter_cycles} field is the approximate or precise value which
+the driver would have read at the \field{clock_reading} time instant
+from the hardware counter identified by \field{hw_counter}. How the
+device determines the value which the driver would have seen is beyond
+the scope of this specification. In case hardware counter reads differ
+among CPUs used by the driver, the device should assume that the driver
+reads the hardware counter from the CPU which the driver enumerates as
+the first.
+
+The hardware counter identifiers are defined in
+\ref{sec:Device Types / RTC Device / Device Operation / Common Definitions / Hardware Counters}.
+
+\end{description}
diff --git a/introduction.tex b/introduction.tex
index e60298a4d78b..34f9485bc393 100644
--- a/introduction.tex
+++ b/introduction.tex
@@ -168,6 +168,12 @@ \section{Normative References}\label{sec:Normative References}
     Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP
     14, RFC 8174, DOI 10.17487/RFC8174, May 2017
         \newline\url{http://www.ietf.org/rfc/rfc8174.txt}\\
+	\phantomsection\label{intro:EPOCH}\textbf{[EPOCH]} &
+    POSIX.1-2024, Base Definitions, Seconds Since the Epoch
+	\newline\url{https://pubs.opengroup.org/onlinepubs/9799919799/basedefs/V1_chap04.html#tag_04_19}\\
+	\phantomsection\label{intro:UTC-SLS}\textbf{[UTC-SLS]} &
+    UTC with Smoothed Leap Seconds (UTC-SLS)
+	\newline\url{https://www.cl.cam.ac.uk/~mgk25/time/utc-sls/}\\
 \end{longtable}
 
 \section{Non-Normative References}
-- 
2.43.0

[PATCH v8 2/4] virtio-rtc: Add initial normative statements

[Peter Hilber]

Add the normative statements for the initial device specification.

Signed-off-by: Peter Hilber <quic_philber@quicinc.com>
---

Notes:
    v8:
    
    - Drop requirement to ignore reserved fields in the device-readable part
      of the message (Matias Ezequiel Vara Larsen).
    
    - Drop requirement about returning same status in response to identical
      requests (Matias Ezequiel Vara Larsen).
    
    - Reword requirements about size mismatches for device
      read-only/write-only parts of the message (Matias Ezequiel Vara
      Larsen).
    
    - Change word order from "field X" to "the X field" (Matias Ezequiel
      Vara Larsen).
    
    v7:
    
    - Remove obsolete requirements for leap second indication.
    
    v6:
    
    - Update requirements to make leap second status information optional if
      if the clock smears (or might smear) leap seconds.
    
    - Allow indicating VIRTIO_RTC_SMEAR_UNSPECIFIED for
      VIRTIO_RTC_CLOCK_SMEARED.
    
    - Shorten some requirements by omitting redundant information.
    
    v5:
    
    - Update normative statements to match v5 changes to non-normative
      statements (patch 1).
    
    v4:
    
    - Require driver to set unused flags to zero.
    
    - Update normative statements to match v4 changes to non-normative
      statements (patch 1).
    
    - Improve formatting.

 conformance.tex                         |   2 +
 device-types/rtc/description.tex        | 272 +++++++++++++++++++++++-
 device-types/rtc/device-conformance.tex |   9 +
 device-types/rtc/driver-conformance.tex |   9 +
 4 files changed, 288 insertions(+), 4 deletions(-)
 create mode 100644 device-types/rtc/device-conformance.tex
 create mode 100644 device-types/rtc/driver-conformance.tex

diff --git a/conformance.tex b/conformance.tex
index d92a2369488e..4ce86a525e84 100644
--- a/conformance.tex
+++ b/conformance.tex
@@ -162,6 +162,7 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets}
 \input{device-types/pmem/driver-conformance.tex}
 \input{device-types/can/driver-conformance.tex}
 \input{device-types/spi/driver-conformance.tex}
+\input{device-types/rtc/driver-conformance.tex}
 
 \conformance{\section}{Device Conformance}\label{sec:Conformance / Device Conformance}
 
@@ -254,6 +255,7 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets}
 \input{device-types/pmem/device-conformance.tex}
 \input{device-types/can/device-conformance.tex}
 \input{device-types/spi/device-conformance.tex}
+\input{device-types/rtc/device-conformance.tex}
 
 \conformance{\section}{Legacy Interface: Transitional Device and Transitional Driver Conformance}\label{sec:Conformance / Legacy Interface: Transitional Device and Transitional Driver Conformance}
 A conformant implementation MUST be either transitional or
diff --git a/device-types/rtc/description.tex b/device-types/rtc/description.tex
index 5d8cf91a6991..f2a3907de511 100644
--- a/device-types/rtc/description.tex
+++ b/device-types/rtc/description.tex
@@ -73,7 +73,7 @@ \subsection{Device Operation}\label{sec:Device Types / RTC Device / Device Opera
 VIRTIO_RTC_S_EOPNOTSUPP indicates that the device could not execute the
 specific request due to an implementation limitation. The device also
 returns status VIRTIO_RTC_S_EOPNOTSUPP for requests with unknown values
-in the fields \field{msg_type} or \field{hw_counter}.
+in the \field{msg_type} or \field{hw_counter} fields.
 
 VIRTIO_RTC_S_ENODEV indicates that the \field{clock_id} field value
 supplied with the request does not identify a clock.
@@ -98,6 +98,106 @@ \subsection{Device Operation}\label{sec:Device Types / RTC Device / Device Opera
 zero-based, dense indices. All fields named \field{clock_id} contain
 clock identifiers.
 
+\drivernormative{\subsubsection}{Device Operation}{Device Types / RTC Device / Device Operation}
+
+If the \field{struct virtio_rtc_resp_head} field \field{status} is not
+VIRTIO_RTC_S_OK, the driver MUST NOT interpret response fields other
+than \field{status}.
+
+The driver MUST set \emph{reserved} fields in the device-readable part
+of the message to zero.
+
+The driver MUST set unnamed bits in \emph{flags} fields in the
+device-readable part of the message to zero.
+
+The driver MUST NOT interpret \emph{reserved} fields in the
+device-writable part of the message.
+
+The driver MUST NOT interpret unnamed bits in \emph{flags} fields in the
+device-writable part of the message.
+
+The driver MUST put the request into the device-readable part of the
+message.
+
+The driver MUST allocate enough space for the response in the
+device-writable part of a requestq message.
+
+\devicenormative{\subsubsection}{Device Operation}{Device Types / RTC Device / Device Operation}
+
+For \field{struct virtio_rtc_resp_head}, the device MUST set the
+\field{status} field to VIRTIO_RTC_S_OK if the device successfully
+executed the request.
+
+For \field{struct virtio_rtc_resp_head}, the device MUST set the
+\field{status} field to a status other than VIRTIO_RTC_S_OK if the
+device did not successfully execute the request.
+
+For \field{struct virtio_rtc_resp_head}, the device MUST set the
+\field{status} field to VIRTIO_RTC_S_EOPNOTSUPP if the device could not
+execute the specific request due to an implementation limitation.
+
+For \field{struct virtio_rtc_resp_head}, the device MUST set the
+\field{status} field to VIRTIO_RTC_S_EOPNOTSUPP for a request with a
+value of the \field{msg_type} field which is not described in this
+specification.
+
+For \field{struct virtio_rtc_resp_head}, the device MUST set the
+\field{status} field to VIRTIO_RTC_S_EOPNOTSUPP for a request with a
+value of the \field{hw_counter} field which is neither described in this
+specification nor otherwise known to the implementation.
+
+For \field{struct virtio_rtc_resp_head}, the device MUST set the
+\field{status} field to VIRTIO_RTC_S_ENODEV if the \field{clock_id}
+field value supplied with the request does not identify a clock.
+
+For \field{struct virtio_rtc_resp_head}, the device MUST set the
+\field{status} field to VIRTIO_RTC_S_EINVAL if the request values are
+inconsistent with the specification and if the inconsistence is not
+described by the requirements which stipulate status
+VIRTIO_RTC_S_EOPNOTSUPP or VIRTIO_RTC_S_ENODEV.
+
+For \field{struct virtio_rtc_resp_head}, the device MUST set the
+\field{status} field to VIRTIO_RTC_S_EINVAL if the request specified in
+the request header through the \field{msg_type} field does not fit into
+the device read-only part of the actual message.
+
+For \field{struct virtio_rtc_resp_head}, the device MUST set the
+\field{status} field to VIRTIO_RTC_S_EINVAL if the response specified in
+the request header through the \field{msg_type} field does not fit into
+the device write-only part of the actual message, unless the
+\field{status} field does not fit into the device write-only part.
+
+For \field{struct virtio_rtc_resp_head}, the device MUST NOT set the
+\field{status} field if the \field{status} field does not fit into the
+device write-only part.
+
+For \field{struct virtio_rtc_resp_head}, the device MUST set the
+\field{status} field to VIRTIO_RTC_S_EIO if none of the previous
+requirements in this document stipulated another \field{status}.
+
+If the device read-only part of a message M is bigger than the size of
+the request specified for message M, the device MUST ignore the
+additional space.
+
+If the device write-only part of a message M is bigger than the size of
+the response specified for message M, the device MUST ignore the
+additional space.
+
+The device MUST set \emph{reserved} fields in the device-writable part
+of the message to zero.
+
+The device MUST set unnamed bits in \emph{flags} fields in the
+device-writable part of the message to zero.
+
+After feature negotiation completion the device MUST NOT change the set
+of clocks until device reset.
+
+The device SHOULD NOT change the set of clocks on a device reset after
+the first device reset.
+
+The device MUST use non-negative integers, which are smaller than the
+number of clocks, as clock identifiers.
+
 \subsubsection{Common Definitions}\label{sec:Device Types / RTC Device / Device Operation / Common Definitions}
 
 This section makes common definitions.
@@ -253,7 +353,7 @@ \subsubsection{Control Requests}\label{sec:Device Types / RTC Device / Device Op
 };
 \end{lstlisting}
 
-Field \field{num_clocks} contains the number of clocks. A device
+The \field{num_clocks} field contains the number of clocks. A device
 provides zero or more clocks. Valid clock ids are those smaller than
 \field{num_clocks}.
 
@@ -281,8 +381,8 @@ \subsubsection{Control Requests}\label{sec:Device Types / RTC Device / Device Op
 zero or more clocks for a clock type.
 
 Clocks of type VIRTIO_RTC_CLOCK_UTC_SMEARED indicate the \emph{smearing
-variant} through field \field{leap_second_smearing}. All other clocks
-set \field{leap_second_smearing} to VIRTIO_RTC_SMEAR_UNSPECIFIED.
+variant} through the \field{leap_second_smearing} field. All other
+clocks set \field{leap_second_smearing} to VIRTIO_RTC_SMEAR_UNSPECIFIED.
 
 \item[VIRTIO_RTC_REQ_CROSS_CAP] discovers whether the device supports
 cross-timestamping for a particular pair of clock and hardware counter.
@@ -315,6 +415,103 @@ \subsubsection{Control Requests}\label{sec:Device Types / RTC Device / Device Op
 
 \end{description}
 
+\drivernormative{\paragraph}{Control Requests}{Device Types / RTC Device / Device Operation / Control Requests}
+
+For VIRTIO_RTC_REQ_CROSS_CAP, the driver MUST set \field{hw_counter} to
+one of the hardware counter identifiers defined in this specification,
+or to a value between 0xF0 and 0xFE.
+
+\devicenormative{\paragraph}{Control Requests}{Device Types / RTC Device / Device Operation / Control Requests}
+
+For any clock of type VIRTIO_RTC_CLOCK_UTC, the device MUST use the UTC
+time standard (Coordinated Universal Time).
+
+For any clock of type VIRTIO_RTC_CLOCK_UTC_SMEARED or
+VIRTIO_RTC_CLOCK_UTC_MAYBE_SMEARED, the device MUST use the UTC time
+standard, insofar as the following requirements do not say otherwise.
+
+For any UTC-like clock, the device MUST use the time epoch of January 1,
+1970, 00:00 UTC.
+
+For any UTC-like clock, the device MUST count seconds since the epoch
+according to \hyperref[intro:EPOCH]{EPOCH}.
+
+For any clock of type VIRTIO_RTC_CLOCK_UTC, the device MUST apply a
+positive leap second according to the UTC time standard by
+instantaneously stepping the clock backwards by 1 s at the start of the
+leap second.
+
+For any clock of type VIRTIO_RTC_CLOCK_UTC, the device MUST apply a
+negative leap second according to the UTC time standard by
+instantaneously stepping the clock forward by 1 s at the start of the
+leap second.
+
+For any leap smearing clock, the device MUST NOT step the clock due to a
+leap second.
+
+For any leap smearing clock, on a positive leap second, the device MUST
+slow down the clock during part of the day containing the leap second
+and/or part of the day after the leap second.
+
+For any leap smearing clock, on a negative leap second, the device MUST
+speed up the clock during part of the day containing the leap second
+and/or part of the day after the leap second.
+
+For any clock with smearing variant VIRTIO_RTC_SMEAR_NOON_LINEAR, on a
+leap second, the device MUST change the frequency of the clock exactly
+from noon prior to the leap second until noon after the leap second.
+
+For any clock with smearing variant VIRTIO_RTC_SMEAR_NOON_LINEAR, while
+changing the frequency of the clock due to a positive leap second, the
+device MUST decrease the frequency of the clock by $1/86400$.
+
+For any clock with smearing variant VIRTIO_RTC_SMEAR_NOON_LINEAR, while
+changing the frequency of the clock due to a negative leap second, the
+device MUST increase the frequency of the clock by $1/86400$.
+
+For any clock with smearing variant VIRTIO_RTC_SMEAR_UTC_SLS, on a leap
+second, the device MUST change the frequency of the clock exactly during
+the last 1000 seconds of the day with the leap second.
+
+For any clock with smearing variant VIRTIO_RTC_SMEAR_UTC_SLS, while
+changing the frequency of the clock due to a positive leap second, the
+device MUST decrease the frequency of the clock by 0.1\%.
+
+For any clock with smearing variant VIRTIO_RTC_SMEAR_UTC_SLS, while
+changing the frequency of the clock due to a negative leap second, the
+device MUST increase the frequency of the clock by 0.1\%.
+
+For any clock of type VIRTIO_RTC_CLOCK_UTC_MAYBE_SMEARED, the device MAY
+deviate from the UTC standard with respect to leap second introduction.
+
+For any clock of type VIRTIO_RTC_CLOCK_TAI, the device MUST use the TAI
+time standard (International Atomic Time).
+
+For any clock of type VIRTIO_RTC_CLOCK_TAI, the device MUST use the time
+epoch of January 1, 1970, 00:00 TAI.
+
+For any clock of type VIRTIO_RTC_CLOCK_MONOTONIC, the device MUST use SI
+seconds subdivisions.
+
+For any clock of type VIRTIO_RTC_CLOCK_MONOTONIC, the device MUST use an
+epoch at a time instant before or during device reset.
+
+For VIRTIO_RTC_REQ_CLOCK_CAP, and clock types other than
+VIRTIO_RTC_CLOCK_UTC_SMEARED, the device MUST set the
+\field{leap_second_smearing} field to VIRTIO_RTC_SMEAR_UNSPECIFIED.
+
+For VIRTIO_RTC_REQ_CLOCK_CAP, and clock type
+VIRTIO_RTC_CLOCK_UTC_SMEARED, the device MUST set the
+\field{leap_second_smearing} field to VIRTIO_RTC_SMEAR_UNSPECIFIED,
+VIRTIO_RTC_SMEAR_NOON_LINEAR, VIRTIO_RTC_SMEAR_UTC_SLS, or to a value
+greater than or equal to 0xF0.
+
+For a VIRTIO_RTC_REQ_CROSS_CAP message M, the device MUST set the
+VIRTIO_RTC_FLAG_CROSS_CAP flag in the \field{flags} field if the device
+would respond to a VIRTIO_RTC_REQ_READ_CROSS message with the same
+\field{hw_counter} and \field{clock_id} values as in M with status
+VIRTIO_RTC_S_OK, and clear the flag otherwise.
+
 \subsubsection{Read Requests}\label{sec:Device Types / RTC Device / Device Operation / Read Requests}
 
 Through \emph{read requests}, the driver requests clock readings from
@@ -426,3 +623,70 @@ \subsubsection{Read Requests}\label{sec:Device Types / RTC Device / Device Opera
 \ref{sec:Device Types / RTC Device / Device Operation / Common Definitions / Hardware Counters}.
 
 \end{description}
+
+\drivernormative{\paragraph}{Read Requests}{Device Types / RTC Device / Device Operation / Read Requests}
+
+For VIRTIO_RTC_REQ_READ_CROSS, the driver MUST set \field{hw_counter} to
+one of the hardware counter identifiers defined in this specification,
+or to a value between 0xF0 and 0xFE.
+
+\devicenormative{\paragraph}{Read Requests}{Device Types / RTC Device / Device Operation / Read Requests}
+
+The device SHOULD continuously support reading of all clocks once
+DRIVER_OK has been set.
+
+For any clock C and read requests \emph{A} and \emph{B} which read C,
+\emph{A} being the message which the driver marks as available before
+\emph{B}, the device MUST obtain the \field{clock_reading} value for the
+message \emph{A} response before the \field{clock_reading} value for the
+message \emph{B} response, or the device MUST obtain the same
+\field{clock_reading} value for both \emph{A} and \emph{B}.
+
+For any clock C, the device MUST mark all read requests reading C as
+used in the total order in which the driver marked these messages as
+available.
+
+For any clock C of type VIRTIO_RTC_CLOCK_MONOTONIC and read requests
+\emph{A} and \emph{B} which read C, \emph{A} being the message which the
+driver marks as available before \emph{B}, the device MUST set the
+\field{clock_reading} value for the message \emph{B} response to a value
+greater than or equal to the \field{clock_reading} value for the message
+\emph{A} response.
+
+The device MUST support VIRTIO_RTC_REQ_READ for every clock.
+
+For VIRTIO_RTC_REQ_READ and for any clock type listed in this
+specification, the device MUST use the nanosecond as unit for the
+\field{clock_reading} field.
+
+For read requests, the device MUST obtain the \field{clock_reading}
+response value after the read request is marked as available.
+
+For VIRTIO_RTC_REQ_READ_CROSS, the device MUST set
+\field{counter_cycles} to a value which approximates the value which the
+driver would have read from the hardware counter identified by
+\field{hw_counter} at the time instant when the device read the
+\field{clock_reading} value.
+
+For VIRTIO_RTC_REQ_READ_CROSS, the device SHOULD assume that the driver
+reads the hardware counter identified by \field{hw_counter} through the
+CPU which the driver enumerates as the first.
+
+For VIRTIO_RTC_REQ_READ_CROSS, the device MUST set \field{status} to a
+value other than VIRTIO_RTC_S_OK if the device cannot determine the
+approximate value which the driver would have read from the hardware
+counter identified by \field{hw_counter} at the time instant when the
+device read the \field{clock_reading} value.
+
+For any clock C, and VIRTIO_RTC_REQ_READ_CROSS messages \emph{A} and
+\emph{B} which read C and which specify the same hardware counter
+\emph{H} through the \field{hw_counter} field, \emph{A} being the
+message which the driver marks as available before \emph{B}, the device
+MUST set the \field{counter_cycles} value for \emph{B} to a value which
+\emph{H} shows after the \field{counter_cycles} value of \emph{A}, or
+the device MUST set the same \field{counter_cycles} value for \emph{A}
+and \emph{B}.
+
+For VIRTIO_RTC_REQ_READ_CROSS and for any clock type listed in this
+specification, the device MUST use the nanosecond as unit for the
+\field{clock_reading} field.
diff --git a/device-types/rtc/device-conformance.tex b/device-types/rtc/device-conformance.tex
new file mode 100644
index 000000000000..4303cd450542
--- /dev/null
+++ b/device-types/rtc/device-conformance.tex
@@ -0,0 +1,9 @@
+\conformance{\subsection}{RTC Device Conformance}\label{sec:Conformance / Device Conformance / RTC Device Conformance}
+
+An RTC device MUST conform to the following normative statements:
+
+\begin{itemize}
+\item \ref{devicenormative:Device Types / RTC Device / Device Operation}
+\item \ref{devicenormative:Device Types / RTC Device / Device Operation / Control Requests}
+\item \ref{devicenormative:Device Types / RTC Device / Device Operation / Read Requests}
+\end{itemize}
diff --git a/device-types/rtc/driver-conformance.tex b/device-types/rtc/driver-conformance.tex
new file mode 100644
index 000000000000..689c18d158d0
--- /dev/null
+++ b/device-types/rtc/driver-conformance.tex
@@ -0,0 +1,9 @@
+\conformance{\subsection}{RTC Driver Conformance}\label{sec:Conformance / Driver Conformance / RTC Driver Conformance}
+
+An RTC driver MUST conform to the following normative statements:
+
+\begin{itemize}
+\item \ref{drivernormative:Device Types / RTC Device / Device Operation}
+\item \ref{drivernormative:Device Types / RTC Device / Device Operation / Control Requests}
+\item \ref{drivernormative:Device Types / RTC Device / Device Operation / Read Requests}
+\end{itemize}
-- 
2.43.0

[PATCH v8 3/4] virtio-rtc: Add alarm feature

[Peter Hilber]

Add the VIRTIO_RTC_F_ALARM feature (without normative statements).

The intended use case is: A driver needs to react when an alarm time has
been reached, but at alarm time, the driver may be in a sleep state or
powered off. The alarm feature can resume and notify the driver in this
case. Alarms may be retained across device resets (including reset on
boot).

Peculiarities
-------------

Unlike usual alarm clocks, a virtio-rtc alarm-capable clock may step
autonomously at any time: An alarm may change back from "expired" to
"not expired" before the driver has started processing an alarm
notification.

To address the above, and the device resets, define "alarm expiration"
in such a way that the driver always has a chance to react to an alarm,
and make the device always responsible for notifying the driver about an
alarm expiration.

The VIRTIO_RTC_REQ_SET_ALARM_ENABLED request is there so that the Linux
ioctls RTC_AIE_ON and RTC_AIE_OFF only need to emit one request.

Signed-off-by: Peter Hilber <quic_philber@quicinc.com>
---

Notes:
    v8:
    
    - Explicitly describe alarm enabled status, where relevant (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".
    
    - Change "once" to "when" (Matias Ezequiel Vara Larsen).
    
    v7:
    
    - Change flag numeric value due to removing leap second indication.
    
    v5:
    
    - Reformat.
    
    v4:
    
    - Change requirements so that driver can reset alarm to clean slate, and
      document how driver can achieve this (Cornelia Hell, Jason Wang) [1].
    
    - Require device to support all expressible alarm times.
    
    - Formatting and wording improvements.
    
    [1] https://lore.kernel.org/all/2ae67401-a8f5-4686-9321-cb3105df594d@opensynergy.com/

 device-types/rtc/description.tex | 262 ++++++++++++++++++++++++++++++-
 1 file changed, 260 insertions(+), 2 deletions(-)

diff --git a/device-types/rtc/description.tex b/device-types/rtc/description.tex
index f2a3907de511..93bcf178b042 100644
--- a/device-types/rtc/description.tex
+++ b/device-types/rtc/description.tex
@@ -4,6 +4,7 @@ \section{RTC Device}\label{sec:Device Types / RTC Device}
 time. The device can provide different clocks, e.g.\ for the UTC or TAI
 time standards, or for physical time elapsed since some past epoch. The
 driver can read the clocks with simple or more accurate methods.
+Optionally, the driver can set an alarm.
 
 \subsection{Device ID}\label{sec:Device Types / RTC Device / Device ID}
 
@@ -13,13 +14,23 @@ \subsection{Virtqueues}\label{sec:Device Types / RTC Device / Virtqueues}
 
 \begin{description}
 \item[0] requestq
+\item[1] alarmq
 \end{description}
 
 The driver enqueues requests to the requestq.
 
+Through the alarmq, the device notifies the driver about alarm
+expirations. The alarmq exists only if VIRTIO_RTC_F_ALARM was
+negotiated.
+
 \subsection{Feature bits}\label{sec:Device Types / RTC Device / Feature bits}
 
-No device-specific feature bits are defined yet.
+\begin{description}
+\item[VIRTIO_RTC_F_ALARM (0)] Device supports alarm.
+\end{description}
+
+VIRTIO_RTC_F_ALARM determines whether the device supports setting an
+alarm for some of the clocks.
 
 \subsection{Device configuration layout}\label{sec:Device Types / RTC Device / Device configuration layout}
 
@@ -373,7 +384,8 @@ \subsubsection{Control Requests}\label{sec:Device Types / RTC Device / Device Op
         struct virtio_rtc_resp_head head;
         u8 type;
         u8 leap_second_smearing;
-        u8 reserved[6];
+        u8 flags;
+        u8 reserved[5];
 };
 \end{lstlisting}
 
@@ -384,6 +396,15 @@ \subsubsection{Control Requests}\label{sec:Device Types / RTC Device / Device Op
 variant} through the \field{leap_second_smearing} field. All other
 clocks set \field{leap_second_smearing} to VIRTIO_RTC_SMEAR_UNSPECIFIED.
 
+The \field{flags} field provides the following information:
+
+\begin{lstlisting}
+#define VIRTIO_RTC_FLAG_ALARM_CAP               (1 << 0)
+\end{lstlisting}
+
+If VIRTIO_RTC_F_ALARM was negotiated, the VIRTIO_RTC_FLAG_ALARM_CAP flag
+indicates that the clock supports an alarm.
+
 \item[VIRTIO_RTC_REQ_CROSS_CAP] discovers whether the device supports
 cross-timestamping for a particular pair of clock and hardware counter.
 
@@ -690,3 +711,240 @@ \subsubsection{Read Requests}\label{sec:Device Types / RTC Device / Device Opera
 For VIRTIO_RTC_REQ_READ_CROSS and for any clock type listed in this
 specification, the device MUST use the nanosecond as unit for the
 \field{clock_reading} field.
+
+\subsubsection{Alarm Operation}\label{sec:Device Types / RTC Device / Device Operation / Alarm Operation}
+
+Through the optional alarm feature, the driver can set an alarm time. On
+alarm expiration, the device notifies the driver. On alarm expiration,
+the device may also wake up the driver, while the driver is in a sleep
+state, or while the driver is powered off. How this is done is beyond
+the scope of the specification. The driver can set one alarm time per
+clock, if the clock supports this.
+
+The device may retain alarm times across device resets.\footnote{Drivers
+        may reset the device on boot or on resume from sleep state. It
+        can make sense for the device to retain the alarm time then,
+        similar to other alarm clocks.}
+
+The alarm feature, and the associated alarmq for notifications from the
+device, are available if VIRTIO_RTC_F_ALARM was negotiated. In addition,
+if the driver previously set an alarm time, even if the device no longer
+both
+
+\begin{itemize}
+\item is live and
+\item has negotiated VIRTIO_RTC_F_ALARM,
+\end{itemize}
+
+the device may still execute implementation-specific actions on alarm
+expiration.
+
+An alarm expires
+
+\begin{itemize}
+\item when the associated clock progresses (also: steps) from a time
+        prior to the alarm time to the alarm time, or to a time after
+        the alarm time, while the alarm is enabled, or
+
+\item when the driver sets an alarm time which is not in the future,
+        while also setting the alarm to enabled, or
+
+\item when the driver sets the alarm to enabled, and the alarm time is
+        not in the future, or
+
+\item when the device is reset, if the alarm time is retained and not in
+        the future, and if the alarm is enabled.\footnote{The device is
+                always responsible for detecting alarm expiration
+                events. This avoids that the driver needs to reason
+                about when it shall poll for alarm expiration.}
+\end{itemize}
+
+When an alarm expires, the driver can disable it. Otherwise, the alarm
+expires each time when one of the above expiration events occurs, even
+if it occurred before.\footnote{This avoids that the driver may
+        miss an alarm when the clock steps backwards after alarm
+        expiration, but before the driver has resumed operation. This
+        also facilitates distinct drivers using the same device,
+        e.g.\ a driver in the bootloader, and a driver in the OS.}
+
+On alarm expiration, the device executes the alarm actions. The alarm
+actions are:
+
+\begin{itemize}
+\item The device notifies the driver through the alarmq. If the device
+        is not live, or no buffers are available in the alarmq, the
+        device will notify once the device is live and buffers are
+        available.
+
+\item Optionally, the device executes other, implementation-specific,
+        actions. The device may execute those immediately, regardless of
+        the device state.
+\end{itemize}
+
+An alarm \emph{expiration} becomes obsolete
+
+\begin{itemize}
+\item when the driver disables the alarm, or
+
+\item when the driver sets an alarm time, or
+
+\item when the clock jumps backwards, before the alarm time, or
+
+\item when another alarm expiration event happens.
+\end{itemize}
+
+If an alarm expiration becomes obsolete, it is unspecified which alarm
+actions the device executes for this alarm expiration, and the device
+stops executing these alarm actions after a grace period.
+
+The device supports all alarm time values which the driver can request
+through alarm control requests.
+
+Initially, the alarm time is the epoch of the clock ($0$), and the alarm
+is disabled.
+
+Alarms set prior to reset may cause unwanted alarm expiration
+notifications, and information leakage, after the reset. To prevent both
+issues, the driver can do the following after the reset, for each clock
+which supports alarm:
+
+\begin{enumerate}
+\item Send a VIRTIO_RTC_REQ_SET_ALARM message, with \field{alarm_time}
+        set to 0, and \field{flags} set to 0.
+
+\item Wait until the device marks the VIRTIO_RTC_REQ_SET_ALARM message
+        as used, with status VIRTIO_RTC_S_OK.
+\end{enumerate}
+
+To prevent the above issues, the driver also marks buffers in the alarmq
+as available only after completing the above steps for all clocks.
+
+\paragraph{Alarm Control Requests}
+
+If VIRTIO_RTC_F_ALARM is negotiated,
+
+\begin{itemize}
+\item the driver can determine if a clock supports an alarm through the
+        VIRTIO_RTC_FLAG_ALARM_CAP flag in the VIRTIO_RTC_REQ_CLOCK_CAP
+        response,
+
+\item the driver can enqueue the alarm control requests into the
+        requestq: VIRTIO_RTC_REQ_READ_ALARM, VIRTIO_RTC_REQ_SET_ALARM,
+        and VIRTIO_RTC_REQ_SET_ALARM_ENABLED.
+\end{itemize}
+
+The unit of all \field{alarm_time} fields is 1 nanosecond.
+
+\begin{description}
+\item[VIRTIO_RTC_REQ_READ_ALARM] reads the current alarm.
+
+\begin{lstlisting}
+#define VIRTIO_RTC_REQ_READ_ALARM 0x1003 /* message type */
+
+struct virtio_rtc_req_read_alarm {
+        struct virtio_rtc_req_head head;
+        le16 clock_id;
+        u8 reserved[6];
+};
+
+struct virtio_rtc_resp_read_alarm {
+        struct virtio_rtc_resp_head head;
+        le64 alarm_time;
+#define VIRTIO_RTC_FLAG_ALARM_ENABLED   (1 << 0)
+        u8 flags;
+        u8 reserved[7];
+};
+\end{lstlisting}
+
+\field{clock_id} identifies the alarm through its associated clock. The
+\field{alarm_time} field returns the alarm time. In the \field{flags}
+field, VIRTIO_RTC_FLAG_ALARM_ENABLED indicates whether the alarm is
+enabled.
+
+\item[VIRTIO_RTC_REQ_SET_ALARM] sets the alarm.
+
+\begin{lstlisting}
+#define VIRTIO_RTC_REQ_SET_ALARM 0x1004 /* message type */
+
+struct virtio_rtc_req_set_alarm {
+        struct virtio_rtc_req_head head;
+        le64 alarm_time;
+        le16 clock_id;
+        /* flag: VIRTIO_RTC_FLAG_ALARM_ENABLED */
+        u8 flags;
+        u8 reserved[5];
+};
+
+struct virtio_rtc_resp_set_alarm {
+        struct virtio_rtc_resp_head head;
+        /* no response params */
+};
+\end{lstlisting}
+
+\field{clock_id} identifies the alarm through its associated clock. The
+\field{alarm_time} field sets the alarm time. If
+VIRTIO_RTC_FLAG_ALARM_ENABLED is set in the \field{flags} field, the
+device enables the alarm; otherwise, the device disables the alarm.
+
+\item[VIRTIO_RTC_REQ_SET_ALARM_ENABLED] enables or disables the alarm.
+
+\begin{lstlisting}
+#define VIRTIO_RTC_REQ_SET_ALARM_ENABLED 0x1005 /* message type */
+
+struct virtio_rtc_req_set_alarm_enabled {
+        struct virtio_rtc_req_head head;
+        le16 clock_id;
+        /* flag: VIRTIO_RTC_FLAG_ALARM_ENABLED */
+        u8 flags;
+        u8 reserved[5];
+};
+
+struct virtio_rtc_resp_set_alarm_enabled {
+        struct virtio_rtc_resp_head head;
+        /* no response params */
+};
+\end{lstlisting}
+
+\field{clock_id} identifies the alarm through its associated clock. If
+VIRTIO_RTC_FLAG_ALARM_ENABLED is set in the \field{flags} field, the
+device enables the alarm; otherwise, the device disables the alarm.
+
+When processing this request, the device retains the alarm time.
+
+\end{description}
+
+\paragraph{Alarm Notifications}
+
+If the alarmq is present, the driver should make buffers available in
+the alarmq, which the device uses for alarm notification messages. All
+alarmq fields are device-writable. The alarmq uses a common notification
+header.
+
+\begin{lstlisting}
+/* common notification header */
+struct virtio_rtc_notif_head {
+        le16 msg_type;
+        u8 reserved[6];
+};
+\end{lstlisting}
+
+The \field{msg_type} field identifies the message type.
+
+\begin{description}
+\item[VIRTIO_RTC_NOTIF_ALARM] notifies the driver about an alarm
+        expiration.
+
+\begin{lstlisting}
+#define VIRTIO_RTC_NOTIF_ALARM 0x2000 /* message type */
+
+struct virtio_rtc_notif_alarm {
+        struct virtio_rtc_notif_head head;
+        le16 clock_id;
+        u8 reserved[6];
+};
+\end{lstlisting}
+
+\end{description}
+
+\field{clock_id} identifies the expired alarm through its associated
+clock.
-- 
2.43.0

[PATCH v8 4/4] virtio-rtc: Add normative statements for alarm feature

[Peter Hilber]

Add the normative statements for the alarm feature added previously.

Signed-off-by: Peter Hilber <quic_philber@quicinc.com>
---

Notes:
    v8:
    
    - Explicitly describe alarm enabled status, where relevant (Matias
      Ezequiel Vara Larsen).
    
    - Simplify requirement about clock readings after alarm (Matias Ezequiel
      Vara Larsen).
    
    - Move requirements to serve alarm expiration events before requirements
      about stopping to serve (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".
    
    v7:
    
    - Remove inadvertent v6 changes, which should have been part of
      preceding patches.
    
    v4:
    
    - Update normative statements to match v4 changes to non-normative
      statements (patch 3).
    
    - Driver should read clock to confirm that alarm has expired.
    
    - Formatting and wording improvements.

 device-types/rtc/description.tex        | 150 ++++++++++++++++++++++++
 device-types/rtc/device-conformance.tex |   4 +
 device-types/rtc/driver-conformance.tex |   2 +
 3 files changed, 156 insertions(+)

diff --git a/device-types/rtc/description.tex b/device-types/rtc/description.tex
index 93bcf178b042..91afae7c2110 100644
--- a/device-types/rtc/description.tex
+++ b/device-types/rtc/description.tex
@@ -32,6 +32,11 @@ \subsection{Feature bits}\label{sec:Device Types / RTC Device / Feature bits}
 VIRTIO_RTC_F_ALARM determines whether the device supports setting an
 alarm for some of the clocks.
 
+\devicenormative{\subsubsection}{Feature bits}{Device Types / RTC Device / Feature bits}
+
+The device SHOULD offer VIRTIO_RTC_F_ALARM if the device can support
+setting an alarm for any of its clocks.
+
 \subsection{Device configuration layout}\label{sec:Device Types / RTC Device / Device configuration layout}
 
 There is no configuration data for the device.
@@ -712,6 +717,11 @@ \subsubsection{Read Requests}\label{sec:Device Types / RTC Device / Device Opera
 specification, the device MUST use the nanosecond as unit for the
 \field{clock_reading} field.
 
+If the device sent an alarm notification for clock C with alarm time A,
+the device MUST, for all read requests of C which the driver marks as
+available after the notification, return a \field{clock_reading} which
+does not precede A (except if C stepped backwards to before A).
+
 \subsubsection{Alarm Operation}\label{sec:Device Types / RTC Device / Device Operation / Alarm Operation}
 
 Through the optional alarm feature, the driver can set an alarm time. On
@@ -819,6 +829,76 @@ \subsubsection{Alarm Operation}\label{sec:Device Types / RTC Device / Device Ope
 To prevent the above issues, the driver also marks buffers in the alarmq
 as available only after completing the above steps for all clocks.
 
+\devicenormative{\paragraph}{Alarm Operation}{Device Types / RTC Device / Device Operation / Alarm Operation}
+
+The device MAY retain both alarm time and alarm enabled status of a
+clock across a device reset.
+
+If the device did not retain alarm time and alarm enabled status of a
+clock across a device reset, the device MUST initialize alarm time to 0.
+
+If the device did not retain alarm time and alarm enabled status of a
+clock across a device reset, the device MUST disable the alarm.
+
+If VIRTIO_RTC_F_ALARM was negotiated, the device MUST support the alarm
+messages, VIRTIO_RTC_REQ_READ_ALARM, VIRTIO_RTC_REQ_SET_ALARM,
+VIRTIO_RTC_REQ_SET_ALARM_ENABLED, and VIRTIO_RTC_NOTIF_ALARM, for one or
+more clocks.
+
+If VIRTIO_RTC_F_ALARM was not negotiated, the device MUST NOT support the
+alarm messages.
+
+The device MUST set the VIRTIO_RTC_FLAG_ALARM_CAP flag in \field{struct
+virtio_rtc_resp_clock_cap.flags} if the respective clock supports alarm
+messages, and clear the flag otherwise.
+
+The device MUST consider it an alarm expiration event when the
+associated clock progresses (also: steps) from a time prior to the alarm
+time to the alarm time, or to a time after the alarm time, while the
+alarm is enabled.
+
+The device MUST consider it an alarm expiration event when the
+driver sets an alarm time which the associated clock has already reached
+or passed, while also setting the alarm to enabled.
+
+The device MUST consider it an alarm expiration event when the driver
+sets the alarm to enabled, if the clock has already reached or passed
+the alarm time.
+
+If the device retained alarm time and alarm enabled status of a clock
+across a device reset, and the clock has already reached or passed the
+alarm time, the device MUST consider this device reset an alarm
+expiration event, if the alarm is enabled.
+
+If an alarm expiration event E happens, the device MUST start serving
+the alarm expiration event E.
+
+If the device is currently serving an alarm expiration event E, the
+device MUST send a single VIRTIO_RTC_NOTIF_ALARM notification for E, as
+soon as an alarmq buffer is available for this purpose.
+
+While the device is serving an alarm expiration event, the device MAY
+execute implementation-specific alarm actions.
+
+The device MAY ignore the device status when executing
+implementation-specific alarm actions.
+
+The device MAY ignore whether VIRTIO_RTC_F_ALARM was negotiated when
+executing implementation-specific alarm actions.
+
+If the driver successfully requests VIRTIO_RTC_REQ_SET_ALARM, or
+VIRTIO_RTC_REQ_SET_ALARM_ENABLED, for clock C, the device MUST stop
+serving any previous alarm expiration event for C before the device
+marks the message as used.
+
+If a clock C steps to a time previous to C's alarm time, the device MUST
+stop serving any previous alarm expiration event for C, within a grace
+period.
+
+If an alarm expiration event happens for clock C, the device MUST stop
+serving any previous alarm expiration event for C, within a grace
+period.
+
 \paragraph{Alarm Control Requests}
 
 If VIRTIO_RTC_F_ALARM is negotiated,
@@ -913,6 +993,59 @@ \subsubsection{Alarm Operation}\label{sec:Device Types / RTC Device / Device Ope
 
 \end{description}
 
+\drivernormative{\subparagraph}{Alarm Control Requests}{Device Types / RTC Device / Device Operation / Alarm Operation / Alarm Control Requests}
+
+For VIRTIO_RTC_REQ_SET_ALARM and for any clock type listed in this
+specification, the driver MUST use the nanosecond as unit for the
+\field{alarm_time} field.
+
+\devicenormative{\subparagraph}{Alarm Control Requests}{Device Types / RTC Device / Device Operation / Alarm Operation / Alarm Control Requests}
+
+If VIRTIO_RTC_F_ALARM was not negotiated, the device MUST set status
+VIRTIO_RTC_S_ENODEV for VIRTIO_RTC_REQ_READ_ALARM,
+VIRTIO_RTC_REQ_SET_ALARM, and VIRTIO_RTC_REQ_SET_ALARM_ENABLED.
+
+If the clock does not support alarm messages, the device MUST set status
+VIRTIO_RTC_S_ENODEV for VIRTIO_RTC_REQ_READ_ALARM,
+VIRTIO_RTC_REQ_SET_ALARM, and VIRTIO_RTC_REQ_SET_ALARM_ENABLED.
+
+For VIRTIO_RTC_REQ_READ_ALARM, the device MUST set the
+\field{alarm_time} field to the alarm time.
+
+For VIRTIO_RTC_REQ_READ_ALARM, the device MUST set the
+VIRTIO_RTC_FLAG_ALARM_ENABLED flag in the \field{flags} field if the
+alarm is enabled, and clear the flag otherwise.
+
+For VIRTIO_RTC_REQ_READ_ALARM and for any clock type listed in this
+specification, the device MUST use the nanosecond as unit for the
+\field{alarm_time} field.
+
+For VIRTIO_RTC_REQ_SET_ALARM, the device MUST accept any
+\field{alarm_time} value.
+
+If the device sets status VIRTIO_RTC_S_OK for VIRTIO_RTC_REQ_SET_ALARM,
+the device MUST set the alarm time to the time represented by the
+\field{alarm_time} field.
+
+If the device sets status VIRTIO_RTC_S_OK for VIRTIO_RTC_REQ_SET_ALARM,
+the device MUST enable the alarm if VIRTIO_RTC_FLAG_ALARM_ENABLED is set
+in the \field{flags} field.
+
+If the device sets status VIRTIO_RTC_S_OK for VIRTIO_RTC_REQ_SET_ALARM,
+the device MUST disable the alarm if VIRTIO_RTC_FLAG_ALARM_ENABLED is
+cleared in the \field{flags} field.
+
+If the device sets status VIRTIO_RTC_S_OK for
+VIRTIO_RTC_REQ_SET_ALARM_ENABLED, the device MUST enable the alarm if
+VIRTIO_RTC_FLAG_ALARM_ENABLED is set in the \field{flags} field.
+
+If the device sets status VIRTIO_RTC_S_OK for
+VIRTIO_RTC_REQ_SET_ALARM_ENABLED, the device MUST disable the alarm if
+VIRTIO_RTC_FLAG_ALARM_ENABLED is cleared in the \field{flags} field.
+
+If the device sets status VIRTIO_RTC_S_OK for
+VIRTIO_RTC_REQ_SET_ALARM_ENABLED, the device MUST retain the alarm time.
+
 \paragraph{Alarm Notifications}
 
 If the alarmq is present, the driver should make buffers available in
@@ -948,3 +1081,20 @@ \subsubsection{Alarm Operation}\label{sec:Device Types / RTC Device / Device Ope
 
 \field{clock_id} identifies the expired alarm through its associated
 clock.
+
+\drivernormative{\subparagraph}{Alarm Notifications}{Device Types / RTC Device / Device Operation / Alarm Operation / Alarm Notifications}
+
+If VIRTIO_RTC_F_ALARM was negotiated, the driver SHOULD populate the
+alarmq with buffers.
+
+The driver MUST allocate enough space for any alarmq message in the
+device-writable part of an alarmq buffer.
+
+If the driver receives a VIRTIO_RTC_NOTIF_ALARM notification, the driver
+SHOULD read the associated clock instead of assuming that the alarm time
+which the driver set last has been reached.
+
+\devicenormative{\subparagraph}{Alarm Notifications}{Device Types / RTC Device / Device Operation / Alarm Operation / Alarm Notifications}
+
+The device MUST NOT send a VIRTIO_RTC_NOTIF_ALARM notification for a
+clock which does not support alarm messages.
diff --git a/device-types/rtc/device-conformance.tex b/device-types/rtc/device-conformance.tex
index 4303cd450542..705691a7319f 100644
--- a/device-types/rtc/device-conformance.tex
+++ b/device-types/rtc/device-conformance.tex
@@ -3,7 +3,11 @@
 An RTC device MUST conform to the following normative statements:
 
 \begin{itemize}
+\item \ref{devicenormative:Device Types / RTC Device / Feature bits}
 \item \ref{devicenormative:Device Types / RTC Device / Device Operation}
 \item \ref{devicenormative:Device Types / RTC Device / Device Operation / Control Requests}
 \item \ref{devicenormative:Device Types / RTC Device / Device Operation / Read Requests}
+\item \ref{devicenormative:Device Types / RTC Device / Device Operation / Alarm Operation}
+\item \ref{devicenormative:Device Types / RTC Device / Device Operation / Alarm Operation / Alarm Control Requests}
+\item \ref{devicenormative:Device Types / RTC Device / Device Operation / Alarm Operation / Alarm Notifications}
 \end{itemize}
diff --git a/device-types/rtc/driver-conformance.tex b/device-types/rtc/driver-conformance.tex
index 689c18d158d0..a87c4cde99c2 100644
--- a/device-types/rtc/driver-conformance.tex
+++ b/device-types/rtc/driver-conformance.tex
@@ -6,4 +6,6 @@
 \item \ref{drivernormative:Device Types / RTC Device / Device Operation}
 \item \ref{drivernormative:Device Types / RTC Device / Device Operation / Control Requests}
 \item \ref{drivernormative:Device Types / RTC Device / Device Operation / Read Requests}
+\item \ref{drivernormative:Device Types / RTC Device / Device Operation / Alarm Operation / Alarm Control Requests}
+\item \ref{drivernormative:Device Types / RTC Device / Device Operation / Alarm Operation / Alarm Notifications}
 \end{itemize}
-- 
2.43.0

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

[Peter Hilber]

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.
> 

Could you please open a voting ballot for these changes?

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

This version of the patch series should have addressed all issues raised
so far. Since posting it 5 weeks ago, there has been no additional
feedback.

Best regards,

Peter

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

[Cornelia Huck]

On Thu, Mar 06 2025, Peter Hilber <quic_philber@quicinc.com> wrote:

> The virtio-rtc device provides information about current time through
> one or more clocks. As such, it is a Real-Time Clock (RTC) device.
>
> The normative statements for this device follow in the next patch.
>
> For this device, there is an RFC Linux kernel driver which is being
> upstreamed, and a proprietary device implementation.
>
> Miscellaneous
> -------------
>
> The spec does not specify how a driver should interpret clock readings,
> esp. also not how to perform clock synchronization.
>
> The device uses the "Timer/Clock" device id which is already part of the
> specification. This device id was registered a long time ago and should
> be unused according to the author's information. The name "RTC" was
> determined to be the best for a device which focuses on current time.
>
> Signed-off-by: Peter Hilber <quic_philber@quicinc.com>

(...)

[First of all, apologies for the very late feedback...]

> +The \field{status} field indicates whether the device successfully
> +executed the request. The device sets the \field{status} field to one of
> +the following values:
> +
> +\begin{lstlisting}
> +#define VIRTIO_RTC_S_OK         0
> +#define VIRTIO_RTC_S_EOPNOTSUPP 2
> +#define VIRTIO_RTC_S_ENODEV     3
> +#define VIRTIO_RTC_S_EINVAL     4
> +#define VIRTIO_RTC_S_EIO        5
> +\end{lstlisting}

Any reason there's no status code 1 here? (I assume there used to be
one... not a real problem, I just stumbled over it.)

Re: [PATCH v8 2/4] virtio-rtc: Add initial normative statements

[Cornelia Huck]

On Thu, Mar 06 2025, Peter Hilber <quic_philber@quicinc.com> wrote:

> Add the normative statements for the initial device specification.
>
> Signed-off-by: Peter Hilber <quic_philber@quicinc.com>

(...)

> diff --git a/device-types/rtc/description.tex b/device-types/rtc/description.tex
> index 5d8cf91a6991..f2a3907de511 100644
> --- a/device-types/rtc/description.tex
> +++ b/device-types/rtc/description.tex
> @@ -73,7 +73,7 @@ \subsection{Device Operation}\label{sec:Device Types / RTC Device / Device Opera
>  VIRTIO_RTC_S_EOPNOTSUPP indicates that the device could not execute the
>  specific request due to an implementation limitation. The device also
>  returns status VIRTIO_RTC_S_EOPNOTSUPP for requests with unknown values
> -in the fields \field{msg_type} or \field{hw_counter}.
> +in the \field{msg_type} or \field{hw_counter} fields.

Looks like some hunks with wording changes ended up in the wrong patch?
(A couple more of those in the remainder of this patch.)

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

[Peter Hilber]

On Tue, Apr 15, 2025 at 03:43:30PM +0200, Cornelia Huck wrote:
> On Thu, Mar 06 2025, Peter Hilber <quic_philber@quicinc.com> wrote:
> 
> > The virtio-rtc device provides information about current time through
> > one or more clocks. As such, it is a Real-Time Clock (RTC) device.
> >
> > The normative statements for this device follow in the next patch.
> >
> > For this device, there is an RFC Linux kernel driver which is being
> > upstreamed, and a proprietary device implementation.
> >
> > Miscellaneous
> > -------------
> >
> > The spec does not specify how a driver should interpret clock readings,
> > esp. also not how to perform clock synchronization.
> >
> > The device uses the "Timer/Clock" device id which is already part of the
> > specification. This device id was registered a long time ago and should
> > be unused according to the author's information. The name "RTC" was
> > determined to be the best for a device which focuses on current time.
> >
> > Signed-off-by: Peter Hilber <quic_philber@quicinc.com>
> 
> (...)
> 
> [First of all, apologies for the very late feedback...]
> 
> > +The \field{status} field indicates whether the device successfully
> > +executed the request. The device sets the \field{status} field to one of
> > +the following values:
> > +
> > +\begin{lstlisting}
> > +#define VIRTIO_RTC_S_OK         0
> > +#define VIRTIO_RTC_S_EOPNOTSUPP 2
> > +#define VIRTIO_RTC_S_ENODEV     3
> > +#define VIRTIO_RTC_S_EINVAL     4
> > +#define VIRTIO_RTC_S_EIO        5
> > +\end{lstlisting}
> 
> Any reason there's no status code 1 here? (I assume there used to be
> one... not a real problem, I just stumbled over it.)
> 

Status code 1 would be the same as VIRTIO_NET_ERR.

In the past, there was some discussion about reusing the spec in the net
device, so I changed the status values to align with the net control
virtqueue ack values. I am not sure if this will be helpful, should the
net device reuse ever materialize, since AFAIU the admin queue might
be used instead of the net control virtqueue.

Thanks for the comment,

Peter

Re: [PATCH v8 2/4] virtio-rtc: Add initial normative statements

[Peter Hilber]

On Tue, Apr 15, 2025 at 03:46:03PM +0200, Cornelia Huck wrote:
> On Thu, Mar 06 2025, Peter Hilber <quic_philber@quicinc.com> wrote:
> 
> > Add the normative statements for the initial device specification.
> >
> > Signed-off-by: Peter Hilber <quic_philber@quicinc.com>
> 
> (...)
> 
> > diff --git a/device-types/rtc/description.tex b/device-types/rtc/description.tex
> > index 5d8cf91a6991..f2a3907de511 100644
> > --- a/device-types/rtc/description.tex
> > +++ b/device-types/rtc/description.tex
> > @@ -73,7 +73,7 @@ \subsection{Device Operation}\label{sec:Device Types / RTC Device / Device Opera
> >  VIRTIO_RTC_S_EOPNOTSUPP indicates that the device could not execute the
> >  specific request due to an implementation limitation. The device also
> >  returns status VIRTIO_RTC_S_EOPNOTSUPP for requests with unknown values
> > -in the fields \field{msg_type} or \field{hw_counter}.
> > +in the \field{msg_type} or \field{hw_counter} fields.
> 
> Looks like some hunks with wording changes ended up in the wrong patch?
> (A couple more of those in the remainder of this patch.)
> 

Yes, terribly sorry about this oversight... I will provide a fix.

Thanks,

Peter

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

[Cornelia Huck]

On Tue, Apr 15 2025, Peter Hilber <quic_philber@quicinc.com> wrote:

> On Tue, Apr 15, 2025 at 03:43:30PM +0200, Cornelia Huck wrote:
>> On Thu, Mar 06 2025, Peter Hilber <quic_philber@quicinc.com> wrote:
>> 
>> > The virtio-rtc device provides information about current time through
>> > one or more clocks. As such, it is a Real-Time Clock (RTC) device.
>> >
>> > The normative statements for this device follow in the next patch.
>> >
>> > For this device, there is an RFC Linux kernel driver which is being
>> > upstreamed, and a proprietary device implementation.
>> >
>> > Miscellaneous
>> > -------------
>> >
>> > The spec does not specify how a driver should interpret clock readings,
>> > esp. also not how to perform clock synchronization.
>> >
>> > The device uses the "Timer/Clock" device id which is already part of the
>> > specification. This device id was registered a long time ago and should
>> > be unused according to the author's information. The name "RTC" was
>> > determined to be the best for a device which focuses on current time.
>> >
>> > Signed-off-by: Peter Hilber <quic_philber@quicinc.com>
>> 
>> (...)
>> 
>> [First of all, apologies for the very late feedback...]
>> 
>> > +The \field{status} field indicates whether the device successfully
>> > +executed the request. The device sets the \field{status} field to one of
>> > +the following values:
>> > +
>> > +\begin{lstlisting}
>> > +#define VIRTIO_RTC_S_OK         0
>> > +#define VIRTIO_RTC_S_EOPNOTSUPP 2
>> > +#define VIRTIO_RTC_S_ENODEV     3
>> > +#define VIRTIO_RTC_S_EINVAL     4
>> > +#define VIRTIO_RTC_S_EIO        5
>> > +\end{lstlisting}
>> 
>> Any reason there's no status code 1 here? (I assume there used to be
>> one... not a real problem, I just stumbled over it.)
>> 
>
> Status code 1 would be the same as VIRTIO_NET_ERR.
>
> In the past, there was some discussion about reusing the spec in the net
> device, so I changed the status values to align with the net control
> virtqueue ack values. I am not sure if this will be helpful, should the
> net device reuse ever materialize, since AFAIU the admin queue might
> be used instead of the net control virtqueue.

Thanks for the explanation -- I think it's fine to just leave it as it
is now, the important thing is that the values are specified.

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

[Matias Ezequiel Vara Larsen]

On Thu, Mar 06, 2025 at 10:51:09AM +0100, Peter Hilber wrote:
> The virtio-rtc device provides information about current time through
> one or more clocks. As such, it is a Real-Time Clock (RTC) device.
> 
> The normative statements for this device follow in the next patch.
> 
> For this device, there is an RFC Linux kernel driver which is being
> upstreamed, and a proprietary device implementation.
> 
> Miscellaneous
> -------------
> 
> The spec does not specify how a driver should interpret clock readings,
> esp. also not how to perform clock synchronization.
> 
> The device uses the "Timer/Clock" device id which is already part of the
> specification. This device id was registered a long time ago and should
> be unused according to the author's information. The name "RTC" was
> determined to be the best for a device which focuses on current time.
> 
> Signed-off-by: Peter Hilber <quic_philber@quicinc.com>
> ---
> 
> Notes:
>     v8:
>     
>     - Change word order from "field X" to "the X field" (Matias Ezequiel
>       Vara Larsen).
>     
>     - Split up sentences about implementation-specific definitions (Matias
>       Ezequiel Vara Larsen).
>     
>     v7:
>     
>     - Remove leap second and performance indications from struct
>       virtio_rtc_resp_read_cross. Remove backing definitions.
>     
>     - Add wording change which was previously mistakenly placed in last
>       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 [8].
>     
>     - Add dedicated clock types for UTC leap second smearing (David
>       Woodhouse).
>     
>     - Extend leap second indications.
>     
>     - Split UTC-TAI offset and fractional offset due to smearing (David
>       Woodhouse).
>     
>     - Remove requirement that TAI offset must not be a whole second while
>       clock is being smeared.
>     
>     - Align bit widths, and some names, with '[RFC PATCH v4] ptp: Add
>       vDSO-style vmclock support' [8].
>     
>     - 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.
>     
>     v4:
>     
>     - Drop distinction of Arm Generic Timer virtual and physical counter [7].
>     
>     - Add requirement that device should assume that driver reads clock from
>       first vCPU (David Woodhouse) [6].
>     
>     - Formatting and wording improvements.
>     
>     v3:
>     
>     - Address comments from Parav Pandit.
>     
>     - Split off normative requirements into a second commit [2].
>     
>     - Merge readq and controlq into requestq [3].
>     
>     - Don't guard cross-timestamping with feature bit [3].
>     
>     - Pad request headers to 64 bit [2].
>     
>     - Rename Virtio status codes to match UNIX error names [2].
>     
>     - Avoid Virtio status code clashes with net controlq ack values.
>     
>     - Reword to refer more to "requests", rather than "messages" [2].
>     
>     - Rephrase some sentences [2].
>     
>     - Use integer data types without "__" prefixes [2].
>     
>     - Reduce clock id width to 16 bits [5].
>     
>     - Make VIRTIO_RTC_FLAG_CROSS_CAP a bit mask rather than a bit index.
>     
>     v2:
>     
>     - Address comments from Cornelia Huck.
>     
>     - Add VIRTIO_RTC_M_CROSS_CAP message [1].
>     
>     - Fix various minor issues and improve wording [1].
>     
>     - Add several clarifications regarding device error statuses.
>     
>     [1] https://lists.oasis-open.org/archives/virtio-comment/202304/msg00523.html
>     [2] https://lore.kernel.org/virtio-comment/b59a7dda-06fe-cff9-df61-b90aa4e50836@opensynergy.com/t/#mffb93800fea11d6dda9e151078abedd6ff1c0f1e
>     [3] https://lore.kernel.org/virtio-comment/b59a7dda-06fe-cff9-df61-b90aa4e50836@opensynergy.com/t/#m94efd0aa9b9c2b96a246b79ef8bfc3bf64ebe791
>     [4] https://lore.kernel.org/lkml/20230630171052.985577-1-peter.hilber@opensynergy.com/T/#m65fa1d715933360498c4e33d7225e4220215a9d6
>     [5] https://lore.kernel.org/virtio-comment/b59a7dda-06fe-cff9-df61-b90aa4e50836@opensynergy.com/t/#mf00ce330228c28556d735eb9597469048c5d8b62
>     [6] https://lore.kernel.org/lkml/d796d9a5-8eda-4528-a6d8-1c4eba24aa1e@opensynergy.com/
>     [7] https://lore.kernel.org/all/20231218064253.9734-2-peter.hilber@opensynergy.com/
>     [8] https://lore.kernel.org/lkml/20240708092924.1473461-1-dwmw2@infradead.org/
> 
>  content.tex                      |   3 +-
>  device-types/rtc/description.tex | 428 +++++++++++++++++++++++++++++++
>  introduction.tex                 |   6 +
>  3 files changed, 436 insertions(+), 1 deletion(-)
>  create mode 100644 device-types/rtc/description.tex
> 
> diff --git a/content.tex b/content.tex
> index 67b1bf3c35ab..b1d93a8aebb4 100644
> --- a/content.tex
> +++ b/content.tex
> @@ -684,7 +684,7 @@ \chapter{Device Types}\label{sec:Device Types}
>  \hline
>  16         &   GPU device       \\
>  \hline
> -17         &   Timer/Clock device \\
> +17         &   RTC (Timer/Clock) device \\
>  \hline
>  18         &   Input device \\
>  \hline
> @@ -776,6 +776,7 @@ \chapter{Device Types}\label{sec:Device Types}
>  \input{device-types/pmem/description.tex}
>  \input{device-types/can/description.tex}
>  \input{device-types/spi/description.tex}
> +\input{device-types/rtc/description.tex}
>  
>  \chapter{Reserved Feature Bits}\label{sec:Reserved Feature Bits}
>  
> diff --git a/device-types/rtc/description.tex b/device-types/rtc/description.tex
> new file mode 100644
> index 000000000000..5d8cf91a6991
> --- /dev/null
> +++ b/device-types/rtc/description.tex
> @@ -0,0 +1,428 @@
> +\section{RTC Device}\label{sec:Device Types / RTC Device}
> +
> +The RTC (Real Time Clock) device provides information about current
> +time. The device can provide different clocks, e.g.\ for the UTC or TAI
> +time standards, or for physical time elapsed since some past epoch. The
> +driver can read the clocks with simple or more accurate methods.
> +

Can't we avoid to use `can` here and just use present simple?

> +\subsection{Device ID}\label{sec:Device Types / RTC Device / Device ID}
> +
> +17
> +
> +\subsection{Virtqueues}\label{sec:Device Types / RTC Device / Virtqueues}
> +
> +\begin{description}
> +\item[0] requestq
> +\end{description}
> +
> +The driver enqueues requests to the requestq.
> +
> +\subsection{Feature bits}\label{sec:Device Types / RTC Device / Feature bits}
> +
> +No device-specific feature bits are defined yet.
> +
> +\subsection{Device configuration layout}\label{sec:Device Types / RTC Device / Device configuration layout}
> +
> +There is no configuration data for the device.
> +
> +\subsection{Device Initialization}\label{sec:Device Types / RTC Device / Device Initialization}
> +
> +The device determines the set of clocks. The device can provide zero or
> +more clocks.

I think you can avoid to use `can` here and also in other places.

> +
> +\subsection{Device Operation}\label{sec:Device Types / RTC Device / Device Operation}
> +
> +For the requestq, the driver sends a message with a request, and
> +receives the response in the device-writable part of the message. The
> +requestq uses common request and response headers.
> +
> +\begin{lstlisting}
> +/* common request header */
> +struct virtio_rtc_req_head {
> +        le16 msg_type;
> +        u8 reserved[6];
> +};
> +
> +/* common response header */
> +struct virtio_rtc_resp_head {
> +        u8 status;
> +        u8 reserved[7];
> +};
> +\end{lstlisting}
> +
> +The \field{msg_type} field identifies the message type.
> +
> +The \field{status} field indicates whether the device successfully
> +executed the request. The device sets the \field{status} field to one of
> +the following values:
> +
> +\begin{lstlisting}
> +#define VIRTIO_RTC_S_OK         0
> +#define VIRTIO_RTC_S_EOPNOTSUPP 2
> +#define VIRTIO_RTC_S_ENODEV     3
> +#define VIRTIO_RTC_S_EINVAL     4
> +#define VIRTIO_RTC_S_EIO        5
> +\end{lstlisting}
> +
> +VIRTIO_RTC_S_OK indicates that the device successfully executed the
> +request.
> +
> +If \field{status} is not VIRTIO_RTC_S_OK, the value of other response
> +fields is undefined.
> +
> +VIRTIO_RTC_S_EOPNOTSUPP indicates that the device could not execute the
> +specific request due to an implementation limitation. The device also
> +returns status VIRTIO_RTC_S_EOPNOTSUPP for requests with unknown values
> +in the fields \field{msg_type} or \field{hw_counter}.
> +
> +VIRTIO_RTC_S_ENODEV indicates that the \field{clock_id} field value
> +supplied with the request does not identify a clock.
> +
> +VIRTIO_RTC_S_EINVAL indicates that
> +
> +\begin{itemize}
> +\item the driver request values are not allowed by the specification or
> +\item the device read-only part of the message, or the device write-only
> +        part of the message, is too small to fit the actual message.
> +\end{itemize}
> +
> +VIRTIO_RTC_S_EIO indicates that the device did not execute the request
> +due to an error which was not caused by invalid input from the driver.

s/was/is

> +
> +All \field{reserved} fields are written as zero, and their value is
> +ignored.
> +
> +The set of clocks does not change after feature negotiation completion,
> +until device reset. The set of clocks should not change on device reset
> +either (similar to negotiated features). Clock identifiers are
> +zero-based, dense indices. All fields named \field{clock_id} contain
> +clock identifiers.
> +
> +\subsubsection{Common Definitions}\label{sec:Device Types / RTC Device / Device Operation / Common Definitions}
> +
> +This section makes common definitions.
> +
> +\paragraph{Clock Types}\label{sec:Device Types / RTC Device / Device Operation / Common Definitions / Clock Types}
> +
> +The following clock types are defined:
> +
> +\begin{lstlisting}
> +#define VIRTIO_RTC_CLOCK_UTC                    0
> +#define VIRTIO_RTC_CLOCK_TAI                    1
> +#define VIRTIO_RTC_CLOCK_MONOTONIC              2
> +#define VIRTIO_RTC_CLOCK_UTC_SMEARED            3
> +#define VIRTIO_RTC_CLOCK_UTC_MAYBE_SMEARED      4
> +\end{lstlisting}
> +
> +\begin{description}
> +
> +\item[VIRTIO_RTC_CLOCK_UTC] uses the UTC (Coordinated Universal Time)
> +        time standard. This clock uses the time epoch of January 1,
> +        1970, 00:00 UTC. This is the same epoch as \emph{Unix time}. The
> +        clock's seconds since the epoch are related to UTC time as
> +        defined by \hyperref[intro:EPOCH]{EPOCH}.
> +
> +        This clock observes positive and negative leap seconds as
> +        announced by standard bodies. At the start of leap seconds, the
> +        clock steps accordingly.
> +
> +\item[VIRTIO_RTC_CLOCK_TAI] uses the TAI (International Atomic Time)
> +        time standard. This clock uses the time epoch of January 1,
> +        1970, 00:00 TAI.
> +
> +\item[VIRTIO_RTC_CLOCK_MONOTONIC] uses monotonic physical time (SI
> +        seconds subdivisions) since some unspecified epoch. The epoch is
> +        before or during device reset.
> +
> +\item[VIRTIO_RTC_CLOCK_UTC_SMEARED] deviates from the UTC standard by
> +        smearing time in the vicinity of a leap second. This avoids
> +        clock steps due to UTC leap seconds. Otherwise, this clock is
> +        similar to VIRTIO_RTC_CLOCK_UTC.
> +
> +\item[VIRTIO_RTC_CLOCK_UTC_MAYBE_SMEARED] This clock
> +
> +\begin{itemize}
> +\item may deviate from the UTC standard by smearing time in the vicinity
> +        of a leap second (similar to VIRTIO_RTC_CLOCK_UTC_SMEARED), or
> +
> +\item may step at the start of leap seconds like VIRTIO_RTC_CLOCK_UTC.
> +\end{itemize}
> +
> +A clock of type VIRTIO_RTC_CLOCK_UTC_MAYBE_SMEARED can change this
> +behavior for every leap second.
> +
> +\end{description}
> +
> +In the following, \emph{UTC-like clock} designates any clock of type
> +VIRTIO_RTC_CLOCK_UTC, VIRTIO_RTC_CLOCK_UTC_SMEARED, or
> +VIRTIO_RTC_CLOCK_UTC_MAYBE_SMEARED.
> +
> +Additional clock types may be standardized in the future.
> +Implementation-specific definitions of clock types are not recommended.
> +Implementation-specific definitions use ids between 0xF0 and 0xFF.
> +
> +\paragraph{Smearing Variants}\label{sec:Device Types / RTC Device / Device Operation / Common Definitions / Smearing Variants}
> +
> +Leap second \emph{smearing variants} describe the deviation from the UTC
> +standard in the vicinity of a leap second. The following smearing
> +variants are currently defined:
> +
> +\begin{lstlisting}
> +#define VIRTIO_RTC_SMEAR_UNSPECIFIED    0
> +#define VIRTIO_RTC_SMEAR_NOON_LINEAR    1
> +#define VIRTIO_RTC_SMEAR_UTC_SLS        2
> +\end{lstlisting}
> +
> +\begin{description}
> +
> +        \item[VIRTIO_RTC_SMEAR_UNSPECIFIED] means that it is unspecified
> +                how time is smeared in the vicinity of leap seconds.
> +
> +        \item[VIRTIO_RTC_SMEAR_NOON_LINEAR] specifies a linear smear
> +                from noon prior to the leap second until noon after the
> +                leap second.
> +
> +        \item[VIRTIO_RTC_SMEAR_UTC_SLS] specifies a linear smear as per
> +                the \hyperref[intro:UTC-SLS]{UTC-SLS} proposal.
> +
> +\end{description}
> +
> +Clocks of type VIRTIO_RTC_CLOCK_UTC_SMEARED always behave according to a
> +smearing variant. The smearing variant does not change over the clock's
> +lifetime.
> +
> +For clocks of type VIRTIO_RTC_CLOCK_UTC_MAYBE_SMEARED, it is unspecified
> +whether leap seconds are smeared, and how leap seconds are smeared.
> +
> +Additional smearing variants may be standardized in the future.
> +Implementation-specific definitions of smearing variants are not
> +recommended. Implementation-specific definitions use ids greater than or
> +equal to 0xF0.
> +
> +In the following, \emph{leap smearing clock} designates
> +
> +\begin{itemize}
> +
> +\item any clock of type VIRTIO_RTC_CLOCK_UTC_SMEARED
> +
> +\item any clock of type VIRTIO_RTC_CLOCK_UTC_MAYBE_SMEARED at any time
> +        when the clock is smearing a leap second.
> +
> +\end{itemize}
> +
> +\paragraph{Hardware Counters}\label{sec:Device Types / RTC Device / Device Operation / Common Definitions / Hardware Counters}
> +
> +The following hardware counter identifiers are specified:
> +
> +\begin{lstlisting}
> +/* Arm Generic Timer Counter-timer Virtual Count Register (CNTVCT_EL0) */
> +#define VIRTIO_RTC_COUNTER_ARM_VCT      0
> +/* x86 Time-Stamp Counter */
> +#define VIRTIO_RTC_COUNTER_X86_TSC      1
> +/* Invalid */
> +#define VIRTIO_RTC_COUNTER_INVALID   0xFF
> +\end{lstlisting}
> +
> +Additional hardware counter identifiers may be standardized in the
> +future. Implementation-specific hardware counter identifiers are not
> +recommended. Implementation-specific hardware counter identifiers have
> +values between 0xF0 and 0xFE.
> +
> +\subsubsection{Control Requests}\label{sec:Device Types / RTC Device / Device Operation / Control Requests}
> +
> +Through \emph{control requests}, the driver requests information about
> +the device capabilities. The driver enqueues control requests in the
> +requestq.
> +
> +\begin{description}
> +
> +\item[VIRTIO_RTC_REQ_CFG] discovers the number of clocks.
> +
> +\begin{lstlisting}
> +#define VIRTIO_RTC_REQ_CFG 0x1000 /* message type */
> +
> +struct virtio_rtc_req_cfg {
> +        struct virtio_rtc_req_head head;
> +        /* no request params */
> +};
> +
> +struct virtio_rtc_resp_cfg {
> +        struct virtio_rtc_resp_head head;
> +        le16 num_clocks;
> +        u8 reserved[6];
> +};
> +\end{lstlisting}
> +
> +Field \field{num_clocks} contains the number of clocks. A device
> +provides zero or more clocks. Valid clock ids are those smaller than
> +\field{num_clocks}.
> +
> +\item[VIRTIO_RTC_REQ_CLOCK_CAP] discovers the capabilities of the clock
> +identified by the \field{clock_id} field.
> +
> +\begin{lstlisting}
> +#define VIRTIO_RTC_REQ_CLOCK_CAP 0x1001 /* message type */
> +
> +struct virtio_rtc_req_clock_cap {
> +        struct virtio_rtc_req_head head;
> +        le16 clock_id;
> +        u8 reserved[6];
> +};
> +
> +struct virtio_rtc_resp_clock_cap {
> +        struct virtio_rtc_resp_head head;
> +        u8 type;
> +        u8 leap_second_smearing;
> +        u8 reserved[6];
> +};
> +\end{lstlisting}
> +
> +The \field{type} field identifies the clock type. A device provides
> +zero or more clocks for a clock type.
> +
> +Clocks of type VIRTIO_RTC_CLOCK_UTC_SMEARED indicate the \emph{smearing
> +variant} through field \field{leap_second_smearing}. All other clocks
> +set \field{leap_second_smearing} to VIRTIO_RTC_SMEAR_UNSPECIFIED.
> +
> +\item[VIRTIO_RTC_REQ_CROSS_CAP] discovers whether the device supports
> +cross-timestamping for a particular pair of clock and hardware counter.
> +
> +\begin{lstlisting}
> +#define VIRTIO_RTC_REQ_CROSS_CAP 0x1002 /* message type */
> +
> +struct virtio_rtc_req_cross_cap {
> +        struct virtio_rtc_req_head head;
> +        le16 clock_id;
> +        u8 hw_counter;
> +        u8 reserved[5];
> +};
> +
> +
> +struct virtio_rtc_resp_cross_cap {
> +        struct virtio_rtc_resp_head head;
> +#define VIRTIO_RTC_FLAG_CROSS_CAP       (1 << 0)
> +        u8 flags;
> +        u8 reserved[7];
> +};
> +\end{lstlisting}
> +
> +The \field{clock_id} field identifies the clock, and the
> +\field{hw_counter} field identifies the hardware counter, for which
> +cross-timestamp support is probed. The device sets the
> +VIRTIO_RTC_FLAG_CROSS_CAP flag in the \field{flags} field if the clock
> +supports cross-timestamping for the particular clock and hardware
> +counter, and clears the flag otherwise.
> +
> +\end{description}
> +
> +\subsubsection{Read Requests}\label{sec:Device Types / RTC Device / Device Operation / Read Requests}
> +
> +Through \emph{read requests}, the driver requests clock readings from
> +the device. The driver enqueues read requests in the requestq. The
> +device obtains device-side clock readings and forwards these clock
> +readings to the driver. The driver may enhance and interpret the clock
> +readings through methods which are beyond the scope of this
> +specification.
> +
> +Once DRIVER_OK has been set, the device should support reading every
> +clock, even when a clock may yet have to be aligned to reference time
> +sources.
> +
> +In general,
> +
> +\begin{itemize}
> +\item clocks may jump backwards or forward, and
> +\item the clock frequency may change. Clocks may be \emph{slewed},
> +        i.e.\ clocks may run at a frequency other than their current
> +        best frequency estimate.
> +\end{itemize}
> +
> +As long as a clock does not jump backwards, the driver clock readings
> +through read request responses increase monotonically:
> +
> +\begin{itemize}
> +\item As long as a clock does not jump backwards in-between device-side
> +        clock readings, the driver-side readings for that clock increase
> +        monotonically as well, in the order in which the driver
> +        marks read requests as available.
> +
> +\item The device marks read requests for the same clock as used in
> +        the order in which the messages were marked as available.
> +\end{itemize}
> +
> +For a clock of type VIRTIO_RTC_CLOCK_MONOTONIC, the device always returns
> +monotonically increasing clock readings through read request responses.
> +
> +The unit of all \field{clock_reading} fields is 1
> +nanosecond.\footnote{For time epochs in year 1970 or later, this means
> +that time until at least year 2553 can be represented in the \field{le64
> +clock_reading} fields.}
> +
> +\begin{description}
> +
> +\item[VIRTIO_RTC_REQ_READ] reads the clock identified by the
> +\field{clock_id} field. The device supports this message for every
> +clock.
> +
> +\begin{lstlisting}
> +#define VIRTIO_RTC_REQ_READ 0x0001 /* message type */
> +
> +struct virtio_rtc_req_read {
> +        struct virtio_rtc_req_head head;
> +        le16 clock_id;
> +        u8 reserved[6];
> +};
> +
> +struct virtio_rtc_resp_read {
> +        struct virtio_rtc_resp_head head;
> +        le64 clock_reading;
> +};
> +\end{lstlisting}
> +
> +\field{clock_reading} is a device-side clock reading obtained after the
> +message was marked as available.

s/was/is

> +
> +\item[VIRTIO_RTC_REQ_READ_CROSS] returns a cross-timestamp for the clock
> +identified by the \field{clock_id} field.\footnote{Cross-timestamping
> +is similar to the ptp_kvm mechanism in the Linux kernel.} This message
> +may yield better performance than using VIRTIO_RTC_REQ_READ.
> +
> +The driver can determine whether the device supports
> +VIRTIO_RTC_REQ_READ_CROSS for a specific clock and \field{hw_counter}
> +through VIRTIO_RTC_REQ_CROSS_CAP.
> +
> +\begin{lstlisting}
> +#define VIRTIO_RTC_REQ_READ_CROSS 0x0002 /* message type */
> +
> +struct virtio_rtc_req_read_cross {
> +        struct virtio_rtc_req_head head;
> +        le16 clock_id;
> +        u8 hw_counter;
> +        u8 reserved[5];
> +};
> +
> +struct virtio_rtc_resp_read_cross {
> +        struct virtio_rtc_resp_head head;
> +        le64 clock_reading;
> +        le64 counter_cycles;
> +};
> +\end{lstlisting}
> +
> +The \field{hw_counter} field specifies the hardware counter for which
> +the driver requests a cross-timestamp.
> +
> +Cross-timestamping returns a \field{clock_reading}, and an associated
> +hardware counter value, \field{counter_cycles}. The
> +\field{counter_cycles} field is the approximate or precise value which
> +the driver would have read at the \field{clock_reading} time instant
> +from the hardware counter identified by \field{hw_counter}. How the
> +device determines the value which the driver would have seen is beyond
> +the scope of this specification. In case hardware counter reads differ
> +among CPUs used by the driver, the device should assume that the driver
> +reads the hardware counter from the CPU which the driver enumerates as
> +the first.
> +
> +The hardware counter identifiers are defined in
> +\ref{sec:Device Types / RTC Device / Device Operation / Common Definitions / Hardware Counters}.
> +
> +\end{description}
> diff --git a/introduction.tex b/introduction.tex
> index e60298a4d78b..34f9485bc393 100644
> --- a/introduction.tex
> +++ b/introduction.tex
> @@ -168,6 +168,12 @@ \section{Normative References}\label{sec:Normative References}
>      Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP
>      14, RFC 8174, DOI 10.17487/RFC8174, May 2017
>          \newline\url{http://www.ietf.org/rfc/rfc8174.txt}\\
> +	\phantomsection\label{intro:EPOCH}\textbf{[EPOCH]} &
> +    POSIX.1-2024, Base Definitions, Seconds Since the Epoch
> +	\newline\url{https://pubs.opengroup.org/onlinepubs/9799919799/basedefs/V1_chap04.html#tag_04_19}\\
> +	\phantomsection\label{intro:UTC-SLS}\textbf{[UTC-SLS]} &
> +    UTC with Smoothed Leap Seconds (UTC-SLS)
> +	\newline\url{https://www.cl.cam.ac.uk/~mgk25/time/utc-sls/}\\
>  \end{longtable}
>  
>  \section{Non-Normative References}
> -- 
> 2.43.0
> 

Re: [PATCH v8 2/4] virtio-rtc: Add initial normative statements

[Matias Ezequiel Vara Larsen]

On Thu, Mar 06, 2025 at 10:51:10AM +0100, Peter Hilber wrote:
> Add the normative statements for the initial device specification.
> 
> Signed-off-by: Peter Hilber <quic_philber@quicinc.com>
> ---
> 
> Notes:
>     v8:
>     
>     - Drop requirement to ignore reserved fields in the device-readable part
>       of the message (Matias Ezequiel Vara Larsen).
>     
>     - Drop requirement about returning same status in response to identical
>       requests (Matias Ezequiel Vara Larsen).
>     
>     - Reword requirements about size mismatches for device
>       read-only/write-only parts of the message (Matias Ezequiel Vara
>       Larsen).
>     
>     - Change word order from "field X" to "the X field" (Matias Ezequiel
>       Vara Larsen).
>     
>     v7:
>     
>     - Remove obsolete requirements for leap second indication.
>     
>     v6:
>     
>     - Update requirements to make leap second status information optional if
>       if the clock smears (or might smear) leap seconds.
>     
>     - Allow indicating VIRTIO_RTC_SMEAR_UNSPECIFIED for
>       VIRTIO_RTC_CLOCK_SMEARED.
>     
>     - Shorten some requirements by omitting redundant information.
>     
>     v5:
>     
>     - Update normative statements to match v5 changes to non-normative
>       statements (patch 1).
>     
>     v4:
>     
>     - Require driver to set unused flags to zero.
>     
>     - Update normative statements to match v4 changes to non-normative
>       statements (patch 1).
>     
>     - Improve formatting.
> 
>  conformance.tex                         |   2 +
>  device-types/rtc/description.tex        | 272 +++++++++++++++++++++++-
>  device-types/rtc/device-conformance.tex |   9 +
>  device-types/rtc/driver-conformance.tex |   9 +
>  4 files changed, 288 insertions(+), 4 deletions(-)
>  create mode 100644 device-types/rtc/device-conformance.tex
>  create mode 100644 device-types/rtc/driver-conformance.tex
> 
> diff --git a/conformance.tex b/conformance.tex
> index d92a2369488e..4ce86a525e84 100644
> --- a/conformance.tex
> +++ b/conformance.tex
> @@ -162,6 +162,7 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets}
>  \input{device-types/pmem/driver-conformance.tex}
>  \input{device-types/can/driver-conformance.tex}
>  \input{device-types/spi/driver-conformance.tex}
> +\input{device-types/rtc/driver-conformance.tex}
>  
>  \conformance{\section}{Device Conformance}\label{sec:Conformance / Device Conformance}
>  
> @@ -254,6 +255,7 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets}
>  \input{device-types/pmem/device-conformance.tex}
>  \input{device-types/can/device-conformance.tex}
>  \input{device-types/spi/device-conformance.tex}
> +\input{device-types/rtc/device-conformance.tex}
>  
>  \conformance{\section}{Legacy Interface: Transitional Device and Transitional Driver Conformance}\label{sec:Conformance / Legacy Interface: Transitional Device and Transitional Driver Conformance}
>  A conformant implementation MUST be either transitional or
> diff --git a/device-types/rtc/description.tex b/device-types/rtc/description.tex
> index 5d8cf91a6991..f2a3907de511 100644
> --- a/device-types/rtc/description.tex
> +++ b/device-types/rtc/description.tex
> @@ -73,7 +73,7 @@ \subsection{Device Operation}\label{sec:Device Types / RTC Device / Device Opera
>  VIRTIO_RTC_S_EOPNOTSUPP indicates that the device could not execute the
>  specific request due to an implementation limitation. The device also
>  returns status VIRTIO_RTC_S_EOPNOTSUPP for requests with unknown values
> -in the fields \field{msg_type} or \field{hw_counter}.
> +in the \field{msg_type} or \field{hw_counter} fields.
>  
>  VIRTIO_RTC_S_ENODEV indicates that the \field{clock_id} field value
>  supplied with the request does not identify a clock.
> @@ -98,6 +98,106 @@ \subsection{Device Operation}\label{sec:Device Types / RTC Device / Device Opera
>  zero-based, dense indices. All fields named \field{clock_id} contain
>  clock identifiers.
>  
> +\drivernormative{\subsubsection}{Device Operation}{Device Types / RTC Device / Device Operation}
> +
> +If the \field{struct virtio_rtc_resp_head} field \field{status} is not
> +VIRTIO_RTC_S_OK, the driver MUST NOT interpret response fields other
> +than \field{status}.

Can't we say "The driver MUST interpret response field only when status
is VIRTIO_RTC_S_OK".

> +
> +The driver MUST set \emph{reserved} fields in the device-readable part
> +of the message to zero.
> +
> +The driver MUST set unnamed bits in \emph{flags} fields in the
> +device-readable part of the message to zero.
> +
> +The driver MUST NOT interpret \emph{reserved} fields in the
> +device-writable part of the message.

Why the driver would interpret reserved fields?

> +
> +The driver MUST NOT interpret unnamed bits in \emph{flags} fields in the
> +device-writable part of the message.
> +
> +The driver MUST put the request into the device-readable part of the
> +message.

I do not think this is required in this section. The spec defines the
device-readable as the only section in which the driver can write. Other
devices just add in "// Device-readable part" in the common structures
for the response and request. Are other devices specifying something
similar? 

> +
> +The driver MUST allocate enough space for the response in the
> +device-writable part of a requestq message.
> +
> +\devicenormative{\subsubsection}{Device Operation}{Device Types / RTC Device / Device Operation}
> +
> +For \field{struct virtio_rtc_resp_head}, the device MUST set the
> +\field{status} field to VIRTIO_RTC_S_OK if the device successfully
> +executed the request.
> +
> +For \field{struct virtio_rtc_resp_head}, the device MUST set the
> +\field{status} field to a status other than VIRTIO_RTC_S_OK if the
> +device did not successfully execute the request.
> +
> +For \field{struct virtio_rtc_resp_head}, the device MUST set the
> +\field{status} field to VIRTIO_RTC_S_EOPNOTSUPP if the device could not
> +execute the specific request due to an implementation limitation.
> +
> +For \field{struct virtio_rtc_resp_head}, the device MUST set the
> +\field{status} field to VIRTIO_RTC_S_EOPNOTSUPP for a request with a
> +value of the \field{msg_type} field which is not described in this
> +specification.
> +
> +For \field{struct virtio_rtc_resp_head}, the device MUST set the
> +\field{status} field to VIRTIO_RTC_S_EOPNOTSUPP for a request with a
> +value of the \field{hw_counter} field which is neither described in this
> +specification nor otherwise known to the implementation.
> +
> +For \field{struct virtio_rtc_resp_head}, the device MUST set the
> +\field{status} field to VIRTIO_RTC_S_ENODEV if the \field{clock_id}
> +field value supplied with the request does not identify a clock.
> +
> +For \field{struct virtio_rtc_resp_head}, the device MUST set the
> +\field{status} field to VIRTIO_RTC_S_EINVAL if the request values are
> +inconsistent with the specification and if the inconsistence is not
> +described by the requirements which stipulate status
> +VIRTIO_RTC_S_EOPNOTSUPP or VIRTIO_RTC_S_ENODEV.
> +
> +For \field{struct virtio_rtc_resp_head}, the device MUST set the
> +\field{status} field to VIRTIO_RTC_S_EINVAL if the request specified in
> +the request header through the \field{msg_type} field does not fit into
> +the device read-only part of the actual message.
> +
> +For \field{struct virtio_rtc_resp_head}, the device MUST set the
> +\field{status} field to VIRTIO_RTC_S_EINVAL if the response specified in
> +the request header through the \field{msg_type} field does not fit into
> +the device write-only part of the actual message, unless the
> +\field{status} field does not fit into the device write-only part.
> +
> +For \field{struct virtio_rtc_resp_head}, the device MUST NOT set the
> +\field{status} field if the \field{status} field does not fit into the
> +device write-only part.
> +
> +For \field{struct virtio_rtc_resp_head}, the device MUST set the
> +\field{status} field to VIRTIO_RTC_S_EIO if none of the previous
> +requirements in this document stipulated another \field{status}.
> +
> +If the device read-only part of a message M is bigger than the size of
> +the request specified for message M, the device MUST ignore the
> +additional space.
> +
> +If the device write-only part of a message M is bigger than the size of
> +the response specified for message M, the device MUST ignore the
> +additional space.
> +
> +The device MUST set \emph{reserved} fields in the device-writable part
> +of the message to zero.
> +
> +The device MUST set unnamed bits in \emph{flags} fields in the
> +device-writable part of the message to zero.
> +
> +After feature negotiation completion the device MUST NOT change the set
> +of clocks until device reset.
> +
> +The device SHOULD NOT change the set of clocks on a device reset after
> +the first device reset.
> +
> +The device MUST use non-negative integers, which are smaller than the
> +number of clocks, as clock identifiers.
> +
>  \subsubsection{Common Definitions}\label{sec:Device Types / RTC Device / Device Operation / Common Definitions}
>  
>  This section makes common definitions.
> @@ -253,7 +353,7 @@ \subsubsection{Control Requests}\label{sec:Device Types / RTC Device / Device Op
>  };
>  \end{lstlisting}
>  
> -Field \field{num_clocks} contains the number of clocks. A device
> +The \field{num_clocks} field contains the number of clocks. A device
>  provides zero or more clocks. Valid clock ids are those smaller than
>  \field{num_clocks}.
>  
> @@ -281,8 +381,8 @@ \subsubsection{Control Requests}\label{sec:Device Types / RTC Device / Device Op
>  zero or more clocks for a clock type.
>  
>  Clocks of type VIRTIO_RTC_CLOCK_UTC_SMEARED indicate the \emph{smearing
> -variant} through field \field{leap_second_smearing}. All other clocks
> -set \field{leap_second_smearing} to VIRTIO_RTC_SMEAR_UNSPECIFIED.
> +variant} through the \field{leap_second_smearing} field. All other
> +clocks set \field{leap_second_smearing} to VIRTIO_RTC_SMEAR_UNSPECIFIED.
>  
>  \item[VIRTIO_RTC_REQ_CROSS_CAP] discovers whether the device supports
>  cross-timestamping for a particular pair of clock and hardware counter.
> @@ -315,6 +415,103 @@ \subsubsection{Control Requests}\label{sec:Device Types / RTC Device / Device Op
>  
>  \end{description}
>  
> +\drivernormative{\paragraph}{Control Requests}{Device Types / RTC Device / Device Operation / Control Requests}
> +
> +For VIRTIO_RTC_REQ_CROSS_CAP, the driver MUST set \field{hw_counter} to
> +one of the hardware counter identifiers defined in this specification,
> +or to a value between 0xF0 and 0xFE.
> +
> +\devicenormative{\paragraph}{Control Requests}{Device Types / RTC Device / Device Operation / Control Requests}
> +
> +For any clock of type VIRTIO_RTC_CLOCK_UTC, the device MUST use the UTC
> +time standard (Coordinated Universal Time).
> +
> +For any clock of type VIRTIO_RTC_CLOCK_UTC_SMEARED or
> +VIRTIO_RTC_CLOCK_UTC_MAYBE_SMEARED, the device MUST use the UTC time
> +standard, insofar as the following requirements do not say otherwise.
> +
> +For any UTC-like clock, the device MUST use the time epoch of January 1,
> +1970, 00:00 UTC.
> +
> +For any UTC-like clock, the device MUST count seconds since the epoch
> +according to \hyperref[intro:EPOCH]{EPOCH}.
> +
> +For any clock of type VIRTIO_RTC_CLOCK_UTC, the device MUST apply a
> +positive leap second according to the UTC time standard by
> +instantaneously stepping the clock backwards by 1 s at the start of the
> +leap second.
> +
> +For any clock of type VIRTIO_RTC_CLOCK_UTC, the device MUST apply a
> +negative leap second according to the UTC time standard by
> +instantaneously stepping the clock forward by 1 s at the start of the
> +leap second.
> +
> +For any leap smearing clock, the device MUST NOT step the clock due to a
> +leap second.
> +
> +For any leap smearing clock, on a positive leap second, the device MUST
> +slow down the clock during part of the day containing the leap second
> +and/or part of the day after the leap second.
> +
> +For any leap smearing clock, on a negative leap second, the device MUST
> +speed up the clock during part of the day containing the leap second
> +and/or part of the day after the leap second.
> +
> +For any clock with smearing variant VIRTIO_RTC_SMEAR_NOON_LINEAR, on a
> +leap second, the device MUST change the frequency of the clock exactly
> +from noon prior to the leap second until noon after the leap second.
> +
> +For any clock with smearing variant VIRTIO_RTC_SMEAR_NOON_LINEAR, while
> +changing the frequency of the clock due to a positive leap second, the
> +device MUST decrease the frequency of the clock by $1/86400$.
> +
> +For any clock with smearing variant VIRTIO_RTC_SMEAR_NOON_LINEAR, while
> +changing the frequency of the clock due to a negative leap second, the
> +device MUST increase the frequency of the clock by $1/86400$.
> +
> +For any clock with smearing variant VIRTIO_RTC_SMEAR_UTC_SLS, on a leap
> +second, the device MUST change the frequency of the clock exactly during
> +the last 1000 seconds of the day with the leap second.
> +
> +For any clock with smearing variant VIRTIO_RTC_SMEAR_UTC_SLS, while
> +changing the frequency of the clock due to a positive leap second, the
> +device MUST decrease the frequency of the clock by 0.1\%.
> +
> +For any clock with smearing variant VIRTIO_RTC_SMEAR_UTC_SLS, while
> +changing the frequency of the clock due to a negative leap second, the
> +device MUST increase the frequency of the clock by 0.1\%.
> +
> +For any clock of type VIRTIO_RTC_CLOCK_UTC_MAYBE_SMEARED, the device MAY
> +deviate from the UTC standard with respect to leap second introduction.
> +
> +For any clock of type VIRTIO_RTC_CLOCK_TAI, the device MUST use the TAI
> +time standard (International Atomic Time).
> +
> +For any clock of type VIRTIO_RTC_CLOCK_TAI, the device MUST use the time
> +epoch of January 1, 1970, 00:00 TAI.
> +
> +For any clock of type VIRTIO_RTC_CLOCK_MONOTONIC, the device MUST use SI
> +seconds subdivisions.
> +
> +For any clock of type VIRTIO_RTC_CLOCK_MONOTONIC, the device MUST use an
> +epoch at a time instant before or during device reset.
> +
> +For VIRTIO_RTC_REQ_CLOCK_CAP, and clock types other than
> +VIRTIO_RTC_CLOCK_UTC_SMEARED, the device MUST set the
> +\field{leap_second_smearing} field to VIRTIO_RTC_SMEAR_UNSPECIFIED.
> +
> +For VIRTIO_RTC_REQ_CLOCK_CAP, and clock type
> +VIRTIO_RTC_CLOCK_UTC_SMEARED, the device MUST set the
> +\field{leap_second_smearing} field to VIRTIO_RTC_SMEAR_UNSPECIFIED,
> +VIRTIO_RTC_SMEAR_NOON_LINEAR, VIRTIO_RTC_SMEAR_UTC_SLS, or to a value
> +greater than or equal to 0xF0.
> +
> +For a VIRTIO_RTC_REQ_CROSS_CAP message M, the device MUST set the
> +VIRTIO_RTC_FLAG_CROSS_CAP flag in the \field{flags} field if the device
> +would respond to a VIRTIO_RTC_REQ_READ_CROSS message with the same
> +\field{hw_counter} and \field{clock_id} values as in M with status
> +VIRTIO_RTC_S_OK, and clear the flag otherwise.

I wonder if we could rewrite this sentence to make it more clear.

> +
>  \subsubsection{Read Requests}\label{sec:Device Types / RTC Device / Device Operation / Read Requests}
>  
>  Through \emph{read requests}, the driver requests clock readings from
> @@ -426,3 +623,70 @@ \subsubsection{Read Requests}\label{sec:Device Types / RTC Device / Device Opera
>  \ref{sec:Device Types / RTC Device / Device Operation / Common Definitions / Hardware Counters}.
>  
>  \end{description}
> +
> +\drivernormative{\paragraph}{Read Requests}{Device Types / RTC Device / Device Operation / Read Requests}
> +
> +For VIRTIO_RTC_REQ_READ_CROSS, the driver MUST set \field{hw_counter} to
> +one of the hardware counter identifiers defined in this specification,
> +or to a value between 0xF0 and 0xFE.
> +
> +\devicenormative{\paragraph}{Read Requests}{Device Types / RTC Device / Device Operation / Read Requests}
> +
> +The device SHOULD continuously support reading of all clocks once
> +DRIVER_OK has been set.
> +

I think you can rewrite as: "After DRIVER_OK has been set, the device
SHOULD continuously support reading of all clocks."

> +For any clock C and read requests \emph{A} and \emph{B} which read C,
> +\emph{A} being the message which the driver marks as available before
> +\emph{B}, the device MUST obtain the \field{clock_reading} value for the
> +message \emph{A} response before the \field{clock_reading} value for the
> +message \emph{B} response, or the device MUST obtain the same
> +\field{clock_reading} value for both \emph{A} and \emph{B}.
> +

I wonder how we can rewrite it without A, B, and C.

> +For any clock C, the device MUST mark all read requests reading C as
> +used in the total order in which the driver marked these messages as
> +available.
> +
> +For any clock C of type VIRTIO_RTC_CLOCK_MONOTONIC and read requests
> +\emph{A} and \emph{B} which read C, \emph{A} being the message which the
> +driver marks as available before \emph{B}, the device MUST set the
> +\field{clock_reading} value for the message \emph{B} response to a value
> +greater than or equal to the \field{clock_reading} value for the message
> +\emph{A} response.
> +
> +The device MUST support VIRTIO_RTC_REQ_READ for every clock.

I would start the sentence by:

"For every clock, ..."

> +
> +For VIRTIO_RTC_REQ_READ and for any clock type listed in this
> +specification, the device MUST use the nanosecond as unit for the
> +\field{clock_reading} field.
> +
> +For read requests, the device MUST obtain the \field{clock_reading}
> +response value after the read request is marked as available.

This is not clear. Who mark the read request available? I think ti is
the driver. The device cannot access anything in the available ring
without driver notification.

> +
> +For VIRTIO_RTC_REQ_READ_CROSS, the device MUST set
> +\field{counter_cycles} to a value which approximates the value which the
> +driver would have read from the hardware counter identified by
> +\field{hw_counter} at the time instant when the device read the
> +\field{clock_reading} value.
> +
> +For VIRTIO_RTC_REQ_READ_CROSS, the device SHOULD assume that the driver
> +reads the hardware counter identified by \field{hw_counter} through the
> +CPU which the driver enumerates as the first.
> +
> +For VIRTIO_RTC_REQ_READ_CROSS, the device MUST set \field{status} to a
> +value other than VIRTIO_RTC_S_OK if the device cannot determine the
> +approximate value which the driver would have read from the hardware
> +counter identified by \field{hw_counter} at the time instant when the
> +device read the \field{clock_reading} value.
> +
> +For any clock C, and VIRTIO_RTC_REQ_READ_CROSS messages \emph{A} and
> +\emph{B} which read C and which specify the same hardware counter
> +\emph{H} through the \field{hw_counter} field, \emph{A} being the
> +message which the driver marks as available before \emph{B}, the device
> +MUST set the \field{counter_cycles} value for \emph{B} to a value which
> +\emph{H} shows after the \field{counter_cycles} value of \emph{A}, or
> +the device MUST set the same \field{counter_cycles} value for \emph{A}
> +and \emph{B}.

I just rewrite this sentence as the following, WDYT?:

If two VIRTIO_RTC_REQ_READ_CROSS messages read the same clock using the
same hardware counter, and one message is made available before the
other, the device must do one of the following:

- Set the later message's counter_cycles to a value that the hardware
  counter shows after the earlier message's counter_cycles.
- Or, set both messages to have the same counter_cycles value.

> +
> +For VIRTIO_RTC_REQ_READ_CROSS and for any clock type listed in this
> +specification, the device MUST use the nanosecond as unit for the
> +\field{clock_reading} field.
> diff --git a/device-types/rtc/device-conformance.tex b/device-types/rtc/device-conformance.tex
> new file mode 100644
> index 000000000000..4303cd450542
> --- /dev/null
> +++ b/device-types/rtc/device-conformance.tex
> @@ -0,0 +1,9 @@
> +\conformance{\subsection}{RTC Device Conformance}\label{sec:Conformance / Device Conformance / RTC Device Conformance}
> +
> +An RTC device MUST conform to the following normative statements:
> +
> +\begin{itemize}
> +\item \ref{devicenormative:Device Types / RTC Device / Device Operation}
> +\item \ref{devicenormative:Device Types / RTC Device / Device Operation / Control Requests}
> +\item \ref{devicenormative:Device Types / RTC Device / Device Operation / Read Requests}
> +\end{itemize}
> diff --git a/device-types/rtc/driver-conformance.tex b/device-types/rtc/driver-conformance.tex
> new file mode 100644
> index 000000000000..689c18d158d0
> --- /dev/null
> +++ b/device-types/rtc/driver-conformance.tex
> @@ -0,0 +1,9 @@
> +\conformance{\subsection}{RTC Driver Conformance}\label{sec:Conformance / Driver Conformance / RTC Driver Conformance}
> +
> +An RTC driver MUST conform to the following normative statements:
> +
> +\begin{itemize}
> +\item \ref{drivernormative:Device Types / RTC Device / Device Operation}
> +\item \ref{drivernormative:Device Types / RTC Device / Device Operation / Control Requests}
> +\item \ref{drivernormative:Device Types / RTC Device / Device Operation / Read Requests}
> +\end{itemize}
> -- 
> 2.43.0
> 

Re: [PATCH v8 3/4] virtio-rtc: Add alarm feature

[Matias Ezequiel Vara Larsen]

On Thu, Mar 06, 2025 at 10:51:11AM +0100, Peter Hilber wrote:
> Add the VIRTIO_RTC_F_ALARM feature (without normative statements).
> 
> The intended use case is: A driver needs to react when an alarm time has
> been reached, but at alarm time, the driver may be in a sleep state or
> powered off. The alarm feature can resume and notify the driver in this
> case. Alarms may be retained across device resets (including reset on
> boot).
> 
> Peculiarities
> -------------
> 
> Unlike usual alarm clocks, a virtio-rtc alarm-capable clock may step
> autonomously at any time: An alarm may change back from "expired" to
> "not expired" before the driver has started processing an alarm
> notification.
> 
> To address the above, and the device resets, define "alarm expiration"
> in such a way that the driver always has a chance to react to an alarm,
> and make the device always responsible for notifying the driver about an
> alarm expiration.
> 
> The VIRTIO_RTC_REQ_SET_ALARM_ENABLED request is there so that the Linux
> ioctls RTC_AIE_ON and RTC_AIE_OFF only need to emit one request.
> 
> Signed-off-by: Peter Hilber <quic_philber@quicinc.com>
> ---
> 
> Notes:
>     v8:
>     
>     - Explicitly describe alarm enabled status, where relevant (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".
>     
>     - Change "once" to "when" (Matias Ezequiel Vara Larsen).
>     
>     v7:
>     
>     - Change flag numeric value due to removing leap second indication.
>     
>     v5:
>     
>     - Reformat.
>     
>     v4:
>     
>     - Change requirements so that driver can reset alarm to clean slate, and
>       document how driver can achieve this (Cornelia Hell, Jason Wang) [1].
>     
>     - Require device to support all expressible alarm times.
>     
>     - Formatting and wording improvements.
>     
>     [1] https://lore.kernel.org/all/2ae67401-a8f5-4686-9321-cb3105df594d@opensynergy.com/
> 
>  device-types/rtc/description.tex | 262 ++++++++++++++++++++++++++++++-
>  1 file changed, 260 insertions(+), 2 deletions(-)
> 
> diff --git a/device-types/rtc/description.tex b/device-types/rtc/description.tex
> index f2a3907de511..93bcf178b042 100644
> --- a/device-types/rtc/description.tex
> +++ b/device-types/rtc/description.tex
> @@ -4,6 +4,7 @@ \section{RTC Device}\label{sec:Device Types / RTC Device}
>  time. The device can provide different clocks, e.g.\ for the UTC or TAI
>  time standards, or for physical time elapsed since some past epoch. The
>  driver can read the clocks with simple or more accurate methods.
> +Optionally, the driver can set an alarm.
>  
>  \subsection{Device ID}\label{sec:Device Types / RTC Device / Device ID}
>  
> @@ -13,13 +14,23 @@ \subsection{Virtqueues}\label{sec:Device Types / RTC Device / Virtqueues}
>  
>  \begin{description}
>  \item[0] requestq
> +\item[1] alarmq
>  \end{description}
>  
>  The driver enqueues requests to the requestq.
>  
> +Through the alarmq, the device notifies the driver about alarm
> +expirations. The alarmq exists only if VIRTIO_RTC_F_ALARM was
> +negotiated.
> +
>  \subsection{Feature bits}\label{sec:Device Types / RTC Device / Feature bits}
>  
> -No device-specific feature bits are defined yet.
> +\begin{description}
> +\item[VIRTIO_RTC_F_ALARM (0)] Device supports alarm.
> +\end{description}
> +
> +VIRTIO_RTC_F_ALARM determines whether the device supports setting an
> +alarm for some of the clocks.
>  
>  \subsection{Device configuration layout}\label{sec:Device Types / RTC Device / Device configuration layout}
>  
> @@ -373,7 +384,8 @@ \subsubsection{Control Requests}\label{sec:Device Types / RTC Device / Device Op
>          struct virtio_rtc_resp_head head;
>          u8 type;
>          u8 leap_second_smearing;
> -        u8 reserved[6];
> +        u8 flags;
> +        u8 reserved[5];
>  };
>  \end{lstlisting}
>  
> @@ -384,6 +396,15 @@ \subsubsection{Control Requests}\label{sec:Device Types / RTC Device / Device Op
>  variant} through the \field{leap_second_smearing} field. All other
>  clocks set \field{leap_second_smearing} to VIRTIO_RTC_SMEAR_UNSPECIFIED.
>  
> +The \field{flags} field provides the following information:
> +
> +\begin{lstlisting}
> +#define VIRTIO_RTC_FLAG_ALARM_CAP               (1 << 0)
> +\end{lstlisting}
> +
> +If VIRTIO_RTC_F_ALARM was negotiated, the VIRTIO_RTC_FLAG_ALARM_CAP flag
> +indicates that the clock supports an alarm.
> +
>  \item[VIRTIO_RTC_REQ_CROSS_CAP] discovers whether the device supports
>  cross-timestamping for a particular pair of clock and hardware counter.
>  
> @@ -690,3 +711,240 @@ \subsubsection{Read Requests}\label{sec:Device Types / RTC Device / Device Opera
>  For VIRTIO_RTC_REQ_READ_CROSS and for any clock type listed in this
>  specification, the device MUST use the nanosecond as unit for the
>  \field{clock_reading} field.
> +
> +\subsubsection{Alarm Operation}\label{sec:Device Types / RTC Device / Device Operation / Alarm Operation}
> +
> +Through the optional alarm feature, the driver can set an alarm time. On
> +alarm expiration, the device notifies the driver. On alarm expiration,
> +the device may also wake up the driver, while the driver is in a sleep
> +state, or while the driver is powered off. How this is done is beyond
> +the scope of the specification. The driver can set one alarm time per
> +clock, if the clock supports this.
> +
> +The device may retain alarm times across device resets.\footnote{Drivers
> +        may reset the device on boot or on resume from sleep state. It
> +        can make sense for the device to retain the alarm time then,
> +        similar to other alarm clocks.}
> +
> +The alarm feature, and the associated alarmq for notifications from the
> +device, are available if VIRTIO_RTC_F_ALARM was negotiated. 

"If the VIRTIO_xxx has been negotiated, ..."

> In addition,
> +if the driver previously set an alarm time, even if the device no longer
> +both
> +
> +\begin{itemize}
> +\item is live and
> +\item has negotiated VIRTIO_RTC_F_ALARM,
> +\end{itemize}
> +
> +the device may still execute implementation-specific actions on alarm
> +expiration.
> +
> +An alarm expires

I think you can add the "when" after "expires" and then remove it
afterward.

> +
> +\begin{itemize}
> +\item when the associated clock progresses (also: steps) from a time
> +        prior to the alarm time to the alarm time, or to a time after
> +        the alarm time, while the alarm is enabled, or
> +
> +\item when the driver sets an alarm time which is not in the future,
> +        while also setting the alarm to enabled, or
> +
> +\item when the driver sets the alarm to enabled, and the alarm time is
> +        not in the future, or
> +
> +\item when the device is reset, if the alarm time is retained and not in
> +        the future, and if the alarm is enabled.\footnote{The device is
> +                always responsible for detecting alarm expiration
> +                events. This avoids that the driver needs to reason
> +                about when it shall poll for alarm expiration.}
> +\end{itemize}
> +
> +When an alarm expires, the driver can disable it. Otherwise, the alarm
> +expires each time when one of the above expiration events occurs, even
> +if it occurred before.\footnote{This avoids that the driver may
> +        miss an alarm when the clock steps backwards after alarm
> +        expiration, but before the driver has resumed operation. This
> +        also facilitates distinct drivers using the same device,
> +        e.g.\ a driver in the bootloader, and a driver in the OS.}
> +
> +On alarm expiration, the device executes the alarm actions. The alarm
> +actions are:
> +
> +\begin{itemize}
> +\item The device notifies the driver through the alarmq. If the device
> +        is not live, or no buffers are available in the alarmq, the
> +        device will notify once the device is live and buffers are
> +        available.
> +
> +\item Optionally, the device executes other, implementation-specific,
> +        actions. The device may execute those immediately, regardless of
> +        the device state.
> +\end{itemize}
> +

I think that, on alarm expiration, you can remove the optionally part
and then just talk about alarm expiration thus removing the `alarm
actions` wording.  

> +An alarm \emph{expiration} becomes obsolete
> +
> +\begin{itemize}
> +\item when the driver disables the alarm, or
> +
> +\item when the driver sets an alarm time, or
> +
> +\item when the clock jumps backwards, before the alarm time, or
> +
> +\item when another alarm expiration event happens.
> +\end{itemize}
> +
> +If an alarm expiration becomes obsolete, it is unspecified which alarm
> +actions the device executes for this alarm expiration, and the device
> +stops executing these alarm actions after a grace period.

Can't you leave this paragraph implementation-specific and thus
removing it completely?

> +
> +The device supports all alarm time values which the driver can request
> +through alarm control requests.
> +
> +Initially, the alarm time is the epoch of the clock ($0$), and the alarm
> +is disabled.

I would rewrite it as:

"Every alarm initializes with an alarm time to 0 and disabled."

> +
> +Alarms set prior to reset may cause unwanted alarm expiration
> +notifications, and information leakage, after the reset. To prevent both
> +issues, the driver can do the following after the reset, for each clock
> +which supports alarm:
> +
> +\begin{enumerate}
> +\item Send a VIRTIO_RTC_REQ_SET_ALARM message, with \field{alarm_time}
> +        set to 0, and \field{flags} set to 0.
> +
> +\item Wait until the device marks the VIRTIO_RTC_REQ_SET_ALARM message
> +        as used, with status VIRTIO_RTC_S_OK.
> +\end{enumerate}
> +
> +To prevent the above issues, the driver also marks buffers in the alarmq
> +as available only after completing the above steps for all clocks.
> +
> +\paragraph{Alarm Control Requests}
> +
> +If VIRTIO_RTC_F_ALARM is negotiated,
> +
> +\begin{itemize}
> +\item the driver can determine if a clock supports an alarm through the
> +        VIRTIO_RTC_FLAG_ALARM_CAP flag in the VIRTIO_RTC_REQ_CLOCK_CAP
> +        response,
> +
> +\item the driver can enqueue the alarm control requests into the
> +        requestq: VIRTIO_RTC_REQ_READ_ALARM, VIRTIO_RTC_REQ_SET_ALARM,
> +        and VIRTIO_RTC_REQ_SET_ALARM_ENABLED.
> +\end{itemize}
> +
> +The unit of all \field{alarm_time} fields is 1 nanosecond.
> +
> +\begin{description}
> +\item[VIRTIO_RTC_REQ_READ_ALARM] reads the current alarm.
> +
> +\begin{lstlisting}
> +#define VIRTIO_RTC_REQ_READ_ALARM 0x1003 /* message type */
> +
> +struct virtio_rtc_req_read_alarm {
> +        struct virtio_rtc_req_head head;
> +        le16 clock_id;
> +        u8 reserved[6];
> +};
> +
> +struct virtio_rtc_resp_read_alarm {
> +        struct virtio_rtc_resp_head head;
> +        le64 alarm_time;
> +#define VIRTIO_RTC_FLAG_ALARM_ENABLED   (1 << 0)
> +        u8 flags;
> +        u8 reserved[7];
> +};
> +\end{lstlisting}
> +
> +\field{clock_id} identifies the alarm through its associated clock. The
> +\field{alarm_time} field returns the alarm time. In the \field{flags}
> +field, VIRTIO_RTC_FLAG_ALARM_ENABLED indicates whether the alarm is
> +enabled.
> +
> +\item[VIRTIO_RTC_REQ_SET_ALARM] sets the alarm.
> +
> +\begin{lstlisting}
> +#define VIRTIO_RTC_REQ_SET_ALARM 0x1004 /* message type */
> +
> +struct virtio_rtc_req_set_alarm {
> +        struct virtio_rtc_req_head head;
> +        le64 alarm_time;
> +        le16 clock_id;
> +        /* flag: VIRTIO_RTC_FLAG_ALARM_ENABLED */
> +        u8 flags;
> +        u8 reserved[5];
> +};
> +
> +struct virtio_rtc_resp_set_alarm {
> +        struct virtio_rtc_resp_head head;
> +        /* no response params */
> +};
> +\end{lstlisting}
> +
> +\field{clock_id} identifies the alarm through its associated clock. The
> +\field{alarm_time} field sets the alarm time. If
> +VIRTIO_RTC_FLAG_ALARM_ENABLED is set in the \field{flags} field, the
> +device enables the alarm; otherwise, the device disables the alarm.
> +
> +\item[VIRTIO_RTC_REQ_SET_ALARM_ENABLED] enables or disables the alarm.
> +
> +\begin{lstlisting}
> +#define VIRTIO_RTC_REQ_SET_ALARM_ENABLED 0x1005 /* message type */
> +
> +struct virtio_rtc_req_set_alarm_enabled {
> +        struct virtio_rtc_req_head head;
> +        le16 clock_id;
> +        /* flag: VIRTIO_RTC_FLAG_ALARM_ENABLED */
> +        u8 flags;
> +        u8 reserved[5];
> +};
> +
> +struct virtio_rtc_resp_set_alarm_enabled {
> +        struct virtio_rtc_resp_head head;
> +        /* no response params */
> +};
> +\end{lstlisting}
> +
> +\field{clock_id} identifies the alarm through its associated clock. If
> +VIRTIO_RTC_FLAG_ALARM_ENABLED is set in the \field{flags} field, the
> +device enables the alarm; otherwise, the device disables the alarm.
> +
> +When processing this request, the device retains the alarm time.
> +
> +\end{description}
> +
> +\paragraph{Alarm Notifications}
> +
> +If the alarmq is present, the driver should make buffers available in
> +the alarmq, which the device uses for alarm notification messages. All
> +alarmq fields are device-writable. The alarmq uses a common notification
> +header.
> +
> +\begin{lstlisting}
> +/* common notification header */
> +struct virtio_rtc_notif_head {
> +        le16 msg_type;
> +        u8 reserved[6];
> +};
> +\end{lstlisting}
> +
> +The \field{msg_type} field identifies the message type.
> +
> +\begin{description}
> +\item[VIRTIO_RTC_NOTIF_ALARM] notifies the driver about an alarm
> +        expiration.
> +
> +\begin{lstlisting}
> +#define VIRTIO_RTC_NOTIF_ALARM 0x2000 /* message type */
> +
> +struct virtio_rtc_notif_alarm {
> +        struct virtio_rtc_notif_head head;
> +        le16 clock_id;
> +        u8 reserved[6];
> +};
> +\end{lstlisting}
> +
> +\end{description}
> +
> +\field{clock_id} identifies the expired alarm through its associated
> +clock.
> -- 
> 2.43.0
> 

Re: [PATCH v8 4/4] virtio-rtc: Add normative statements for alarm feature

[Matias Ezequiel Vara Larsen]

On Thu, Mar 06, 2025 at 10:51:12AM +0100, Peter Hilber wrote:
> Add the normative statements for the alarm feature added previously.
> 
> Signed-off-by: Peter Hilber <quic_philber@quicinc.com>
> ---
> 
> Notes:
>     v8:
>     
>     - Explicitly describe alarm enabled status, where relevant (Matias
>       Ezequiel Vara Larsen).
>     
>     - Simplify requirement about clock readings after alarm (Matias Ezequiel
>       Vara Larsen).
>     
>     - Move requirements to serve alarm expiration events before requirements
>       about stopping to serve (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".
>     
>     v7:
>     
>     - Remove inadvertent v6 changes, which should have been part of
>       preceding patches.
>     
>     v4:
>     
>     - Update normative statements to match v4 changes to non-normative
>       statements (patch 3).
>     
>     - Driver should read clock to confirm that alarm has expired.
>     
>     - Formatting and wording improvements.
> 
>  device-types/rtc/description.tex        | 150 ++++++++++++++++++++++++
>  device-types/rtc/device-conformance.tex |   4 +
>  device-types/rtc/driver-conformance.tex |   2 +
>  3 files changed, 156 insertions(+)
> 
> diff --git a/device-types/rtc/description.tex b/device-types/rtc/description.tex
> index 93bcf178b042..91afae7c2110 100644
> --- a/device-types/rtc/description.tex
> +++ b/device-types/rtc/description.tex
> @@ -32,6 +32,11 @@ \subsection{Feature bits}\label{sec:Device Types / RTC Device / Feature bits}
>  VIRTIO_RTC_F_ALARM determines whether the device supports setting an
>  alarm for some of the clocks.
>  
> +\devicenormative{\subsubsection}{Feature bits}{Device Types / RTC Device / Feature bits}
> +
> +The device SHOULD offer VIRTIO_RTC_F_ALARM if the device can support
> +setting an alarm for any of its clocks.
> +

I think you can remove `can` here.

>  \subsection{Device configuration layout}\label{sec:Device Types / RTC Device / Device configuration layout}
>  
>  There is no configuration data for the device.
> @@ -712,6 +717,11 @@ \subsubsection{Read Requests}\label{sec:Device Types / RTC Device / Device Opera
>  specification, the device MUST use the nanosecond as unit for the
>  \field{clock_reading} field.
>  
> +If the device sent an alarm notification for clock C with alarm time A,
> +the device MUST, for all read requests of C which the driver marks as
> +available after the notification, return a \field{clock_reading} which
> +does not precede A (except if C stepped backwards to before A).
> +
>  \subsubsection{Alarm Operation}\label{sec:Device Types / RTC Device / Device Operation / Alarm Operation}
>  
>  Through the optional alarm feature, the driver can set an alarm time. On
> @@ -819,6 +829,76 @@ \subsubsection{Alarm Operation}\label{sec:Device Types / RTC Device / Device Ope
>  To prevent the above issues, the driver also marks buffers in the alarmq
>  as available only after completing the above steps for all clocks.
>  
> +\devicenormative{\paragraph}{Alarm Operation}{Device Types / RTC Device / Device Operation / Alarm Operation}
> +
> +The device MAY retain both alarm time and alarm enabled status of a
> +clock across a device reset.
> +
> +If the device did not retain alarm time and alarm enabled status of a
> +clock across a device reset, the device MUST initialize alarm time to 0.
> +
> +If the device did not retain alarm time and alarm enabled status of a
> +clock across a device reset, the device MUST disable the alarm.
> +
> +If VIRTIO_RTC_F_ALARM was negotiated, the device MUST support the alarm
> +messages, VIRTIO_RTC_REQ_READ_ALARM, VIRTIO_RTC_REQ_SET_ALARM,
> +VIRTIO_RTC_REQ_SET_ALARM_ENABLED, and VIRTIO_RTC_NOTIF_ALARM, for one or
> +more clocks.
> +
> +If VIRTIO_RTC_F_ALARM was not negotiated, the device MUST NOT support the
> +alarm messages.

`has been negotiated ...` I think there are others below.

> +
> +The device MUST set the VIRTIO_RTC_FLAG_ALARM_CAP flag in \field{struct
> +virtio_rtc_resp_clock_cap.flags} if the respective clock supports alarm
> +messages, and clear the flag otherwise.
> +
> +The device MUST consider it an alarm expiration event when the
> +associated clock progresses (also: steps) from a time prior to the alarm
> +time to the alarm time, or to a time after the alarm time, while the
> +alarm is enabled.
> +
> +The device MUST consider it an alarm expiration event when the
> +driver sets an alarm time which the associated clock has already reached
> +or passed, while also setting the alarm to enabled.
> +
> +The device MUST consider it an alarm expiration event when the driver
> +sets the alarm to enabled, if the clock has already reached or passed
> +the alarm time.
> +
> +If the device retained alarm time and alarm enabled status of a clock
> +across a device reset, and the clock has already reached or passed the
> +alarm time, the device MUST consider this device reset an alarm
> +expiration event, if the alarm is enabled.
> +
> +If an alarm expiration event E happens, the device MUST start serving
> +the alarm expiration event E.
> +
> +If the device is currently serving an alarm expiration event E, the
> +device MUST send a single VIRTIO_RTC_NOTIF_ALARM notification for E, as
> +soon as an alarmq buffer is available for this purpose.
> +
> +While the device is serving an alarm expiration event, the device MAY
> +execute implementation-specific alarm actions.
> +
> +The device MAY ignore the device status when executing
> +implementation-specific alarm actions.
> +
> +The device MAY ignore whether VIRTIO_RTC_F_ALARM was negotiated when
> +executing implementation-specific alarm actions.
> +
> +If the driver successfully requests VIRTIO_RTC_REQ_SET_ALARM, or
> +VIRTIO_RTC_REQ_SET_ALARM_ENABLED, for clock C, the device MUST stop
> +serving any previous alarm expiration event for C before the device
> +marks the message as used.
> +
> +If a clock C steps to a time previous to C's alarm time, the device MUST
> +stop serving any previous alarm expiration event for C, within a grace
> +period.
> +
> +If an alarm expiration event happens for clock C, the device MUST stop
> +serving any previous alarm expiration event for C, within a grace
> +period.
> +
>  \paragraph{Alarm Control Requests}
>  
>  If VIRTIO_RTC_F_ALARM is negotiated,
> @@ -913,6 +993,59 @@ \subsubsection{Alarm Operation}\label{sec:Device Types / RTC Device / Device Ope
>  
>  \end{description}
>  
> +\drivernormative{\subparagraph}{Alarm Control Requests}{Device Types / RTC Device / Device Operation / Alarm Operation / Alarm Control Requests}
> +
> +For VIRTIO_RTC_REQ_SET_ALARM and for any clock type listed in this
> +specification, the driver MUST use the nanosecond as unit for the
> +\field{alarm_time} field.
> +
> +\devicenormative{\subparagraph}{Alarm Control Requests}{Device Types / RTC Device / Device Operation / Alarm Operation / Alarm Control Requests}
> +
> +If VIRTIO_RTC_F_ALARM was not negotiated, the device MUST set status
> +VIRTIO_RTC_S_ENODEV for VIRTIO_RTC_REQ_READ_ALARM,
> +VIRTIO_RTC_REQ_SET_ALARM, and VIRTIO_RTC_REQ_SET_ALARM_ENABLED.
> +
> +If the clock does not support alarm messages, the device MUST set status
> +VIRTIO_RTC_S_ENODEV for VIRTIO_RTC_REQ_READ_ALARM,
> +VIRTIO_RTC_REQ_SET_ALARM, and VIRTIO_RTC_REQ_SET_ALARM_ENABLED.
> +
> +For VIRTIO_RTC_REQ_READ_ALARM, the device MUST set the
> +\field{alarm_time} field to the alarm time.
> +
> +For VIRTIO_RTC_REQ_READ_ALARM, the device MUST set the
> +VIRTIO_RTC_FLAG_ALARM_ENABLED flag in the \field{flags} field if the
> +alarm is enabled, and clear the flag otherwise.
> +
> +For VIRTIO_RTC_REQ_READ_ALARM and for any clock type listed in this
> +specification, the device MUST use the nanosecond as unit for the
> +\field{alarm_time} field.
> +
> +For VIRTIO_RTC_REQ_SET_ALARM, the device MUST accept any
> +\field{alarm_time} value.
> +
> +If the device sets status VIRTIO_RTC_S_OK for VIRTIO_RTC_REQ_SET_ALARM,
> +the device MUST set the alarm time to the time represented by the
> +\field{alarm_time} field.
> +
> +If the device sets status VIRTIO_RTC_S_OK for VIRTIO_RTC_REQ_SET_ALARM,
> +the device MUST enable the alarm if VIRTIO_RTC_FLAG_ALARM_ENABLED is set
> +in the \field{flags} field.
> +
> +If the device sets status VIRTIO_RTC_S_OK for VIRTIO_RTC_REQ_SET_ALARM,
> +the device MUST disable the alarm if VIRTIO_RTC_FLAG_ALARM_ENABLED is
> +cleared in the \field{flags} field.
> +
> +If the device sets status VIRTIO_RTC_S_OK for
> +VIRTIO_RTC_REQ_SET_ALARM_ENABLED, the device MUST enable the alarm if
> +VIRTIO_RTC_FLAG_ALARM_ENABLED is set in the \field{flags} field.
> +
> +If the device sets status VIRTIO_RTC_S_OK for
> +VIRTIO_RTC_REQ_SET_ALARM_ENABLED, the device MUST disable the alarm if
> +VIRTIO_RTC_FLAG_ALARM_ENABLED is cleared in the \field{flags} field.
> +
> +If the device sets status VIRTIO_RTC_S_OK for
> +VIRTIO_RTC_REQ_SET_ALARM_ENABLED, the device MUST retain the alarm time.
> +
>  \paragraph{Alarm Notifications}
>  
>  If the alarmq is present, the driver should make buffers available in
> @@ -948,3 +1081,20 @@ \subsubsection{Alarm Operation}\label{sec:Device Types / RTC Device / Device Ope
>  
>  \field{clock_id} identifies the expired alarm through its associated
>  clock.
> +
> +\drivernormative{\subparagraph}{Alarm Notifications}{Device Types / RTC Device / Device Operation / Alarm Operation / Alarm Notifications}
> +
> +If VIRTIO_RTC_F_ALARM was negotiated, the driver SHOULD populate the
> +alarmq with buffers.
> +
> +The driver MUST allocate enough space for any alarmq message in the
> +device-writable part of an alarmq buffer.
> +
> +If the driver receives a VIRTIO_RTC_NOTIF_ALARM notification, the driver
> +SHOULD read the associated clock instead of assuming that the alarm time
> +which the driver set last has been reached.
> +
> +\devicenormative{\subparagraph}{Alarm Notifications}{Device Types / RTC Device / Device Operation / Alarm Operation / Alarm Notifications}
> +
> +The device MUST NOT send a VIRTIO_RTC_NOTIF_ALARM notification for a
> +clock which does not support alarm messages.
> diff --git a/device-types/rtc/device-conformance.tex b/device-types/rtc/device-conformance.tex
> index 4303cd450542..705691a7319f 100644
> --- a/device-types/rtc/device-conformance.tex
> +++ b/device-types/rtc/device-conformance.tex
> @@ -3,7 +3,11 @@
>  An RTC device MUST conform to the following normative statements:
>  
>  \begin{itemize}
> +\item \ref{devicenormative:Device Types / RTC Device / Feature bits}
>  \item \ref{devicenormative:Device Types / RTC Device / Device Operation}
>  \item \ref{devicenormative:Device Types / RTC Device / Device Operation / Control Requests}
>  \item \ref{devicenormative:Device Types / RTC Device / Device Operation / Read Requests}
> +\item \ref{devicenormative:Device Types / RTC Device / Device Operation / Alarm Operation}
> +\item \ref{devicenormative:Device Types / RTC Device / Device Operation / Alarm Operation / Alarm Control Requests}
> +\item \ref{devicenormative:Device Types / RTC Device / Device Operation / Alarm Operation / Alarm Notifications}
>  \end{itemize}
> diff --git a/device-types/rtc/driver-conformance.tex b/device-types/rtc/driver-conformance.tex
> index 689c18d158d0..a87c4cde99c2 100644
> --- a/device-types/rtc/driver-conformance.tex
> +++ b/device-types/rtc/driver-conformance.tex
> @@ -6,4 +6,6 @@
>  \item \ref{drivernormative:Device Types / RTC Device / Device Operation}
>  \item \ref{drivernormative:Device Types / RTC Device / Device Operation / Control Requests}
>  \item \ref{drivernormative:Device Types / RTC Device / Device Operation / Read Requests}
> +\item \ref{drivernormative:Device Types / RTC Device / Device Operation / Alarm Operation / Alarm Control Requests}
> +\item \ref{drivernormative:Device Types / RTC Device / Device Operation / Alarm Operation / Alarm Notifications}
>  \end{itemize}
> -- 
> 2.43.0
> 

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

[Matias Ezequiel Vara Larsen]

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
> 

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

[Peter Hilber]

On Wed, Apr 16, 2025 at 03:02:51PM +0200, Matias Ezequiel Vara Larsen wrote:
> 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.

Hi Matias,

not sure which patches you did not address. I got your replies for all 4
patches. Is it the Linux kernel driver patches?

Thanks for the comments,

Peter

> 
> 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
> > 
> 

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

[Matias Ezequiel Vara Larsen]

On Wed, Apr 16, 2025 at 4:45 PM Peter Hilber <quic_philber@quicinc.com> wrote:
>
> On Wed, Apr 16, 2025 at 03:02:51PM +0200, Matias Ezequiel Vara Larsen wrote:
> > 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.
>
> Hi Matias,
>
> not sure which patches you did not address. I got your replies for all 4
> patches. Is it the Linux kernel driver patches?
>

No, sorry I meant that I could not cover all the sections in the
patches. I think I stopped at Device Requirements: Alarm Operation.

Matias

> Thanks for the comments,
>
> Peter
>
> >
> > 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
> > >
> >
>

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

[Michael S. Tsirkin]

On Thu, Mar 06, 2025 at 10:51:09AM +0100, Peter Hilber wrote:
> The virtio-rtc device provides information about current time through
> one or more clocks. As such, it is a Real-Time Clock (RTC) device.
> 
> The normative statements for this device follow in the next patch.
> 
> For this device, there is an RFC Linux kernel driver which is being
> upstreamed, and a proprietary device implementation.
> 
> Miscellaneous
> -------------
> 
> The spec does not specify how a driver should interpret clock readings,
> esp. also not how to perform clock synchronization.
> 
> The device uses the "Timer/Clock" device id which is already part of the
> specification. This device id was registered a long time ago and should
> be unused according to the author's information. The name "RTC" was
> determined to be the best for a device which focuses on current time.
> 
> Signed-off-by: Peter Hilber <quic_philber@quicinc.com>
> ---
> 
> Notes:
>     v8:
>     
>     - Change word order from "field X" to "the X field" (Matias Ezequiel
>       Vara Larsen).
>     
>     - Split up sentences about implementation-specific definitions (Matias
>       Ezequiel Vara Larsen).
>     
>     v7:
>     
>     - Remove leap second and performance indications from struct
>       virtio_rtc_resp_read_cross. Remove backing definitions.
>     
>     - Add wording change which was previously mistakenly placed in last
>       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 [8].
>     
>     - Add dedicated clock types for UTC leap second smearing (David
>       Woodhouse).
>     
>     - Extend leap second indications.
>     
>     - Split UTC-TAI offset and fractional offset due to smearing (David
>       Woodhouse).
>     
>     - Remove requirement that TAI offset must not be a whole second while
>       clock is being smeared.
>     
>     - Align bit widths, and some names, with '[RFC PATCH v4] ptp: Add
>       vDSO-style vmclock support' [8].
>     
>     - 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.
>     
>     v4:
>     
>     - Drop distinction of Arm Generic Timer virtual and physical counter [7].
>     
>     - Add requirement that device should assume that driver reads clock from
>       first vCPU (David Woodhouse) [6].
>     
>     - Formatting and wording improvements.
>     
>     v3:
>     
>     - Address comments from Parav Pandit.
>     
>     - Split off normative requirements into a second commit [2].
>     
>     - Merge readq and controlq into requestq [3].
>     
>     - Don't guard cross-timestamping with feature bit [3].
>     
>     - Pad request headers to 64 bit [2].
>     
>     - Rename Virtio status codes to match UNIX error names [2].
>     
>     - Avoid Virtio status code clashes with net controlq ack values.
>     
>     - Reword to refer more to "requests", rather than "messages" [2].
>     
>     - Rephrase some sentences [2].
>     
>     - Use integer data types without "__" prefixes [2].
>     
>     - Reduce clock id width to 16 bits [5].
>     
>     - Make VIRTIO_RTC_FLAG_CROSS_CAP a bit mask rather than a bit index.
>     
>     v2:
>     
>     - Address comments from Cornelia Huck.
>     
>     - Add VIRTIO_RTC_M_CROSS_CAP message [1].
>     
>     - Fix various minor issues and improve wording [1].
>     
>     - Add several clarifications regarding device error statuses.
>     
>     [1] https://lists.oasis-open.org/archives/virtio-comment/202304/msg00523.html
>     [2] https://lore.kernel.org/virtio-comment/b59a7dda-06fe-cff9-df61-b90aa4e50836@opensynergy.com/t/#mffb93800fea11d6dda9e151078abedd6ff1c0f1e
>     [3] https://lore.kernel.org/virtio-comment/b59a7dda-06fe-cff9-df61-b90aa4e50836@opensynergy.com/t/#m94efd0aa9b9c2b96a246b79ef8bfc3bf64ebe791
>     [4] https://lore.kernel.org/lkml/20230630171052.985577-1-peter.hilber@opensynergy.com/T/#m65fa1d715933360498c4e33d7225e4220215a9d6
>     [5] https://lore.kernel.org/virtio-comment/b59a7dda-06fe-cff9-df61-b90aa4e50836@opensynergy.com/t/#mf00ce330228c28556d735eb9597469048c5d8b62
>     [6] https://lore.kernel.org/lkml/d796d9a5-8eda-4528-a6d8-1c4eba24aa1e@opensynergy.com/
>     [7] https://lore.kernel.org/all/20231218064253.9734-2-peter.hilber@opensynergy.com/
>     [8] https://lore.kernel.org/lkml/20240708092924.1473461-1-dwmw2@infradead.org/
> 
>  content.tex                      |   3 +-
>  device-types/rtc/description.tex | 428 +++++++++++++++++++++++++++++++
>  introduction.tex                 |   6 +
>  3 files changed, 436 insertions(+), 1 deletion(-)
>  create mode 100644 device-types/rtc/description.tex
> 
> diff --git a/content.tex b/content.tex
> index 67b1bf3c35ab..b1d93a8aebb4 100644
> --- a/content.tex
> +++ b/content.tex
> @@ -684,7 +684,7 @@ \chapter{Device Types}\label{sec:Device Types}
>  \hline
>  16         &   GPU device       \\
>  \hline
> -17         &   Timer/Clock device \\
> +17         &   RTC (Timer/Clock) device \\


Do you want to change it to Real Time Clock here then?

>  \hline
>  18         &   Input device \\
>  \hline
> @@ -776,6 +776,7 @@ \chapter{Device Types}\label{sec:Device Types}
>  \input{device-types/pmem/description.tex}
>  \input{device-types/can/description.tex}
>  \input{device-types/spi/description.tex}
> +\input{device-types/rtc/description.tex}
>  
>  \chapter{Reserved Feature Bits}\label{sec:Reserved Feature Bits}
>  
> diff --git a/device-types/rtc/description.tex b/device-types/rtc/description.tex
> new file mode 100644
> index 000000000000..5d8cf91a6991
> --- /dev/null
> +++ b/device-types/rtc/description.tex
> @@ -0,0 +1,428 @@
> +\section{RTC Device}\label{sec:Device Types / RTC Device}
> +
> +The RTC (Real Time Clock) device provides information about current
> +time. The device can provide different clocks, e.g.\ for the UTC or TAI
> +time standards, or for physical time elapsed since some past epoch. The
> +driver can read the clocks with simple or more accurate methods.
> +
> +\subsection{Device ID}\label{sec:Device Types / RTC Device / Device ID}
> +
> +17
> +
> +\subsection{Virtqueues}\label{sec:Device Types / RTC Device / Virtqueues}
> +
> +\begin{description}
> +\item[0] requestq
> +\end{description}
> +
> +The driver enqueues requests to the requestq.
> +
> +\subsection{Feature bits}\label{sec:Device Types / RTC Device / Feature bits}
> +
> +No device-specific feature bits are defined yet.

Just say:

None

like SPI

or

None currently defined.

like entropy.



> +\subsection{Device configuration layout}\label{sec:Device Types / RTC Device / Device configuration layout}
> +
> +There is no configuration data for the device.

None currently defined.

configuration data is not a thing


> +\subsection{Device Initialization}\label{sec:Device Types / RTC Device / Device Initialization}
> +
> +The device determines the set of clocks. The device can provide zero or
> +more clocks.
> +
> +\subsection{Device Operation}\label{sec:Device Types / RTC Device / Device Operation}
> +
> +For the requestq, the driver sends a message with a request, and
> +receives the response in the device-writable part of the message.


Hmm. This confuses two things.

The device-writable part is in the buffer.
Message type is the request type.


> The
> +requestq uses common request and response headers.
> +
> +\begin{lstlisting}
> +/* common request header */
> +struct virtio_rtc_req_head {
> +        le16 msg_type;
> +        u8 reserved[6];
> +};
> +
> +/* common response header */
> +struct virtio_rtc_resp_head {
> +        u8 status;
> +        u8 reserved[7];
> +};
> +\end{lstlisting}
> +
> +The \field{msg_type} field identifies the message type.
> +
> +The \field{status} field indicates whether the device successfully
> +executed the request. The device sets the \field{status} field to one of
> +the following values:
> +
> +\begin{lstlisting}
> +#define VIRTIO_RTC_S_OK         0
> +#define VIRTIO_RTC_S_EOPNOTSUPP 2
> +#define VIRTIO_RTC_S_ENODEV     3
> +#define VIRTIO_RTC_S_EINVAL     4
> +#define VIRTIO_RTC_S_EIO        5
> +\end{lstlisting}
> +
> +VIRTIO_RTC_S_OK indicates that the device successfully executed the
> +request.
> +
> +If \field{status} is not VIRTIO_RTC_S_OK, the value of other response
> +fields is undefined.
> +
> +VIRTIO_RTC_S_EOPNOTSUPP indicates that the device could not execute the
> +specific request due to an implementation limitation. The device also
> +returns status VIRTIO_RTC_S_EOPNOTSUPP for requests with unknown values
> +in the fields \field{msg_type} or \field{hw_counter}.
> +
> +VIRTIO_RTC_S_ENODEV indicates that the \field{clock_id} field value
> +supplied with the request does not identify a clock.
> +
> +VIRTIO_RTC_S_EINVAL indicates that

either? or both?

> +
> +\begin{itemize}
> +\item the driver request values are not allowed by the specification or

how do you mean? not recognized by the device? what do you expect
driver to do? assert basically? no well behaved driver will
encounter it right?




> +\item the device read-only part of the message, or the device write-only
> +        part of the message, is too small to fit the actual message.

what is the actual message? do you mean the read-only part is too
small to fit the request or the write-only part is too small to
fit the response?


> +\end{itemize}
> +
> +VIRTIO_RTC_S_EIO indicates that the device did not execute the request
> +due to an error which was not caused by invalid input from the driver.
> +
> +All \field{reserved} fields are written as zero, and their value is
> +ignored.
> +
> +The set of clocks does not change after feature negotiation completion,
> +until device reset. The set of clocks should not change on device reset
> +either (similar to negotiated features). Clock identifiers are
> +zero-based, dense indices. All fields

in which structure? within request structures?

> named \field{clock_id} contain
> +clock identifiers.
> +
> +\subsubsection{Common Definitions}\label{sec:Device Types / RTC Device / Device Operation / Common Definitions}
> +
> +This section makes common definitions.
> +
> +\paragraph{Clock Types}\label{sec:Device Types / RTC Device / Device Operation / Common Definitions / Clock Types}
> +
> +The following clock types are defined:
> +
> +\begin{lstlisting}
> +#define VIRTIO_RTC_CLOCK_UTC                    0
> +#define VIRTIO_RTC_CLOCK_TAI                    1
> +#define VIRTIO_RTC_CLOCK_MONOTONIC              2
> +#define VIRTIO_RTC_CLOCK_UTC_SMEARED            3
> +#define VIRTIO_RTC_CLOCK_UTC_MAYBE_SMEARED      4
> +\end{lstlisting}
> +
> +\begin{description}
> +
> +\item[VIRTIO_RTC_CLOCK_UTC] uses the UTC (Coordinated Universal Time)
> +        time standard. This clock uses the time epoch of January 1,
> +        1970, 00:00 UTC. This is the same epoch as \emph{Unix time}. The
> +        clock's seconds since the epoch are related to UTC time as
> +        defined by \hyperref[intro:EPOCH]{EPOCH}.
> +
> +        This clock observes positive and negative leap seconds as
> +        announced by standard bodies. At the start of leap seconds, the
> +        clock steps accordingly.
> +
> +\item[VIRTIO_RTC_CLOCK_TAI] uses the TAI (International Atomic Time)
> +        time standard. This clock uses the time epoch of January 1,
> +        1970, 00:00 TAI.
> +
> +\item[VIRTIO_RTC_CLOCK_MONOTONIC] uses monotonic physical time (SI
> +        seconds subdivisions) since some unspecified epoch. The epoch is
> +        before or during device reset.
> +
> +\item[VIRTIO_RTC_CLOCK_UTC_SMEARED] deviates from the UTC standard by
> +        smearing time in the vicinity of a leap second. This avoids
> +        clock steps due to UTC leap seconds. Otherwise, this clock is
> +        similar to VIRTIO_RTC_CLOCK_UTC.
> +
> +\item[VIRTIO_RTC_CLOCK_UTC_MAYBE_SMEARED] This clock
> +
> +\begin{itemize}
> +\item may deviate from the UTC standard by smearing time in the vicinity
> +        of a leap second (similar to VIRTIO_RTC_CLOCK_UTC_SMEARED), or
> +
> +\item may step at the start of leap seconds like VIRTIO_RTC_CLOCK_UTC.
> +\end{itemize}
> +
> +A clock of type VIRTIO_RTC_CLOCK_UTC_MAYBE_SMEARED can change this
> +behavior for every leap second.
> +
> +\end{description}
> +
> +In the following, \emph{UTC-like clock} designates any clock of type
> +VIRTIO_RTC_CLOCK_UTC, VIRTIO_RTC_CLOCK_UTC_SMEARED, or
> +VIRTIO_RTC_CLOCK_UTC_MAYBE_SMEARED.
> +
> +Additional clock types may be standardized in the future.
> +Implementation-specific definitions of clock types are not recommended.
> +Implementation-specific definitions use ids between 0xF0 and 0xFF.
> +
> +\paragraph{Smearing Variants}\label{sec:Device Types / RTC Device / Device Operation / Common Definitions / Smearing Variants}
> +
> +Leap second \emph{smearing variants} describe the deviation from the UTC
> +standard in the vicinity of a leap second. The following smearing
> +variants are currently defined:
> +
> +\begin{lstlisting}
> +#define VIRTIO_RTC_SMEAR_UNSPECIFIED    0
> +#define VIRTIO_RTC_SMEAR_NOON_LINEAR    1
> +#define VIRTIO_RTC_SMEAR_UTC_SLS        2
> +\end{lstlisting}
> +
> +\begin{description}
> +
> +        \item[VIRTIO_RTC_SMEAR_UNSPECIFIED] means that it is unspecified
> +                how time is smeared in the vicinity of leap seconds.
> +
> +        \item[VIRTIO_RTC_SMEAR_NOON_LINEAR] specifies a linear smear
> +                from noon prior to the leap second until noon after the
> +                leap second.
> +
> +        \item[VIRTIO_RTC_SMEAR_UTC_SLS] specifies a linear smear as per
> +                the \hyperref[intro:UTC-SLS]{UTC-SLS} proposal.
> +
> +\end{description}
> +
> +Clocks of type VIRTIO_RTC_CLOCK_UTC_SMEARED always behave according to a
> +smearing variant. The smearing variant does not change over the clock's
> +lifetime.
> +
> +For clocks of type VIRTIO_RTC_CLOCK_UTC_MAYBE_SMEARED, it is unspecified
> +whether leap seconds are smeared, and how leap seconds are smeared.
> +
> +Additional smearing variants may be standardized in the future.
> +Implementation-specific definitions of smearing variants are not
> +recommended. Implementation-specific definitions use ids greater than or
> +equal to 0xF0.
> +
> +In the following, \emph{leap smearing clock} designates

here, and elsewhere, it's confusing whether itemization is for either
or both.

> +\begin{itemize}
> +
> +\item any clock of type VIRTIO_RTC_CLOCK_UTC_SMEARED
> +
> +\item any clock of type VIRTIO_RTC_CLOCK_UTC_MAYBE_SMEARED at any time
> +        when the clock is smearing a leap second.
> +
> +\end{itemize}
> +
> +\paragraph{Hardware Counters}\label{sec:Device Types / RTC Device / Device Operation / Common Definitions / Hardware Counters}
> +
> +The following hardware counter identifiers are specified:
> +
> +\begin{lstlisting}
> +/* Arm Generic Timer Counter-timer Virtual Count Register (CNTVCT_EL0) */
> +#define VIRTIO_RTC_COUNTER_ARM_VCT      0
> +/* x86 Time-Stamp Counter */
> +#define VIRTIO_RTC_COUNTER_X86_TSC      1
> +/* Invalid */
> +#define VIRTIO_RTC_COUNTER_INVALID   0xFF
> +\end{lstlisting}
> +
> +Additional hardware counter identifiers may be standardized in the
> +future. Implementation-specific hardware counter identifiers are not
> +recommended. Implementation-specific hardware counter identifiers have
> +values between 0xF0 and 0xFE.

Maybe something like "and are reserved for experimental implementations".


> +
> +\subsubsection{Control Requests}\label{sec:Device Types / RTC Device / Device Operation / Control Requests}
> +
> +Through \emph{control requests}, the driver requests information about
> +the device capabilities. The driver enqueues control requests in the
> +requestq.
> +
> +\begin{description}
> +
> +\item[VIRTIO_RTC_REQ_CFG] discovers the number of clocks.
> +
> +\begin{lstlisting}
> +#define VIRTIO_RTC_REQ_CFG 0x1000 /* message type */
> +
> +struct virtio_rtc_req_cfg {
> +        struct virtio_rtc_req_head head;
> +        /* no request params */
> +};
> +
> +struct virtio_rtc_resp_cfg {
> +        struct virtio_rtc_resp_head head;
> +        le16 num_clocks;
> +        u8 reserved[6];
> +};
> +\end{lstlisting}
> +
> +Field \field{num_clocks} contains the number of clocks. A device
> +provides zero or more clocks. Valid clock ids are those smaller than
> +\field{num_clocks}.
> +
> +\item[VIRTIO_RTC_REQ_CLOCK_CAP] discovers the capabilities of the clock
> +identified by the \field{clock_id} field.
> +
> +\begin{lstlisting}
> +#define VIRTIO_RTC_REQ_CLOCK_CAP 0x1001 /* message type */
> +
> +struct virtio_rtc_req_clock_cap {
> +        struct virtio_rtc_req_head head;
> +        le16 clock_id;
> +        u8 reserved[6];
> +};
> +
> +struct virtio_rtc_resp_clock_cap {
> +        struct virtio_rtc_resp_head head;
> +        u8 type;
> +        u8 leap_second_smearing;
> +        u8 reserved[6];
> +};
> +\end{lstlisting}
> +
> +The \field{type} field identifies the clock type. A device provides
> +zero or more clocks for a clock type.
> +
> +Clocks of type VIRTIO_RTC_CLOCK_UTC_SMEARED indicate the \emph{smearing
> +variant} through field \field{leap_second_smearing}. All other clocks
> +set \field{leap_second_smearing} to VIRTIO_RTC_SMEAR_UNSPECIFIED.
> +
> +\item[VIRTIO_RTC_REQ_CROSS_CAP] discovers whether the device supports
> +cross-timestamping for a particular pair of clock and hardware counter.
> +
> +\begin{lstlisting}
> +#define VIRTIO_RTC_REQ_CROSS_CAP 0x1002 /* message type */
> +
> +struct virtio_rtc_req_cross_cap {
> +        struct virtio_rtc_req_head head;
> +        le16 clock_id;
> +        u8 hw_counter;
> +        u8 reserved[5];
> +};
> +
> +
> +struct virtio_rtc_resp_cross_cap {
> +        struct virtio_rtc_resp_head head;
> +#define VIRTIO_RTC_FLAG_CROSS_CAP       (1 << 0)
> +        u8 flags;
> +        u8 reserved[7];
> +};
> +\end{lstlisting}
> +
> +The \field{clock_id} field identifies the clock, and the
> +\field{hw_counter} field identifies the hardware counter, for which
> +cross-timestamp support is probed. The device sets the
> +VIRTIO_RTC_FLAG_CROSS_CAP flag in the \field{flags} field if the clock
> +supports cross-timestamping for the particular clock and hardware
> +counter, and clears the flag otherwise.
> +
> +\end{description}
> +
> +\subsubsection{Read Requests}\label{sec:Device Types / RTC Device / Device Operation / Read Requests}
> +
> +Through \emph{read requests}, the driver requests clock readings from
> +the device. The driver enqueues read requests in the requestq. The
> +device obtains device-side clock readings and forwards these clock
> +readings to the driver. The driver may enhance and interpret the clock
> +readings through methods which are beyond the scope of this
> +specification.
> +
> +Once DRIVER_OK has been set, the device should support reading every
> +clock, even when a clock may yet have to be aligned to reference time
> +sources.
> +
> +In general,
> +
> +\begin{itemize}
> +\item clocks may jump backwards or forward, and
> +\item the clock frequency may change. Clocks may be \emph{slewed},
> +        i.e.\ clocks may run at a frequency other than their current
> +        best frequency estimate.
> +\end{itemize}
> +
> +As long as a clock does not jump backwards, the driver clock readings
> +through read request responses increase monotonically:
> +
> +\begin{itemize}
> +\item As long as a clock does not jump backwards in-between device-side
> +        clock readings, the driver-side readings for that clock increase
> +        monotonically as well, in the order in which the driver
> +        marks read requests as available.
> +
> +\item The device marks read requests for the same clock as used in
> +        the order in which the messages were marked as available.

buffers are available

> +\end{itemize}
> +
> +For a clock of type VIRTIO_RTC_CLOCK_MONOTONIC, the device always returns
> +monotonically increasing clock readings through read request responses.
> +
> +The unit of all \field{clock_reading} fields is 1
> +nanosecond.\footnote{For time epochs in year 1970 or later, this means
> +that time until at least year 2553 can be represented in the \field{le64
> +clock_reading} fields.}
> +
> +\begin{description}
> +
> +\item[VIRTIO_RTC_REQ_READ] reads the clock identified by the
> +\field{clock_id} field. The device supports this message for every
> +clock.
> +
> +\begin{lstlisting}
> +#define VIRTIO_RTC_REQ_READ 0x0001 /* message type */
> +
> +struct virtio_rtc_req_read {
> +        struct virtio_rtc_req_head head;
> +        le16 clock_id;
> +        u8 reserved[6];
> +};
> +
> +struct virtio_rtc_resp_read {
> +        struct virtio_rtc_resp_head head;
> +        le64 clock_reading;
> +};
> +\end{lstlisting}
> +
> +\field{clock_reading} is a device-side clock reading obtained after the
> +message was marked as available.
> +
> +\item[VIRTIO_RTC_REQ_READ_CROSS] returns a cross-timestamp for the clock
> +identified by the \field{clock_id} field.\footnote{Cross-timestamping
> +is similar to the ptp_kvm mechanism in the Linux kernel.} This message
> +may yield better performance than using VIRTIO_RTC_REQ_READ.
> +
> +The driver can determine whether the device supports
> +VIRTIO_RTC_REQ_READ_CROSS for a specific clock and \field{hw_counter}
> +through VIRTIO_RTC_REQ_CROSS_CAP.
> +
> +\begin{lstlisting}
> +#define VIRTIO_RTC_REQ_READ_CROSS 0x0002 /* message type */
> +
> +struct virtio_rtc_req_read_cross {
> +        struct virtio_rtc_req_head head;
> +        le16 clock_id;
> +        u8 hw_counter;
> +        u8 reserved[5];
> +};
> +
> +struct virtio_rtc_resp_read_cross {
> +        struct virtio_rtc_resp_head head;
> +        le64 clock_reading;
> +        le64 counter_cycles;
> +};
> +\end{lstlisting}
> +
> +The \field{hw_counter} field specifies the hardware counter for which
> +the driver requests a cross-timestamp.
> +
> +Cross-timestamping returns a \field{clock_reading}, and an associated
> +hardware counter value, \field{counter_cycles}. The
> +\field{counter_cycles} field is the approximate or precise value which
> +the driver would have read at the \field{clock_reading} time instant
> +from the hardware counter identified by \field{hw_counter}. How the
> +device determines the value which the driver would have seen is beyond
> +the scope of this specification.

Not sure how it's beyond the scope. What exactly do you have
in mind? The following paragraph hints at the fact you have
some idea?

> In case hardware counter reads differ
> +among CPUs used by the driver, the device should assume that the driver
> +reads the hardware counter from the CPU which the driver enumerates as
> +the first.
> +
> +The hardware counter identifiers are defined in
> +\ref{sec:Device Types / RTC Device / Device Operation / Common Definitions / Hardware Counters}.
> +
> +\end{description}
> diff --git a/introduction.tex b/introduction.tex
> index e60298a4d78b..34f9485bc393 100644
> --- a/introduction.tex
> +++ b/introduction.tex
> @@ -168,6 +168,12 @@ \section{Normative References}\label{sec:Normative References}
>      Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP
>      14, RFC 8174, DOI 10.17487/RFC8174, May 2017
>          \newline\url{http://www.ietf.org/rfc/rfc8174.txt}\\
> +	\phantomsection\label{intro:EPOCH}\textbf{[EPOCH]} &
> +    POSIX.1-2024, Base Definitions, Seconds Since the Epoch
> +	\newline\url{https://pubs.opengroup.org/onlinepubs/9799919799/basedefs/V1_chap04.html#tag_04_19}\\
> +	\phantomsection\label{intro:UTC-SLS}\textbf{[UTC-SLS]} &
> +    UTC with Smoothed Leap Seconds (UTC-SLS)
> +	\newline\url{https://www.cl.cam.ac.uk/~mgk25/time/utc-sls/}\\
>  \end{longtable}
>  
>  \section{Non-Normative References}
> -- 
> 2.43.0
> 

Re: [PATCH v8 2/4] virtio-rtc: Add initial normative statements

[Michael S. Tsirkin]

On Thu, Mar 06, 2025 at 10:51:10AM +0100, Peter Hilber wrote:
> Add the normative statements for the initial device specification.
> 
> Signed-off-by: Peter Hilber <quic_philber@quicinc.com>
> ---
> 
> Notes:
>     v8:
>     
>     - Drop requirement to ignore reserved fields in the device-readable part
>       of the message (Matias Ezequiel Vara Larsen).
>     
>     - Drop requirement about returning same status in response to identical
>       requests (Matias Ezequiel Vara Larsen).
>     
>     - Reword requirements about size mismatches for device
>       read-only/write-only parts of the message (Matias Ezequiel Vara
>       Larsen).
>     
>     - Change word order from "field X" to "the X field" (Matias Ezequiel
>       Vara Larsen).
>     
>     v7:
>     
>     - Remove obsolete requirements for leap second indication.
>     
>     v6:
>     
>     - Update requirements to make leap second status information optional if
>       if the clock smears (or might smear) leap seconds.
>     
>     - Allow indicating VIRTIO_RTC_SMEAR_UNSPECIFIED for
>       VIRTIO_RTC_CLOCK_SMEARED.
>     
>     - Shorten some requirements by omitting redundant information.
>     
>     v5:
>     
>     - Update normative statements to match v5 changes to non-normative
>       statements (patch 1).
>     
>     v4:
>     
>     - Require driver to set unused flags to zero.
>     
>     - Update normative statements to match v4 changes to non-normative
>       statements (patch 1).
>     
>     - Improve formatting.
> 
>  conformance.tex                         |   2 +
>  device-types/rtc/description.tex        | 272 +++++++++++++++++++++++-
>  device-types/rtc/device-conformance.tex |   9 +
>  device-types/rtc/driver-conformance.tex |   9 +
>  4 files changed, 288 insertions(+), 4 deletions(-)
>  create mode 100644 device-types/rtc/device-conformance.tex
>  create mode 100644 device-types/rtc/driver-conformance.tex
> 
> diff --git a/conformance.tex b/conformance.tex
> index d92a2369488e..4ce86a525e84 100644
> --- a/conformance.tex
> +++ b/conformance.tex
> @@ -162,6 +162,7 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets}
>  \input{device-types/pmem/driver-conformance.tex}
>  \input{device-types/can/driver-conformance.tex}
>  \input{device-types/spi/driver-conformance.tex}
> +\input{device-types/rtc/driver-conformance.tex}
>  
>  \conformance{\section}{Device Conformance}\label{sec:Conformance / Device Conformance}
>  
> @@ -254,6 +255,7 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets}
>  \input{device-types/pmem/device-conformance.tex}
>  \input{device-types/can/device-conformance.tex}
>  \input{device-types/spi/device-conformance.tex}
> +\input{device-types/rtc/device-conformance.tex}
>  
>  \conformance{\section}{Legacy Interface: Transitional Device and Transitional Driver Conformance}\label{sec:Conformance / Legacy Interface: Transitional Device and Transitional Driver Conformance}
>  A conformant implementation MUST be either transitional or
> diff --git a/device-types/rtc/description.tex b/device-types/rtc/description.tex
> index 5d8cf91a6991..f2a3907de511 100644
> --- a/device-types/rtc/description.tex
> +++ b/device-types/rtc/description.tex
> @@ -73,7 +73,7 @@ \subsection{Device Operation}\label{sec:Device Types / RTC Device / Device Opera
>  VIRTIO_RTC_S_EOPNOTSUPP indicates that the device could not execute the
>  specific request due to an implementation limitation. The device also
>  returns status VIRTIO_RTC_S_EOPNOTSUPP for requests with unknown values
> -in the fields \field{msg_type} or \field{hw_counter}.
> +in the \field{msg_type} or \field{hw_counter} fields.
>  
>  VIRTIO_RTC_S_ENODEV indicates that the \field{clock_id} field value
>  supplied with the request does not identify a clock.
> @@ -98,6 +98,106 @@ \subsection{Device Operation}\label{sec:Device Types / RTC Device / Device Opera
>  zero-based, dense indices. All fields named \field{clock_id} contain
>  clock identifiers.
>  
> +\drivernormative{\subsubsection}{Device Operation}{Device Types / RTC Device / Device Operation}
> +
> +If the \field{struct virtio_rtc_resp_head} field \field{status} is not
> +VIRTIO_RTC_S_OK, the driver MUST NOT interpret response fields other
> +than \field{status}.
> +
> +The driver MUST set \emph{reserved} fields in the device-readable part
> +of the message to zero.
> +
> +The driver MUST set unnamed bits in \emph{flags} fields in the
> +device-readable part of the message to zero.


This is problematic, it should depend on features negotiated
not on features listed in the spec as we will not
remember to change this and break drivers.
Just add in the description explanation which flags are legal for each request,
then refer to that.


> +
> +The driver MUST NOT interpret \emph{reserved} fields in the
> +device-writable part of the message.
> +
> +The driver MUST NOT interpret unnamed bits in \emph{flags} fields in the
> +device-writable part of the message.

same though a bit less of a problem here.


> +
> +The driver MUST put the request into the device-readable part of the
> +message.
> +
> +The driver MUST allocate enough space for the response in the
> +device-writable part of a requestq message.
> +
> +\devicenormative{\subsubsection}{Device Operation}{Device Types / RTC Device / Device Operation}
> +
> +For \field{struct virtio_rtc_resp_head}, the device MUST set the
> +\field{status} field to VIRTIO_RTC_S_OK if the device successfully
> +executed the request.
> +
> +For \field{struct virtio_rtc_resp_head}, the device MUST set the
> +\field{status} field to a status other than VIRTIO_RTC_S_OK if the
> +device did not successfully execute the request.
> +
> +For \field{struct virtio_rtc_resp_head}, the device MUST set the
> +\field{status} field to VIRTIO_RTC_S_EOPNOTSUPP if the device could not
> +execute the specific request due to an implementation limitation.
> +
> +For \field{struct virtio_rtc_resp_head}, the device MUST set the
> +\field{status} field to VIRTIO_RTC_S_EOPNOTSUPP for a request with a
> +value of the \field{msg_type} field which is not described in this
> +specification.
> +
> +For \field{struct virtio_rtc_resp_head}, the device MUST set the
> +\field{status} field to VIRTIO_RTC_S_EOPNOTSUPP for a request with a
> +value of the \field{hw_counter} field which is neither described in this
> +specification nor otherwise known to the implementation.
> +
> +For \field{struct virtio_rtc_resp_head}, the device MUST set the
> +\field{status} field to VIRTIO_RTC_S_ENODEV if the \field{clock_id}
> +field value supplied with the request does not identify a clock.
> +
> +For \field{struct virtio_rtc_resp_head}, the device MUST set the
> +\field{status} field to VIRTIO_RTC_S_EINVAL if the request values are
> +inconsistent with the specification and if the inconsistence is not
> +described by the requirements which stipulate status
> +VIRTIO_RTC_S_EOPNOTSUPP or VIRTIO_RTC_S_ENODEV.
> +
> +For \field{struct virtio_rtc_resp_head}, the device MUST set the
> +\field{status} field to VIRTIO_RTC_S_EINVAL if the request specified in
> +the request header through the \field{msg_type} field does not fit into
> +the device read-only part of the actual message.
> +
> +For \field{struct virtio_rtc_resp_head}, the device MUST set the
> +\field{status} field to VIRTIO_RTC_S_EINVAL if the response specified in
> +the request header through the \field{msg_type} field does not fit into
> +the device write-only part of the actual message, unless the
> +\field{status} field does not fit into the device write-only part.
> +
> +For \field{struct virtio_rtc_resp_head}, the device MUST NOT set the
> +\field{status} field if the \field{status} field does not fit into the
> +device write-only part.
> +
> +For \field{struct virtio_rtc_resp_head}, the device MUST set the
> +\field{status} field to VIRTIO_RTC_S_EIO if none of the previous
> +requirements in this document stipulated another \field{status}.
> +
> +If the device read-only part of a message M is bigger than the size of
> +the request specified for message M, the device MUST ignore the
> +additional space.
> +
> +If the device write-only part of a message M is bigger than the size of
> +the response specified for message M, the device MUST ignore the
> +additional space.
> +
> +The device MUST set \emph{reserved} fields in the device-writable part
> +of the message to zero.
> +
> +The device MUST set unnamed bits in \emph{flags} fields in the
> +device-writable part of the message to zero.
> +
> +After feature negotiation completion the device MUST NOT change the set
> +of clocks until device reset.
> +
> +The device SHOULD NOT change the set of clocks on a device reset after
> +the first device reset.

really SHUOLD is more appropriate

and first in what sense? here is the text for features:


	If a device has successfully negotiated a set of features 
	at least once (by accepting the FEATURES_OK \field{device 
	status} bit during device initialization), then it SHOULD
	NOT fail re-negotiation of the same set of features after
	a device or system reset.  Failure to do so would interfere
	with resuming from suspend and error recovery.

do something similar and be specific pls.



> +
> +The device MUST use non-negative integers, which are smaller than the
> +number of clocks, as clock identifiers.
> +
>  \subsubsection{Common Definitions}\label{sec:Device Types / RTC Device / Device Operation / Common Definitions}
>  
>  This section makes common definitions.
> @@ -253,7 +353,7 @@ \subsubsection{Control Requests}\label{sec:Device Types / RTC Device / Device Op
>  };
>  \end{lstlisting}
>  
> -Field \field{num_clocks} contains the number of clocks. A device
> +The \field{num_clocks} field contains the number of clocks. A device
>  provides zero or more clocks. Valid clock ids are those smaller than
>  \field{num_clocks}.
>  
> @@ -281,8 +381,8 @@ \subsubsection{Control Requests}\label{sec:Device Types / RTC Device / Device Op
>  zero or more clocks for a clock type.
>  
>  Clocks of type VIRTIO_RTC_CLOCK_UTC_SMEARED indicate the \emph{smearing
> -variant} through field \field{leap_second_smearing}. All other clocks
> -set \field{leap_second_smearing} to VIRTIO_RTC_SMEAR_UNSPECIFIED.
> +variant} through the \field{leap_second_smearing} field. All other
> +clocks set \field{leap_second_smearing} to VIRTIO_RTC_SMEAR_UNSPECIFIED.
>  
>  \item[VIRTIO_RTC_REQ_CROSS_CAP] discovers whether the device supports
>  cross-timestamping for a particular pair of clock and hardware counter.
> @@ -315,6 +415,103 @@ \subsubsection{Control Requests}\label{sec:Device Types / RTC Device / Device Op
>  
>  \end{description}
>  
> +\drivernormative{\paragraph}{Control Requests}{Device Types / RTC Device / Device Operation / Control Requests}
> +
> +For VIRTIO_RTC_REQ_CROSS_CAP, the driver MUST set \field{hw_counter} to
> +one of the hardware counter identifiers defined in this specification,
> +or to a value between 0xF0 and 0xFE.
> +
> +\devicenormative{\paragraph}{Control Requests}{Device Types / RTC Device / Device Operation / Control Requests}
> +
> +For any clock of type VIRTIO_RTC_CLOCK_UTC, the device MUST use the UTC
> +time standard (Coordinated Universal Time).
> +
> +For any clock of type VIRTIO_RTC_CLOCK_UTC_SMEARED or
> +VIRTIO_RTC_CLOCK_UTC_MAYBE_SMEARED, the device MUST use the UTC time
> +standard, insofar as the following requirements do not say otherwise.
> +
> +For any UTC-like clock, the device MUST use the time epoch of January 1,
> +1970, 00:00 UTC.
> +
> +For any UTC-like clock, the device MUST count seconds since the epoch
> +according to \hyperref[intro:EPOCH]{EPOCH}.
> +
> +For any clock of type VIRTIO_RTC_CLOCK_UTC, the device MUST apply a
> +positive leap second according to the UTC time standard by
> +instantaneously stepping the clock backwards by 1 s at the start of the
> +leap second.
> +
> +For any clock of type VIRTIO_RTC_CLOCK_UTC, the device MUST apply a
> +negative leap second according to the UTC time standard by
> +instantaneously stepping the clock forward by 1 s at the start of the
> +leap second.
> +
> +For any leap smearing clock, the device MUST NOT step the clock due to a
> +leap second.
> +
> +For any leap smearing clock, on a positive leap second, the device MUST
> +slow down the clock during part of the day containing the leap second
> +and/or part of the day after the leap second.
> +
> +For any leap smearing clock, on a negative leap second, the device MUST
> +speed up the clock during part of the day containing the leap second
> +and/or part of the day after the leap second.
> +
> +For any clock with smearing variant VIRTIO_RTC_SMEAR_NOON_LINEAR, on a
> +leap second, the device MUST change the frequency of the clock exactly
> +from noon prior to the leap second until noon after the leap second.
> +
> +For any clock with smearing variant VIRTIO_RTC_SMEAR_NOON_LINEAR, while
> +changing the frequency of the clock due to a positive leap second, the
> +device MUST decrease the frequency of the clock by $1/86400$.
> +
> +For any clock with smearing variant VIRTIO_RTC_SMEAR_NOON_LINEAR, while
> +changing the frequency of the clock due to a negative leap second, the
> +device MUST increase the frequency of the clock by $1/86400$.
> +
> +For any clock with smearing variant VIRTIO_RTC_SMEAR_UTC_SLS, on a leap
> +second, the device MUST change the frequency of the clock exactly during
> +the last 1000 seconds of the day with the leap second.
> +
> +For any clock with smearing variant VIRTIO_RTC_SMEAR_UTC_SLS, while
> +changing the frequency of the clock due to a positive leap second, the
> +device MUST decrease the frequency of the clock by 0.1\%.
> +
> +For any clock with smearing variant VIRTIO_RTC_SMEAR_UTC_SLS, while
> +changing the frequency of the clock due to a negative leap second, the
> +device MUST increase the frequency of the clock by 0.1\%.
> +
> +For any clock of type VIRTIO_RTC_CLOCK_UTC_MAYBE_SMEARED, the device MAY
> +deviate from the UTC standard with respect to leap second introduction.
> +
> +For any clock of type VIRTIO_RTC_CLOCK_TAI, the device MUST use the TAI
> +time standard (International Atomic Time).
> +
> +For any clock of type VIRTIO_RTC_CLOCK_TAI, the device MUST use the time
> +epoch of January 1, 1970, 00:00 TAI.
> +
> +For any clock of type VIRTIO_RTC_CLOCK_MONOTONIC, the device MUST use SI
> +seconds subdivisions.
> +
> +For any clock of type VIRTIO_RTC_CLOCK_MONOTONIC, the device MUST use an
> +epoch at a time instant before or during device reset.
> +
> +For VIRTIO_RTC_REQ_CLOCK_CAP, and clock types other than
> +VIRTIO_RTC_CLOCK_UTC_SMEARED, the device MUST set the
> +\field{leap_second_smearing} field to VIRTIO_RTC_SMEAR_UNSPECIFIED.
> +
> +For VIRTIO_RTC_REQ_CLOCK_CAP, and clock type
> +VIRTIO_RTC_CLOCK_UTC_SMEARED, the device MUST set the
> +\field{leap_second_smearing} field to VIRTIO_RTC_SMEAR_UNSPECIFIED,
> +VIRTIO_RTC_SMEAR_NOON_LINEAR, VIRTIO_RTC_SMEAR_UTC_SLS, or to a value
> +greater than or equal to 0xF0.
> +
> +For a VIRTIO_RTC_REQ_CROSS_CAP message M, the device MUST set the
> +VIRTIO_RTC_FLAG_CROSS_CAP flag in the \field{flags} field if the device
> +would respond to a VIRTIO_RTC_REQ_READ_CROSS message with the same
> +\field{hw_counter} and \field{clock_id} values as in M with status
> +VIRTIO_RTC_S_OK, and clear the flag otherwise.
> +
>  \subsubsection{Read Requests}\label{sec:Device Types / RTC Device / Device Operation / Read Requests}
>  
>  Through \emph{read requests}, the driver requests clock readings from
> @@ -426,3 +623,70 @@ \subsubsection{Read Requests}\label{sec:Device Types / RTC Device / Device Opera
>  \ref{sec:Device Types / RTC Device / Device Operation / Common Definitions / Hardware Counters}.
>  
>  \end{description}
> +
> +\drivernormative{\paragraph}{Read Requests}{Device Types / RTC Device / Device Operation / Read Requests}
> +
> +For VIRTIO_RTC_REQ_READ_CROSS, the driver MUST set \field{hw_counter} to
> +one of the hardware counter identifiers defined in this specification,
> +or to a value between 0xF0 and 0xFE.
> +
> +\devicenormative{\paragraph}{Read Requests}{Device Types / RTC Device / Device Operation / Read Requests}
> +
> +The device SHOULD continuously support reading of all clocks once
> +DRIVER_OK has been set.
> +
> +For any clock C and read requests \emph{A} and \emph{B} which read C,
> +\emph{A} being the message which the driver marks as available before
> +\emph{B}, the device MUST obtain the \field{clock_reading} value for the
> +message \emph{A} response before the \field{clock_reading} value for the
> +message \emph{B} response, or the device MUST obtain the same
> +\field{clock_reading} value for both \emph{A} and \emph{B}.
> +
> +For any clock C, the device MUST mark all read requests reading C as
> +used in the total order in which the driver marked these messages as
> +available.
> +
> +For any clock C of type VIRTIO_RTC_CLOCK_MONOTONIC and read requests
> +\emph{A} and \emph{B} which read C, \emph{A} being the message which the
> +driver marks as available before \emph{B}, the device MUST set the
> +\field{clock_reading} value for the message \emph{B} response to a value
> +greater than or equal to the \field{clock_reading} value for the message
> +\emph{A} response.
> +
> +The device MUST support VIRTIO_RTC_REQ_READ for every clock.
> +
> +For VIRTIO_RTC_REQ_READ and for any clock type listed in this
> +specification, the device MUST use the nanosecond as unit for the
> +\field{clock_reading} field.
> +
> +For read requests, the device MUST obtain the \field{clock_reading}
> +response value after the read request is marked as available.
> +
> +For VIRTIO_RTC_REQ_READ_CROSS, the device MUST set
> +\field{counter_cycles} to a value which approximates the value which the
> +driver would have read from the hardware counter identified by
> +\field{hw_counter} at the time instant when the device read the
> +\field{clock_reading} value.
> +
> +For VIRTIO_RTC_REQ_READ_CROSS, the device SHOULD assume that the driver
> +reads the hardware counter identified by \field{hw_counter} through the
> +CPU which the driver enumerates as the first.
> +
> +For VIRTIO_RTC_REQ_READ_CROSS, the device MUST set \field{status} to a
> +value other than VIRTIO_RTC_S_OK if the device cannot determine the
> +approximate value which the driver would have read from the hardware
> +counter identified by \field{hw_counter} at the time instant when the
> +device read the \field{clock_reading} value.
> +
> +For any clock C, and VIRTIO_RTC_REQ_READ_CROSS messages \emph{A} and
> +\emph{B} which read C and which specify the same hardware counter
> +\emph{H} through the \field{hw_counter} field, \emph{A} being the
> +message which the driver marks as available before \emph{B}, the device
> +MUST set the \field{counter_cycles} value for \emph{B} to a value which
> +\emph{H} shows after the \field{counter_cycles} value of \emph{A}, or
> +the device MUST set the same \field{counter_cycles} value for \emph{A}
> +and \emph{B}.
> +
> +For VIRTIO_RTC_REQ_READ_CROSS and for any clock type listed in this
> +specification, the device MUST use the nanosecond as unit for the
> +\field{clock_reading} field.
> diff --git a/device-types/rtc/device-conformance.tex b/device-types/rtc/device-conformance.tex
> new file mode 100644
> index 000000000000..4303cd450542
> --- /dev/null
> +++ b/device-types/rtc/device-conformance.tex
> @@ -0,0 +1,9 @@
> +\conformance{\subsection}{RTC Device Conformance}\label{sec:Conformance / Device Conformance / RTC Device Conformance}
> +
> +An RTC device MUST conform to the following normative statements:
> +
> +\begin{itemize}
> +\item \ref{devicenormative:Device Types / RTC Device / Device Operation}
> +\item \ref{devicenormative:Device Types / RTC Device / Device Operation / Control Requests}
> +\item \ref{devicenormative:Device Types / RTC Device / Device Operation / Read Requests}
> +\end{itemize}
> diff --git a/device-types/rtc/driver-conformance.tex b/device-types/rtc/driver-conformance.tex
> new file mode 100644
> index 000000000000..689c18d158d0
> --- /dev/null
> +++ b/device-types/rtc/driver-conformance.tex
> @@ -0,0 +1,9 @@
> +\conformance{\subsection}{RTC Driver Conformance}\label{sec:Conformance / Driver Conformance / RTC Driver Conformance}
> +
> +An RTC driver MUST conform to the following normative statements:
> +
> +\begin{itemize}
> +\item \ref{drivernormative:Device Types / RTC Device / Device Operation}
> +\item \ref{drivernormative:Device Types / RTC Device / Device Operation / Control Requests}
> +\item \ref{drivernormative:Device Types / RTC Device / Device Operation / Read Requests}
> +\end{itemize}
> -- 
> 2.43.0
> 

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

[Michael S. Tsirkin]

Good work. I sent some comments but they are pretty minor. Thanks!

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.

A bit more text on the motivation, when to do you intend to use this
device, would be good.


> 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
> 

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

[Peter Hilber]

On Tue, Apr 15, 2025 at 05:04:05PM +0200, Matias Ezequiel Vara Larsen wrote:
> On Thu, Mar 06, 2025 at 10:51:09AM +0100, Peter Hilber wrote:
> > The virtio-rtc device provides information about current time through
> > one or more clocks. As such, it is a Real-Time Clock (RTC) device.
> > 
> > The normative statements for this device follow in the next patch.
> > 
> > For this device, there is an RFC Linux kernel driver which is being
> > upstreamed, and a proprietary device implementation.
> > 
> > Miscellaneous
> > -------------
> > 
> > The spec does not specify how a driver should interpret clock readings,
> > esp. also not how to perform clock synchronization.
> > 
> > The device uses the "Timer/Clock" device id which is already part of the
> > specification. This device id was registered a long time ago and should
> > be unused according to the author's information. The name "RTC" was
> > determined to be the best for a device which focuses on current time.
> > 
> > Signed-off-by: Peter Hilber <quic_philber@quicinc.com>
> > ---
> > 
> > Notes:
> >     v8:
> >     
> >     - Change word order from "field X" to "the X field" (Matias Ezequiel
> >       Vara Larsen).
> >     
> >     - Split up sentences about implementation-specific definitions (Matias
> >       Ezequiel Vara Larsen).
> >     
> >     v7:
> >     
> >     - Remove leap second and performance indications from struct
> >       virtio_rtc_resp_read_cross. Remove backing definitions.
> >     
> >     - Add wording change which was previously mistakenly placed in last
> >       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 [8].
> >     
> >     - Add dedicated clock types for UTC leap second smearing (David
> >       Woodhouse).
> >     
> >     - Extend leap second indications.
> >     
> >     - Split UTC-TAI offset and fractional offset due to smearing (David
> >       Woodhouse).
> >     
> >     - Remove requirement that TAI offset must not be a whole second while
> >       clock is being smeared.
> >     
> >     - Align bit widths, and some names, with '[RFC PATCH v4] ptp: Add
> >       vDSO-style vmclock support' [8].
> >     
> >     - 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.
> >     
> >     v4:
> >     
> >     - Drop distinction of Arm Generic Timer virtual and physical counter [7].
> >     
> >     - Add requirement that device should assume that driver reads clock from
> >       first vCPU (David Woodhouse) [6].
> >     
> >     - Formatting and wording improvements.
> >     
> >     v3:
> >     
> >     - Address comments from Parav Pandit.
> >     
> >     - Split off normative requirements into a second commit [2].
> >     
> >     - Merge readq and controlq into requestq [3].
> >     
> >     - Don't guard cross-timestamping with feature bit [3].
> >     
> >     - Pad request headers to 64 bit [2].
> >     
> >     - Rename Virtio status codes to match UNIX error names [2].
> >     
> >     - Avoid Virtio status code clashes with net controlq ack values.
> >     
> >     - Reword to refer more to "requests", rather than "messages" [2].
> >     
> >     - Rephrase some sentences [2].
> >     
> >     - Use integer data types without "__" prefixes [2].
> >     
> >     - Reduce clock id width to 16 bits [5].
> >     
> >     - Make VIRTIO_RTC_FLAG_CROSS_CAP a bit mask rather than a bit index.
> >     
> >     v2:
> >     
> >     - Address comments from Cornelia Huck.
> >     
> >     - Add VIRTIO_RTC_M_CROSS_CAP message [1].
> >     
> >     - Fix various minor issues and improve wording [1].
> >     
> >     - Add several clarifications regarding device error statuses.
> >     
> >     [1] https://lists.oasis-open.org/archives/virtio-comment/202304/msg00523.html
> >     [2] https://lore.kernel.org/virtio-comment/b59a7dda-06fe-cff9-df61-b90aa4e50836@opensynergy.com/t/#mffb93800fea11d6dda9e151078abedd6ff1c0f1e
> >     [3] https://lore.kernel.org/virtio-comment/b59a7dda-06fe-cff9-df61-b90aa4e50836@opensynergy.com/t/#m94efd0aa9b9c2b96a246b79ef8bfc3bf64ebe791
> >     [4] https://lore.kernel.org/lkml/20230630171052.985577-1-peter.hilber@opensynergy.com/T/#m65fa1d715933360498c4e33d7225e4220215a9d6
> >     [5] https://lore.kernel.org/virtio-comment/b59a7dda-06fe-cff9-df61-b90aa4e50836@opensynergy.com/t/#mf00ce330228c28556d735eb9597469048c5d8b62
> >     [6] https://lore.kernel.org/lkml/d796d9a5-8eda-4528-a6d8-1c4eba24aa1e@opensynergy.com/
> >     [7] https://lore.kernel.org/all/20231218064253.9734-2-peter.hilber@opensynergy.com/
> >     [8] https://lore.kernel.org/lkml/20240708092924.1473461-1-dwmw2@infradead.org/
> > 
> >  content.tex                      |   3 +-
> >  device-types/rtc/description.tex | 428 +++++++++++++++++++++++++++++++
> >  introduction.tex                 |   6 +
> >  3 files changed, 436 insertions(+), 1 deletion(-)
> >  create mode 100644 device-types/rtc/description.tex
> > 
> > diff --git a/content.tex b/content.tex
> > index 67b1bf3c35ab..b1d93a8aebb4 100644
> > --- a/content.tex
> > +++ b/content.tex
> > @@ -684,7 +684,7 @@ \chapter{Device Types}\label{sec:Device Types}
> >  \hline
> >  16         &   GPU device       \\
> >  \hline
> > -17         &   Timer/Clock device \\
> > +17         &   RTC (Timer/Clock) device \\
> >  \hline
> >  18         &   Input device \\
> >  \hline
> > @@ -776,6 +776,7 @@ \chapter{Device Types}\label{sec:Device Types}
> >  \input{device-types/pmem/description.tex}
> >  \input{device-types/can/description.tex}
> >  \input{device-types/spi/description.tex}
> > +\input{device-types/rtc/description.tex}
> >  
> >  \chapter{Reserved Feature Bits}\label{sec:Reserved Feature Bits}
> >  
> > diff --git a/device-types/rtc/description.tex b/device-types/rtc/description.tex
> > new file mode 100644
> > index 000000000000..5d8cf91a6991
> > --- /dev/null
> > +++ b/device-types/rtc/description.tex
> > @@ -0,0 +1,428 @@
> > +\section{RTC Device}\label{sec:Device Types / RTC Device}
> > +
> > +The RTC (Real Time Clock) device provides information about current
> > +time. The device can provide different clocks, e.g.\ for the UTC or TAI
> > +time standards, or for physical time elapsed since some past epoch. The
> > +driver can read the clocks with simple or more accurate methods.
> > +
> 
> Can't we avoid to use `can` here and just use present simple?

As for the last sentence, OK. For the previous sentence, I propose to
retain "can" since a device is free to provide any subset of clocks.

> 
> > +\subsection{Device ID}\label{sec:Device Types / RTC Device / Device ID}
> > +
> > +17
> > +
> > +\subsection{Virtqueues}\label{sec:Device Types / RTC Device / Virtqueues}
> > +
> > +\begin{description}
> > +\item[0] requestq
> > +\end{description}
> > +
> > +The driver enqueues requests to the requestq.
> > +
> > +\subsection{Feature bits}\label{sec:Device Types / RTC Device / Feature bits}
> > +
> > +No device-specific feature bits are defined yet.
> > +
> > +\subsection{Device configuration layout}\label{sec:Device Types / RTC Device / Device configuration layout}
> > +
> > +There is no configuration data for the device.
> > +
> > +\subsection{Device Initialization}\label{sec:Device Types / RTC Device / Device Initialization}
> > +
> > +The device determines the set of clocks. The device can provide zero or
> > +more clocks.
> 
> I think you can avoid to use `can` here and also in other places.
> 

OK.

> > +
> > +\subsection{Device Operation}\label{sec:Device Types / RTC Device / Device Operation}
> > +
> > +For the requestq, the driver sends a message with a request, and
> > +receives the response in the device-writable part of the message. The
> > +requestq uses common request and response headers.
> > +
> > +\begin{lstlisting}
> > +/* common request header */
> > +struct virtio_rtc_req_head {
> > +        le16 msg_type;
> > +        u8 reserved[6];
> > +};
> > +
> > +/* common response header */
> > +struct virtio_rtc_resp_head {
> > +        u8 status;
> > +        u8 reserved[7];
> > +};
> > +\end{lstlisting}
> > +
> > +The \field{msg_type} field identifies the message type.
> > +
> > +The \field{status} field indicates whether the device successfully
> > +executed the request. The device sets the \field{status} field to one of
> > +the following values:
> > +
> > +\begin{lstlisting}
> > +#define VIRTIO_RTC_S_OK         0
> > +#define VIRTIO_RTC_S_EOPNOTSUPP 2
> > +#define VIRTIO_RTC_S_ENODEV     3
> > +#define VIRTIO_RTC_S_EINVAL     4
> > +#define VIRTIO_RTC_S_EIO        5
> > +\end{lstlisting}
> > +
> > +VIRTIO_RTC_S_OK indicates that the device successfully executed the
> > +request.
> > +
> > +If \field{status} is not VIRTIO_RTC_S_OK, the value of other response
> > +fields is undefined.
> > +
> > +VIRTIO_RTC_S_EOPNOTSUPP indicates that the device could not execute the
> > +specific request due to an implementation limitation. The device also
> > +returns status VIRTIO_RTC_S_EOPNOTSUPP for requests with unknown values
> > +in the fields \field{msg_type} or \field{hw_counter}.
> > +
> > +VIRTIO_RTC_S_ENODEV indicates that the \field{clock_id} field value
> > +supplied with the request does not identify a clock.
> > +
> > +VIRTIO_RTC_S_EINVAL indicates that
> > +
> > +\begin{itemize}
> > +\item the driver request values are not allowed by the specification or
> > +\item the device read-only part of the message, or the device write-only
> > +        part of the message, is too small to fit the actual message.
> > +\end{itemize}
> > +
> > +VIRTIO_RTC_S_EIO indicates that the device did not execute the request
> > +due to an error which was not caused by invalid input from the driver.
> 
> s/was/is

AFAIU this does not match with using past - "did not execute" - in the
main sentence.

> 
> > +
> > +All \field{reserved} fields are written as zero, and their value is
> > +ignored.
> > +
> > +The set of clocks does not change after feature negotiation completion,
> > +until device reset. The set of clocks should not change on device reset
> > +either (similar to negotiated features). Clock identifiers are
> > +zero-based, dense indices. All fields named \field{clock_id} contain
> > +clock identifiers.
> > +
> > +\subsubsection{Common Definitions}\label{sec:Device Types / RTC Device / Device Operation / Common Definitions}
> > +
> > +This section makes common definitions.
> > +
> > +\paragraph{Clock Types}\label{sec:Device Types / RTC Device / Device Operation / Common Definitions / Clock Types}
> > +
> > +The following clock types are defined:
> > +
> > +\begin{lstlisting}
> > +#define VIRTIO_RTC_CLOCK_UTC                    0
> > +#define VIRTIO_RTC_CLOCK_TAI                    1
> > +#define VIRTIO_RTC_CLOCK_MONOTONIC              2
> > +#define VIRTIO_RTC_CLOCK_UTC_SMEARED            3
> > +#define VIRTIO_RTC_CLOCK_UTC_MAYBE_SMEARED      4
> > +\end{lstlisting}
> > +
> > +\begin{description}
> > +
> > +\item[VIRTIO_RTC_CLOCK_UTC] uses the UTC (Coordinated Universal Time)
> > +        time standard. This clock uses the time epoch of January 1,
> > +        1970, 00:00 UTC. This is the same epoch as \emph{Unix time}. The
> > +        clock's seconds since the epoch are related to UTC time as
> > +        defined by \hyperref[intro:EPOCH]{EPOCH}.
> > +
> > +        This clock observes positive and negative leap seconds as
> > +        announced by standard bodies. At the start of leap seconds, the
> > +        clock steps accordingly.
> > +
> > +\item[VIRTIO_RTC_CLOCK_TAI] uses the TAI (International Atomic Time)
> > +        time standard. This clock uses the time epoch of January 1,
> > +        1970, 00:00 TAI.
> > +
> > +\item[VIRTIO_RTC_CLOCK_MONOTONIC] uses monotonic physical time (SI
> > +        seconds subdivisions) since some unspecified epoch. The epoch is
> > +        before or during device reset.
> > +
> > +\item[VIRTIO_RTC_CLOCK_UTC_SMEARED] deviates from the UTC standard by
> > +        smearing time in the vicinity of a leap second. This avoids
> > +        clock steps due to UTC leap seconds. Otherwise, this clock is
> > +        similar to VIRTIO_RTC_CLOCK_UTC.
> > +
> > +\item[VIRTIO_RTC_CLOCK_UTC_MAYBE_SMEARED] This clock
> > +
> > +\begin{itemize}
> > +\item may deviate from the UTC standard by smearing time in the vicinity
> > +        of a leap second (similar to VIRTIO_RTC_CLOCK_UTC_SMEARED), or
> > +
> > +\item may step at the start of leap seconds like VIRTIO_RTC_CLOCK_UTC.
> > +\end{itemize}
> > +
> > +A clock of type VIRTIO_RTC_CLOCK_UTC_MAYBE_SMEARED can change this
> > +behavior for every leap second.
> > +
> > +\end{description}
> > +
> > +In the following, \emph{UTC-like clock} designates any clock of type
> > +VIRTIO_RTC_CLOCK_UTC, VIRTIO_RTC_CLOCK_UTC_SMEARED, or
> > +VIRTIO_RTC_CLOCK_UTC_MAYBE_SMEARED.
> > +
> > +Additional clock types may be standardized in the future.
> > +Implementation-specific definitions of clock types are not recommended.
> > +Implementation-specific definitions use ids between 0xF0 and 0xFF.
> > +
> > +\paragraph{Smearing Variants}\label{sec:Device Types / RTC Device / Device Operation / Common Definitions / Smearing Variants}
> > +
> > +Leap second \emph{smearing variants} describe the deviation from the UTC
> > +standard in the vicinity of a leap second. The following smearing
> > +variants are currently defined:
> > +
> > +\begin{lstlisting}
> > +#define VIRTIO_RTC_SMEAR_UNSPECIFIED    0
> > +#define VIRTIO_RTC_SMEAR_NOON_LINEAR    1
> > +#define VIRTIO_RTC_SMEAR_UTC_SLS        2
> > +\end{lstlisting}
> > +
> > +\begin{description}
> > +
> > +        \item[VIRTIO_RTC_SMEAR_UNSPECIFIED] means that it is unspecified
> > +                how time is smeared in the vicinity of leap seconds.
> > +
> > +        \item[VIRTIO_RTC_SMEAR_NOON_LINEAR] specifies a linear smear
> > +                from noon prior to the leap second until noon after the
> > +                leap second.
> > +
> > +        \item[VIRTIO_RTC_SMEAR_UTC_SLS] specifies a linear smear as per
> > +                the \hyperref[intro:UTC-SLS]{UTC-SLS} proposal.
> > +
> > +\end{description}
> > +
> > +Clocks of type VIRTIO_RTC_CLOCK_UTC_SMEARED always behave according to a
> > +smearing variant. The smearing variant does not change over the clock's
> > +lifetime.
> > +
> > +For clocks of type VIRTIO_RTC_CLOCK_UTC_MAYBE_SMEARED, it is unspecified
> > +whether leap seconds are smeared, and how leap seconds are smeared.
> > +
> > +Additional smearing variants may be standardized in the future.
> > +Implementation-specific definitions of smearing variants are not
> > +recommended. Implementation-specific definitions use ids greater than or
> > +equal to 0xF0.
> > +
> > +In the following, \emph{leap smearing clock} designates
> > +
> > +\begin{itemize}
> > +
> > +\item any clock of type VIRTIO_RTC_CLOCK_UTC_SMEARED
> > +
> > +\item any clock of type VIRTIO_RTC_CLOCK_UTC_MAYBE_SMEARED at any time
> > +        when the clock is smearing a leap second.
> > +
> > +\end{itemize}
> > +
> > +\paragraph{Hardware Counters}\label{sec:Device Types / RTC Device / Device Operation / Common Definitions / Hardware Counters}
> > +
> > +The following hardware counter identifiers are specified:
> > +
> > +\begin{lstlisting}
> > +/* Arm Generic Timer Counter-timer Virtual Count Register (CNTVCT_EL0) */
> > +#define VIRTIO_RTC_COUNTER_ARM_VCT      0
> > +/* x86 Time-Stamp Counter */
> > +#define VIRTIO_RTC_COUNTER_X86_TSC      1
> > +/* Invalid */
> > +#define VIRTIO_RTC_COUNTER_INVALID   0xFF
> > +\end{lstlisting}
> > +
> > +Additional hardware counter identifiers may be standardized in the
> > +future. Implementation-specific hardware counter identifiers are not
> > +recommended. Implementation-specific hardware counter identifiers have
> > +values between 0xF0 and 0xFE.
> > +
> > +\subsubsection{Control Requests}\label{sec:Device Types / RTC Device / Device Operation / Control Requests}
> > +
> > +Through \emph{control requests}, the driver requests information about
> > +the device capabilities. The driver enqueues control requests in the
> > +requestq.
> > +
> > +\begin{description}
> > +
> > +\item[VIRTIO_RTC_REQ_CFG] discovers the number of clocks.
> > +
> > +\begin{lstlisting}
> > +#define VIRTIO_RTC_REQ_CFG 0x1000 /* message type */
> > +
> > +struct virtio_rtc_req_cfg {
> > +        struct virtio_rtc_req_head head;
> > +        /* no request params */
> > +};
> > +
> > +struct virtio_rtc_resp_cfg {
> > +        struct virtio_rtc_resp_head head;
> > +        le16 num_clocks;
> > +        u8 reserved[6];
> > +};
> > +\end{lstlisting}
> > +
> > +Field \field{num_clocks} contains the number of clocks. A device
> > +provides zero or more clocks. Valid clock ids are those smaller than
> > +\field{num_clocks}.
> > +
> > +\item[VIRTIO_RTC_REQ_CLOCK_CAP] discovers the capabilities of the clock
> > +identified by the \field{clock_id} field.
> > +
> > +\begin{lstlisting}
> > +#define VIRTIO_RTC_REQ_CLOCK_CAP 0x1001 /* message type */
> > +
> > +struct virtio_rtc_req_clock_cap {
> > +        struct virtio_rtc_req_head head;
> > +        le16 clock_id;
> > +        u8 reserved[6];
> > +};
> > +
> > +struct virtio_rtc_resp_clock_cap {
> > +        struct virtio_rtc_resp_head head;
> > +        u8 type;
> > +        u8 leap_second_smearing;
> > +        u8 reserved[6];
> > +};
> > +\end{lstlisting}
> > +
> > +The \field{type} field identifies the clock type. A device provides
> > +zero or more clocks for a clock type.
> > +
> > +Clocks of type VIRTIO_RTC_CLOCK_UTC_SMEARED indicate the \emph{smearing
> > +variant} through field \field{leap_second_smearing}. All other clocks
> > +set \field{leap_second_smearing} to VIRTIO_RTC_SMEAR_UNSPECIFIED.
> > +
> > +\item[VIRTIO_RTC_REQ_CROSS_CAP] discovers whether the device supports
> > +cross-timestamping for a particular pair of clock and hardware counter.
> > +
> > +\begin{lstlisting}
> > +#define VIRTIO_RTC_REQ_CROSS_CAP 0x1002 /* message type */
> > +
> > +struct virtio_rtc_req_cross_cap {
> > +        struct virtio_rtc_req_head head;
> > +        le16 clock_id;
> > +        u8 hw_counter;
> > +        u8 reserved[5];
> > +};
> > +
> > +
> > +struct virtio_rtc_resp_cross_cap {
> > +        struct virtio_rtc_resp_head head;
> > +#define VIRTIO_RTC_FLAG_CROSS_CAP       (1 << 0)
> > +        u8 flags;
> > +        u8 reserved[7];
> > +};
> > +\end{lstlisting}
> > +
> > +The \field{clock_id} field identifies the clock, and the
> > +\field{hw_counter} field identifies the hardware counter, for which
> > +cross-timestamp support is probed. The device sets the
> > +VIRTIO_RTC_FLAG_CROSS_CAP flag in the \field{flags} field if the clock
> > +supports cross-timestamping for the particular clock and hardware
> > +counter, and clears the flag otherwise.
> > +
> > +\end{description}
> > +
> > +\subsubsection{Read Requests}\label{sec:Device Types / RTC Device / Device Operation / Read Requests}
> > +
> > +Through \emph{read requests}, the driver requests clock readings from
> > +the device. The driver enqueues read requests in the requestq. The
> > +device obtains device-side clock readings and forwards these clock
> > +readings to the driver. The driver may enhance and interpret the clock
> > +readings through methods which are beyond the scope of this
> > +specification.
> > +
> > +Once DRIVER_OK has been set, the device should support reading every
> > +clock, even when a clock may yet have to be aligned to reference time
> > +sources.
> > +
> > +In general,
> > +
> > +\begin{itemize}
> > +\item clocks may jump backwards or forward, and
> > +\item the clock frequency may change. Clocks may be \emph{slewed},
> > +        i.e.\ clocks may run at a frequency other than their current
> > +        best frequency estimate.
> > +\end{itemize}
> > +
> > +As long as a clock does not jump backwards, the driver clock readings
> > +through read request responses increase monotonically:
> > +
> > +\begin{itemize}
> > +\item As long as a clock does not jump backwards in-between device-side
> > +        clock readings, the driver-side readings for that clock increase
> > +        monotonically as well, in the order in which the driver
> > +        marks read requests as available.
> > +
> > +\item The device marks read requests for the same clock as used in
> > +        the order in which the messages were marked as available.
> > +\end{itemize}
> > +
> > +For a clock of type VIRTIO_RTC_CLOCK_MONOTONIC, the device always returns
> > +monotonically increasing clock readings through read request responses.
> > +
> > +The unit of all \field{clock_reading} fields is 1
> > +nanosecond.\footnote{For time epochs in year 1970 or later, this means
> > +that time until at least year 2553 can be represented in the \field{le64
> > +clock_reading} fields.}
> > +
> > +\begin{description}
> > +
> > +\item[VIRTIO_RTC_REQ_READ] reads the clock identified by the
> > +\field{clock_id} field. The device supports this message for every
> > +clock.
> > +
> > +\begin{lstlisting}
> > +#define VIRTIO_RTC_REQ_READ 0x0001 /* message type */
> > +
> > +struct virtio_rtc_req_read {
> > +        struct virtio_rtc_req_head head;
> > +        le16 clock_id;
> > +        u8 reserved[6];
> > +};
> > +
> > +struct virtio_rtc_resp_read {
> > +        struct virtio_rtc_resp_head head;
> > +        le64 clock_reading;
> > +};
> > +\end{lstlisting}
> > +
> > +\field{clock_reading} is a device-side clock reading obtained after the
> > +message was marked as available.
> 
> s/was/is

Like this?

	\field{clock_reading} is a device-side clock reading obtained
	once the message is marked as available.

AFAIU with this change "marked as available" would be viewed as a state,
not as an event. Would this really be better?

Thanks for the comments,

Peter

Re: [PATCH v8 2/4] virtio-rtc: Add initial normative statements

[Peter Hilber]

On Tue, Apr 15, 2025 at 06:03:12PM +0200, Matias Ezequiel Vara Larsen wrote:
> On Thu, Mar 06, 2025 at 10:51:10AM +0100, Peter Hilber wrote:
> > Add the normative statements for the initial device specification.
> > 
> > Signed-off-by: Peter Hilber <quic_philber@quicinc.com>
> > ---
> > 
> > Notes:
> >     v8:
> >     
> >     - Drop requirement to ignore reserved fields in the device-readable part
> >       of the message (Matias Ezequiel Vara Larsen).
> >     
> >     - Drop requirement about returning same status in response to identical
> >       requests (Matias Ezequiel Vara Larsen).
> >     
> >     - Reword requirements about size mismatches for device
> >       read-only/write-only parts of the message (Matias Ezequiel Vara
> >       Larsen).
> >     
> >     - Change word order from "field X" to "the X field" (Matias Ezequiel
> >       Vara Larsen).
> >     
> >     v7:
> >     
> >     - Remove obsolete requirements for leap second indication.
> >     
> >     v6:
> >     
> >     - Update requirements to make leap second status information optional if
> >       if the clock smears (or might smear) leap seconds.
> >     
> >     - Allow indicating VIRTIO_RTC_SMEAR_UNSPECIFIED for
> >       VIRTIO_RTC_CLOCK_SMEARED.
> >     
> >     - Shorten some requirements by omitting redundant information.
> >     
> >     v5:
> >     
> >     - Update normative statements to match v5 changes to non-normative
> >       statements (patch 1).
> >     
> >     v4:
> >     
> >     - Require driver to set unused flags to zero.
> >     
> >     - Update normative statements to match v4 changes to non-normative
> >       statements (patch 1).
> >     
> >     - Improve formatting.
> > 
> >  conformance.tex                         |   2 +
> >  device-types/rtc/description.tex        | 272 +++++++++++++++++++++++-
> >  device-types/rtc/device-conformance.tex |   9 +
> >  device-types/rtc/driver-conformance.tex |   9 +
> >  4 files changed, 288 insertions(+), 4 deletions(-)
> >  create mode 100644 device-types/rtc/device-conformance.tex
> >  create mode 100644 device-types/rtc/driver-conformance.tex
> > 
> > diff --git a/conformance.tex b/conformance.tex
> > index d92a2369488e..4ce86a525e84 100644
> > --- a/conformance.tex
> > +++ b/conformance.tex
> > @@ -162,6 +162,7 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets}
> >  \input{device-types/pmem/driver-conformance.tex}
> >  \input{device-types/can/driver-conformance.tex}
> >  \input{device-types/spi/driver-conformance.tex}
> > +\input{device-types/rtc/driver-conformance.tex}
> >  
> >  \conformance{\section}{Device Conformance}\label{sec:Conformance / Device Conformance}
> >  
> > @@ -254,6 +255,7 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets}
> >  \input{device-types/pmem/device-conformance.tex}
> >  \input{device-types/can/device-conformance.tex}
> >  \input{device-types/spi/device-conformance.tex}
> > +\input{device-types/rtc/device-conformance.tex}
> >  
> >  \conformance{\section}{Legacy Interface: Transitional Device and Transitional Driver Conformance}\label{sec:Conformance / Legacy Interface: Transitional Device and Transitional Driver Conformance}
> >  A conformant implementation MUST be either transitional or
> > diff --git a/device-types/rtc/description.tex b/device-types/rtc/description.tex
> > index 5d8cf91a6991..f2a3907de511 100644
> > --- a/device-types/rtc/description.tex
> > +++ b/device-types/rtc/description.tex
> > @@ -73,7 +73,7 @@ \subsection{Device Operation}\label{sec:Device Types / RTC Device / Device Opera
> >  VIRTIO_RTC_S_EOPNOTSUPP indicates that the device could not execute the
> >  specific request due to an implementation limitation. The device also
> >  returns status VIRTIO_RTC_S_EOPNOTSUPP for requests with unknown values
> > -in the fields \field{msg_type} or \field{hw_counter}.
> > +in the \field{msg_type} or \field{hw_counter} fields.
> >  
> >  VIRTIO_RTC_S_ENODEV indicates that the \field{clock_id} field value
> >  supplied with the request does not identify a clock.
> > @@ -98,6 +98,106 @@ \subsection{Device Operation}\label{sec:Device Types / RTC Device / Device Opera
> >  zero-based, dense indices. All fields named \field{clock_id} contain
> >  clock identifiers.
> >  
> > +\drivernormative{\subsubsection}{Device Operation}{Device Types / RTC Device / Device Operation}
> > +
> > +If the \field{struct virtio_rtc_resp_head} field \field{status} is not
> > +VIRTIO_RTC_S_OK, the driver MUST NOT interpret response fields other
> > +than \field{status}.
> 
> Can't we say "The driver MUST interpret response field only when status
> is VIRTIO_RTC_S_OK".

OK.

> 
> > +
> > +The driver MUST set \emph{reserved} fields in the device-readable part
> > +of the message to zero.
> > +
> > +The driver MUST set unnamed bits in \emph{flags} fields in the
> > +device-readable part of the message to zero.
> > +
> > +The driver MUST NOT interpret \emph{reserved} fields in the
> > +device-writable part of the message.
> 
> Why the driver would interpret reserved fields?

The driver shall not do this in any way. Especially, the driver shall
not fail due to unexpected reserved field values. 

> 
> > +
> > +The driver MUST NOT interpret unnamed bits in \emph{flags} fields in the
> > +device-writable part of the message.
> > +
> > +The driver MUST put the request into the device-readable part of the
> > +message.
> 
> I do not think this is required in this section. The spec defines the
> device-readable as the only section in which the driver can write. Other
> devices just add in "// Device-readable part" in the common structures
> for the response and request. Are other devices specifying something
> similar? 
> 

I can remove this. There are some requirements about the queues where to
put device-readable/device-writable buffers for other devices, like the
console device, but none which explicitly specify the readable/writable
split.

> > +
> > +The driver MUST allocate enough space for the response in the
> > +device-writable part of a requestq message.
> > +
> > +\devicenormative{\subsubsection}{Device Operation}{Device Types / RTC Device / Device Operation}
> > +
> > +For \field{struct virtio_rtc_resp_head}, the device MUST set the
> > +\field{status} field to VIRTIO_RTC_S_OK if the device successfully
> > +executed the request.
> > +
> > +For \field{struct virtio_rtc_resp_head}, the device MUST set the
> > +\field{status} field to a status other than VIRTIO_RTC_S_OK if the
> > +device did not successfully execute the request.
> > +
> > +For \field{struct virtio_rtc_resp_head}, the device MUST set the
> > +\field{status} field to VIRTIO_RTC_S_EOPNOTSUPP if the device could not
> > +execute the specific request due to an implementation limitation.
> > +
> > +For \field{struct virtio_rtc_resp_head}, the device MUST set the
> > +\field{status} field to VIRTIO_RTC_S_EOPNOTSUPP for a request with a
> > +value of the \field{msg_type} field which is not described in this
> > +specification.
> > +
> > +For \field{struct virtio_rtc_resp_head}, the device MUST set the
> > +\field{status} field to VIRTIO_RTC_S_EOPNOTSUPP for a request with a
> > +value of the \field{hw_counter} field which is neither described in this
> > +specification nor otherwise known to the implementation.
> > +
> > +For \field{struct virtio_rtc_resp_head}, the device MUST set the
> > +\field{status} field to VIRTIO_RTC_S_ENODEV if the \field{clock_id}
> > +field value supplied with the request does not identify a clock.
> > +
> > +For \field{struct virtio_rtc_resp_head}, the device MUST set the
> > +\field{status} field to VIRTIO_RTC_S_EINVAL if the request values are
> > +inconsistent with the specification and if the inconsistence is not
> > +described by the requirements which stipulate status
> > +VIRTIO_RTC_S_EOPNOTSUPP or VIRTIO_RTC_S_ENODEV.
> > +
> > +For \field{struct virtio_rtc_resp_head}, the device MUST set the
> > +\field{status} field to VIRTIO_RTC_S_EINVAL if the request specified in
> > +the request header through the \field{msg_type} field does not fit into
> > +the device read-only part of the actual message.
> > +
> > +For \field{struct virtio_rtc_resp_head}, the device MUST set the
> > +\field{status} field to VIRTIO_RTC_S_EINVAL if the response specified in
> > +the request header through the \field{msg_type} field does not fit into
> > +the device write-only part of the actual message, unless the
> > +\field{status} field does not fit into the device write-only part.
> > +
> > +For \field{struct virtio_rtc_resp_head}, the device MUST NOT set the
> > +\field{status} field if the \field{status} field does not fit into the
> > +device write-only part.
> > +
> > +For \field{struct virtio_rtc_resp_head}, the device MUST set the
> > +\field{status} field to VIRTIO_RTC_S_EIO if none of the previous
> > +requirements in this document stipulated another \field{status}.
> > +
> > +If the device read-only part of a message M is bigger than the size of
> > +the request specified for message M, the device MUST ignore the
> > +additional space.
> > +
> > +If the device write-only part of a message M is bigger than the size of
> > +the response specified for message M, the device MUST ignore the
> > +additional space.
> > +
> > +The device MUST set \emph{reserved} fields in the device-writable part
> > +of the message to zero.
> > +
> > +The device MUST set unnamed bits in \emph{flags} fields in the
> > +device-writable part of the message to zero.
> > +
> > +After feature negotiation completion the device MUST NOT change the set
> > +of clocks until device reset.
> > +
> > +The device SHOULD NOT change the set of clocks on a device reset after
> > +the first device reset.
> > +
> > +The device MUST use non-negative integers, which are smaller than the
> > +number of clocks, as clock identifiers.
> > +
> >  \subsubsection{Common Definitions}\label{sec:Device Types / RTC Device / Device Operation / Common Definitions}
> >  
> >  This section makes common definitions.
> > @@ -253,7 +353,7 @@ \subsubsection{Control Requests}\label{sec:Device Types / RTC Device / Device Op
> >  };
> >  \end{lstlisting}
> >  
> > -Field \field{num_clocks} contains the number of clocks. A device
> > +The \field{num_clocks} field contains the number of clocks. A device
> >  provides zero or more clocks. Valid clock ids are those smaller than
> >  \field{num_clocks}.
> >  
> > @@ -281,8 +381,8 @@ \subsubsection{Control Requests}\label{sec:Device Types / RTC Device / Device Op
> >  zero or more clocks for a clock type.
> >  
> >  Clocks of type VIRTIO_RTC_CLOCK_UTC_SMEARED indicate the \emph{smearing
> > -variant} through field \field{leap_second_smearing}. All other clocks
> > -set \field{leap_second_smearing} to VIRTIO_RTC_SMEAR_UNSPECIFIED.
> > +variant} through the \field{leap_second_smearing} field. All other
> > +clocks set \field{leap_second_smearing} to VIRTIO_RTC_SMEAR_UNSPECIFIED.
> >  
> >  \item[VIRTIO_RTC_REQ_CROSS_CAP] discovers whether the device supports
> >  cross-timestamping for a particular pair of clock and hardware counter.
> > @@ -315,6 +415,103 @@ \subsubsection{Control Requests}\label{sec:Device Types / RTC Device / Device Op
> >  
> >  \end{description}
> >  
> > +\drivernormative{\paragraph}{Control Requests}{Device Types / RTC Device / Device Operation / Control Requests}
> > +
> > +For VIRTIO_RTC_REQ_CROSS_CAP, the driver MUST set \field{hw_counter} to
> > +one of the hardware counter identifiers defined in this specification,
> > +or to a value between 0xF0 and 0xFE.
> > +
> > +\devicenormative{\paragraph}{Control Requests}{Device Types / RTC Device / Device Operation / Control Requests}
> > +
> > +For any clock of type VIRTIO_RTC_CLOCK_UTC, the device MUST use the UTC
> > +time standard (Coordinated Universal Time).
> > +
> > +For any clock of type VIRTIO_RTC_CLOCK_UTC_SMEARED or
> > +VIRTIO_RTC_CLOCK_UTC_MAYBE_SMEARED, the device MUST use the UTC time
> > +standard, insofar as the following requirements do not say otherwise.
> > +
> > +For any UTC-like clock, the device MUST use the time epoch of January 1,
> > +1970, 00:00 UTC.
> > +
> > +For any UTC-like clock, the device MUST count seconds since the epoch
> > +according to \hyperref[intro:EPOCH]{EPOCH}.
> > +
> > +For any clock of type VIRTIO_RTC_CLOCK_UTC, the device MUST apply a
> > +positive leap second according to the UTC time standard by
> > +instantaneously stepping the clock backwards by 1 s at the start of the
> > +leap second.
> > +
> > +For any clock of type VIRTIO_RTC_CLOCK_UTC, the device MUST apply a
> > +negative leap second according to the UTC time standard by
> > +instantaneously stepping the clock forward by 1 s at the start of the
> > +leap second.
> > +
> > +For any leap smearing clock, the device MUST NOT step the clock due to a
> > +leap second.
> > +
> > +For any leap smearing clock, on a positive leap second, the device MUST
> > +slow down the clock during part of the day containing the leap second
> > +and/or part of the day after the leap second.
> > +
> > +For any leap smearing clock, on a negative leap second, the device MUST
> > +speed up the clock during part of the day containing the leap second
> > +and/or part of the day after the leap second.
> > +
> > +For any clock with smearing variant VIRTIO_RTC_SMEAR_NOON_LINEAR, on a
> > +leap second, the device MUST change the frequency of the clock exactly
> > +from noon prior to the leap second until noon after the leap second.
> > +
> > +For any clock with smearing variant VIRTIO_RTC_SMEAR_NOON_LINEAR, while
> > +changing the frequency of the clock due to a positive leap second, the
> > +device MUST decrease the frequency of the clock by $1/86400$.
> > +
> > +For any clock with smearing variant VIRTIO_RTC_SMEAR_NOON_LINEAR, while
> > +changing the frequency of the clock due to a negative leap second, the
> > +device MUST increase the frequency of the clock by $1/86400$.
> > +
> > +For any clock with smearing variant VIRTIO_RTC_SMEAR_UTC_SLS, on a leap
> > +second, the device MUST change the frequency of the clock exactly during
> > +the last 1000 seconds of the day with the leap second.
> > +
> > +For any clock with smearing variant VIRTIO_RTC_SMEAR_UTC_SLS, while
> > +changing the frequency of the clock due to a positive leap second, the
> > +device MUST decrease the frequency of the clock by 0.1\%.
> > +
> > +For any clock with smearing variant VIRTIO_RTC_SMEAR_UTC_SLS, while
> > +changing the frequency of the clock due to a negative leap second, the
> > +device MUST increase the frequency of the clock by 0.1\%.
> > +
> > +For any clock of type VIRTIO_RTC_CLOCK_UTC_MAYBE_SMEARED, the device MAY
> > +deviate from the UTC standard with respect to leap second introduction.
> > +
> > +For any clock of type VIRTIO_RTC_CLOCK_TAI, the device MUST use the TAI
> > +time standard (International Atomic Time).
> > +
> > +For any clock of type VIRTIO_RTC_CLOCK_TAI, the device MUST use the time
> > +epoch of January 1, 1970, 00:00 TAI.
> > +
> > +For any clock of type VIRTIO_RTC_CLOCK_MONOTONIC, the device MUST use SI
> > +seconds subdivisions.
> > +
> > +For any clock of type VIRTIO_RTC_CLOCK_MONOTONIC, the device MUST use an
> > +epoch at a time instant before or during device reset.
> > +
> > +For VIRTIO_RTC_REQ_CLOCK_CAP, and clock types other than
> > +VIRTIO_RTC_CLOCK_UTC_SMEARED, the device MUST set the
> > +\field{leap_second_smearing} field to VIRTIO_RTC_SMEAR_UNSPECIFIED.
> > +
> > +For VIRTIO_RTC_REQ_CLOCK_CAP, and clock type
> > +VIRTIO_RTC_CLOCK_UTC_SMEARED, the device MUST set the
> > +\field{leap_second_smearing} field to VIRTIO_RTC_SMEAR_UNSPECIFIED,
> > +VIRTIO_RTC_SMEAR_NOON_LINEAR, VIRTIO_RTC_SMEAR_UTC_SLS, or to a value
> > +greater than or equal to 0xF0.
> > +
> > +For a VIRTIO_RTC_REQ_CROSS_CAP message M, the device MUST set the
> > +VIRTIO_RTC_FLAG_CROSS_CAP flag in the \field{flags} field if the device
> > +would respond to a VIRTIO_RTC_REQ_READ_CROSS message with the same
> > +\field{hw_counter} and \field{clock_id} values as in M with status
> > +VIRTIO_RTC_S_OK, and clear the flag otherwise.
> 
> I wonder if we could rewrite this sentence to make it more clear.

How about

	The device SHOULD set the VIRTIO_RTC_FLAG_CROSS_CAP flag in the
	VIRTIO_RTC_REQ_CROSS_CAP response if and only if the device
	would return status VIRTIO_RTC_S_OK for a
	VIRTIO_RTC_REQ_READ_CROSS message with the same
	\field{hw_counter} and \field{clock_id} values.

In the above, I also changed the requirement from MUST to SHOULD, since
I think that there might be intermittent error conditions which are
acceptable for the device not to detect when processing the
VIRTIO_RTC_REQ_CROSS_CAP message.

> 
> > +
> >  \subsubsection{Read Requests}\label{sec:Device Types / RTC Device / Device Operation / Read Requests}
> >  
> >  Through \emph{read requests}, the driver requests clock readings from
> > @@ -426,3 +623,70 @@ \subsubsection{Read Requests}\label{sec:Device Types / RTC Device / Device Opera
> >  \ref{sec:Device Types / RTC Device / Device Operation / Common Definitions / Hardware Counters}.
> >  
> >  \end{description}
> > +
> > +\drivernormative{\paragraph}{Read Requests}{Device Types / RTC Device / Device Operation / Read Requests}
> > +
> > +For VIRTIO_RTC_REQ_READ_CROSS, the driver MUST set \field{hw_counter} to
> > +one of the hardware counter identifiers defined in this specification,
> > +or to a value between 0xF0 and 0xFE.
> > +
> > +\devicenormative{\paragraph}{Read Requests}{Device Types / RTC Device / Device Operation / Read Requests}
> > +
> > +The device SHOULD continuously support reading of all clocks once
> > +DRIVER_OK has been set.
> > +
> 
> I think you can rewrite as: "After DRIVER_OK has been set, the device
> SHOULD continuously support reading of all clocks."

OK.

> 
> > +For any clock C and read requests \emph{A} and \emph{B} which read C,
> > +\emph{A} being the message which the driver marks as available before
> > +\emph{B}, the device MUST obtain the \field{clock_reading} value for the
> > +message \emph{A} response before the \field{clock_reading} value for the
> > +message \emph{B} response, or the device MUST obtain the same
> > +\field{clock_reading} value for both \emph{A} and \emph{B}.
> > +
> 
> I wonder how we can rewrite it without A, B, and C.

How is using short instance names a problem? Looking at e.g. the C
standard, such naming is used to avoid ambiguity.

Is this better?

	For any two read requests to the same clock, the device MUST
	either obtain the \field{clock_reading} value for the message
	which the driver makes available first before obtaining the
	\field{clock_reading} value for the other message, or the device
	MUST return the same \field{clock_reading} value.

> 
> > +For any clock C, the device MUST mark all read requests reading C as
> > +used in the total order in which the driver marked these messages as
> > +available.
> > +
> > +For any clock C of type VIRTIO_RTC_CLOCK_MONOTONIC and read requests
> > +\emph{A} and \emph{B} which read C, \emph{A} being the message which the
> > +driver marks as available before \emph{B}, the device MUST set the
> > +\field{clock_reading} value for the message \emph{B} response to a value
> > +greater than or equal to the \field{clock_reading} value for the message
> > +\emph{A} response.
> > +
> > +The device MUST support VIRTIO_RTC_REQ_READ for every clock.
> 
> I would start the sentence by:
> 
> "For every clock, ..."

OK.

> 
> > +
> > +For VIRTIO_RTC_REQ_READ and for any clock type listed in this
> > +specification, the device MUST use the nanosecond as unit for the
> > +\field{clock_reading} field.
> > +
> > +For read requests, the device MUST obtain the \field{clock_reading}
> > +response value after the read request is marked as available.
> 
> This is not clear. Who mark the read request available? I think ti is
> the driver. The device cannot access anything in the available ring
> without driver notification.

To avoid ambiguity:

	For read requests, the device MUST obtain the
	\field{clock_reading} response value after the driver made the
	read request available.

> 
> > +
> > +For VIRTIO_RTC_REQ_READ_CROSS, the device MUST set
> > +\field{counter_cycles} to a value which approximates the value which the
> > +driver would have read from the hardware counter identified by
> > +\field{hw_counter} at the time instant when the device read the
> > +\field{clock_reading} value.
> > +
> > +For VIRTIO_RTC_REQ_READ_CROSS, the device SHOULD assume that the driver
> > +reads the hardware counter identified by \field{hw_counter} through the
> > +CPU which the driver enumerates as the first.
> > +
> > +For VIRTIO_RTC_REQ_READ_CROSS, the device MUST set \field{status} to a
> > +value other than VIRTIO_RTC_S_OK if the device cannot determine the
> > +approximate value which the driver would have read from the hardware
> > +counter identified by \field{hw_counter} at the time instant when the
> > +device read the \field{clock_reading} value.
> > +
> > +For any clock C, and VIRTIO_RTC_REQ_READ_CROSS messages \emph{A} and
> > +\emph{B} which read C and which specify the same hardware counter
> > +\emph{H} through the \field{hw_counter} field, \emph{A} being the
> > +message which the driver marks as available before \emph{B}, the device
> > +MUST set the \field{counter_cycles} value for \emph{B} to a value which
> > +\emph{H} shows after the \field{counter_cycles} value of \emph{A}, or
> > +the device MUST set the same \field{counter_cycles} value for \emph{A}
> > +and \emph{B}.
> 
> I just rewrite this sentence as the following, WDYT?:
> 
> If two VIRTIO_RTC_REQ_READ_CROSS messages read the same clock using the
> same hardware counter, and one message is made available before the
> other, the device must do one of the following:
> 
> - Set the later message's counter_cycles to a value that the hardware
>   counter shows after the earlier message's counter_cycles.
> - Or, set both messages to have the same counter_cycles value.

Like this?

	If two VIRTIO_RTC_REQ_READ_CROSS messages read the same clock
	using the same hardware counter, and one message is made
	available before the other, the device MUST either
	
	- set the later message's counter_cycles to a value that the
	  hardware counter shows after the earlier message's
	  counter_cycles, or
	
	- set both messages to have the same counter_cycles value.

Thanks for the comments,

Peter

Re: [PATCH v8 3/4] virtio-rtc: Add alarm feature

[Peter Hilber]

On Wed, Apr 16, 2025 at 10:17:33AM +0200, Matias Ezequiel Vara Larsen wrote:
> On Thu, Mar 06, 2025 at 10:51:11AM +0100, Peter Hilber wrote:
> > Add the VIRTIO_RTC_F_ALARM feature (without normative statements).
> > 
> > The intended use case is: A driver needs to react when an alarm time has
> > been reached, but at alarm time, the driver may be in a sleep state or
> > powered off. The alarm feature can resume and notify the driver in this
> > case. Alarms may be retained across device resets (including reset on
> > boot).
> > 
> > Peculiarities
> > -------------
> > 
> > Unlike usual alarm clocks, a virtio-rtc alarm-capable clock may step
> > autonomously at any time: An alarm may change back from "expired" to
> > "not expired" before the driver has started processing an alarm
> > notification.
> > 
> > To address the above, and the device resets, define "alarm expiration"
> > in such a way that the driver always has a chance to react to an alarm,
> > and make the device always responsible for notifying the driver about an
> > alarm expiration.
> > 
> > The VIRTIO_RTC_REQ_SET_ALARM_ENABLED request is there so that the Linux
> > ioctls RTC_AIE_ON and RTC_AIE_OFF only need to emit one request.
> > 
> > Signed-off-by: Peter Hilber <quic_philber@quicinc.com>
> > ---
> > 
> > Notes:
> >     v8:
> >     
> >     - Explicitly describe alarm enabled status, where relevant (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".
> >     
> >     - Change "once" to "when" (Matias Ezequiel Vara Larsen).
> >     
> >     v7:
> >     
> >     - Change flag numeric value due to removing leap second indication.
> >     
> >     v5:
> >     
> >     - Reformat.
> >     
> >     v4:
> >     
> >     - Change requirements so that driver can reset alarm to clean slate, and
> >       document how driver can achieve this (Cornelia Hell, Jason Wang) [1].
> >     
> >     - Require device to support all expressible alarm times.
> >     
> >     - Formatting and wording improvements.
> >     
> >     [1] https://lore.kernel.org/all/2ae67401-a8f5-4686-9321-cb3105df594d@opensynergy.com/
> > 
> >  device-types/rtc/description.tex | 262 ++++++++++++++++++++++++++++++-
> >  1 file changed, 260 insertions(+), 2 deletions(-)
> > 
> > diff --git a/device-types/rtc/description.tex b/device-types/rtc/description.tex
> > index f2a3907de511..93bcf178b042 100644
> > --- a/device-types/rtc/description.tex
> > +++ b/device-types/rtc/description.tex
> > @@ -4,6 +4,7 @@ \section{RTC Device}\label{sec:Device Types / RTC Device}
> >  time. The device can provide different clocks, e.g.\ for the UTC or TAI
> >  time standards, or for physical time elapsed since some past epoch. The
> >  driver can read the clocks with simple or more accurate methods.
> > +Optionally, the driver can set an alarm.
> >  
> >  \subsection{Device ID}\label{sec:Device Types / RTC Device / Device ID}
> >  
> > @@ -13,13 +14,23 @@ \subsection{Virtqueues}\label{sec:Device Types / RTC Device / Virtqueues}
> >  
> >  \begin{description}
> >  \item[0] requestq
> > +\item[1] alarmq
> >  \end{description}
> >  
> >  The driver enqueues requests to the requestq.
> >  
> > +Through the alarmq, the device notifies the driver about alarm
> > +expirations. The alarmq exists only if VIRTIO_RTC_F_ALARM was
> > +negotiated.
> > +
> >  \subsection{Feature bits}\label{sec:Device Types / RTC Device / Feature bits}
> >  
> > -No device-specific feature bits are defined yet.
> > +\begin{description}
> > +\item[VIRTIO_RTC_F_ALARM (0)] Device supports alarm.
> > +\end{description}
> > +
> > +VIRTIO_RTC_F_ALARM determines whether the device supports setting an
> > +alarm for some of the clocks.
> >  
> >  \subsection{Device configuration layout}\label{sec:Device Types / RTC Device / Device configuration layout}
> >  
> > @@ -373,7 +384,8 @@ \subsubsection{Control Requests}\label{sec:Device Types / RTC Device / Device Op
> >          struct virtio_rtc_resp_head head;
> >          u8 type;
> >          u8 leap_second_smearing;
> > -        u8 reserved[6];
> > +        u8 flags;
> > +        u8 reserved[5];
> >  };
> >  \end{lstlisting}
> >  
> > @@ -384,6 +396,15 @@ \subsubsection{Control Requests}\label{sec:Device Types / RTC Device / Device Op
> >  variant} through the \field{leap_second_smearing} field. All other
> >  clocks set \field{leap_second_smearing} to VIRTIO_RTC_SMEAR_UNSPECIFIED.
> >  
> > +The \field{flags} field provides the following information:
> > +
> > +\begin{lstlisting}
> > +#define VIRTIO_RTC_FLAG_ALARM_CAP               (1 << 0)
> > +\end{lstlisting}
> > +
> > +If VIRTIO_RTC_F_ALARM was negotiated, the VIRTIO_RTC_FLAG_ALARM_CAP flag
> > +indicates that the clock supports an alarm.
> > +
> >  \item[VIRTIO_RTC_REQ_CROSS_CAP] discovers whether the device supports
> >  cross-timestamping for a particular pair of clock and hardware counter.
> >  
> > @@ -690,3 +711,240 @@ \subsubsection{Read Requests}\label{sec:Device Types / RTC Device / Device Opera
> >  For VIRTIO_RTC_REQ_READ_CROSS and for any clock type listed in this
> >  specification, the device MUST use the nanosecond as unit for the
> >  \field{clock_reading} field.
> > +
> > +\subsubsection{Alarm Operation}\label{sec:Device Types / RTC Device / Device Operation / Alarm Operation}
> > +
> > +Through the optional alarm feature, the driver can set an alarm time. On
> > +alarm expiration, the device notifies the driver. On alarm expiration,
> > +the device may also wake up the driver, while the driver is in a sleep
> > +state, or while the driver is powered off. How this is done is beyond
> > +the scope of the specification. The driver can set one alarm time per
> > +clock, if the clock supports this.
> > +
> > +The device may retain alarm times across device resets.\footnote{Drivers
> > +        may reset the device on boot or on resume from sleep state. It
> > +        can make sense for the device to retain the alarm time then,
> > +        similar to other alarm clocks.}
> > +
> > +The alarm feature, and the associated alarmq for notifications from the
> > +device, are available if VIRTIO_RTC_F_ALARM was negotiated. 
> 
> "If the VIRTIO_xxx has been negotiated, ..."

Like this?

	If VIRTIO_RTC_F_ALARM has been negotiated, the device supports
	the alarm feature and the associated alarmq for notifications
	from the device.

> 
> > In addition,
> > +if the driver previously set an alarm time, even if the device no longer
> > +both
> > +
> > +\begin{itemize}
> > +\item is live and
> > +\item has negotiated VIRTIO_RTC_F_ALARM,
> > +\end{itemize}
> > +
> > +the device may still execute implementation-specific actions on alarm
> > +expiration.
> > +
> > +An alarm expires
> 
> I think you can add the "when" after "expires" and then remove it
> afterward.

Does this not hurt the legibility of the long sentences?

> 
> > +
> > +\begin{itemize}
> > +\item when the associated clock progresses (also: steps) from a time
> > +        prior to the alarm time to the alarm time, or to a time after
> > +        the alarm time, while the alarm is enabled, or
> > +
> > +\item when the driver sets an alarm time which is not in the future,
> > +        while also setting the alarm to enabled, or
> > +
> > +\item when the driver sets the alarm to enabled, and the alarm time is
> > +        not in the future, or
> > +
> > +\item when the device is reset, if the alarm time is retained and not in
> > +        the future, and if the alarm is enabled.\footnote{The device is
> > +                always responsible for detecting alarm expiration
> > +                events. This avoids that the driver needs to reason
> > +                about when it shall poll for alarm expiration.}
> > +\end{itemize}
> > +
> > +When an alarm expires, the driver can disable it. Otherwise, the alarm
> > +expires each time when one of the above expiration events occurs, even
> > +if it occurred before.\footnote{This avoids that the driver may
> > +        miss an alarm when the clock steps backwards after alarm
> > +        expiration, but before the driver has resumed operation. This
> > +        also facilitates distinct drivers using the same device,
> > +        e.g.\ a driver in the bootloader, and a driver in the OS.}
> > +
> > +On alarm expiration, the device executes the alarm actions. The alarm
> > +actions are:
> > +
> > +\begin{itemize}
> > +\item The device notifies the driver through the alarmq. If the device
> > +        is not live, or no buffers are available in the alarmq, the
> > +        device will notify once the device is live and buffers are
> > +        available.
> > +
> > +\item Optionally, the device executes other, implementation-specific,
> > +        actions. The device may execute those immediately, regardless of
> > +        the device state.
> > +\end{itemize}
> > +
> 
> I think that, on alarm expiration, you can remove the optionally part
> and then just talk about alarm expiration thus removing the `alarm
> actions` wording.  

My concern about this is that readers may not understand that alarm
expiration can still have consequences while the device is in reset
state. And the alarm feature mostly makes sense for cases where the
driver is in a sleep state, and where, by consequence, the device may be
in reset state.

> 
> > +An alarm \emph{expiration} becomes obsolete
> > +
> > +\begin{itemize}
> > +\item when the driver disables the alarm, or
> > +
> > +\item when the driver sets an alarm time, or
> > +
> > +\item when the clock jumps backwards, before the alarm time, or
> > +
> > +\item when another alarm expiration event happens.
> > +\end{itemize}
> > +
> > +If an alarm expiration becomes obsolete, it is unspecified which alarm
> > +actions the device executes for this alarm expiration, and the device
> > +stops executing these alarm actions after a grace period.
> 
> Can't you leave this paragraph implementation-specific and thus
> removing it completely?

OK.

> 
> > +
> > +The device supports all alarm time values which the driver can request
> > +through alarm control requests.
> > +
> > +Initially, the alarm time is the epoch of the clock ($0$), and the alarm
> > +is disabled.
> 
> I would rewrite it as:
> 
> "Every alarm initializes with an alarm time to 0 and disabled."

To me, this seems grammatically inconsistent. Maybe it could be
rewritten as

	Every alarm initializes the alarm time to 0, and the alarm state
	to disabled.

Still, it seems better to me to not make the alarm a subject which
manages itself, but rather let the alarm (implicitly) be an entity which
is managed by the device. But maybe the epoch does not need to be
mentioned. What about this?

	Initially, the alarm time is 0, and the alarm is disabled.

Thanks for the comments,

Peter

Re: [PATCH v8 4/4] virtio-rtc: Add normative statements for alarm feature

[Peter Hilber]

On Wed, Apr 16, 2025 at 02:14:36PM +0200, Matias Ezequiel Vara Larsen wrote:
> On Thu, Mar 06, 2025 at 10:51:12AM +0100, Peter Hilber wrote:
> > Add the normative statements for the alarm feature added previously.
> > 
> > Signed-off-by: Peter Hilber <quic_philber@quicinc.com>
> > ---
> > 
> > Notes:
> >     v8:
> >     
> >     - Explicitly describe alarm enabled status, where relevant (Matias
> >       Ezequiel Vara Larsen).
> >     
> >     - Simplify requirement about clock readings after alarm (Matias Ezequiel
> >       Vara Larsen).
> >     
> >     - Move requirements to serve alarm expiration events before requirements
> >       about stopping to serve (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".
> >     
> >     v7:
> >     
> >     - Remove inadvertent v6 changes, which should have been part of
> >       preceding patches.
> >     
> >     v4:
> >     
> >     - Update normative statements to match v4 changes to non-normative
> >       statements (patch 3).
> >     
> >     - Driver should read clock to confirm that alarm has expired.
> >     
> >     - Formatting and wording improvements.
> > 
> >  device-types/rtc/description.tex        | 150 ++++++++++++++++++++++++
> >  device-types/rtc/device-conformance.tex |   4 +
> >  device-types/rtc/driver-conformance.tex |   2 +
> >  3 files changed, 156 insertions(+)
> > 
> > diff --git a/device-types/rtc/description.tex b/device-types/rtc/description.tex
> > index 93bcf178b042..91afae7c2110 100644
> > --- a/device-types/rtc/description.tex
> > +++ b/device-types/rtc/description.tex
> > @@ -32,6 +32,11 @@ \subsection{Feature bits}\label{sec:Device Types / RTC Device / Feature bits}
> >  VIRTIO_RTC_F_ALARM determines whether the device supports setting an
> >  alarm for some of the clocks.
> >  
> > +\devicenormative{\subsubsection}{Feature bits}{Device Types / RTC Device / Feature bits}
> > +
> > +The device SHOULD offer VIRTIO_RTC_F_ALARM if the device can support
> > +setting an alarm for any of its clocks.
> > +
> 
> I think you can remove `can` here.

I think there was already a discussion about this for v7. My argument
was that "supports setting an alarm" is only the case if the feature is
actually negotiated, and that this interpretation is consistent with the
wording in the rest of the device specification. What do you think?

> 
> >  \subsection{Device configuration layout}\label{sec:Device Types / RTC Device / Device configuration layout}
> >  
> >  There is no configuration data for the device.
> > @@ -712,6 +717,11 @@ \subsubsection{Read Requests}\label{sec:Device Types / RTC Device / Device Opera
> >  specification, the device MUST use the nanosecond as unit for the
> >  \field{clock_reading} field.
> >  
> > +If the device sent an alarm notification for clock C with alarm time A,
> > +the device MUST, for all read requests of C which the driver marks as
> > +available after the notification, return a \field{clock_reading} which
> > +does not precede A (except if C stepped backwards to before A).
> > +
> >  \subsubsection{Alarm Operation}\label{sec:Device Types / RTC Device / Device Operation / Alarm Operation}
> >  
> >  Through the optional alarm feature, the driver can set an alarm time. On
> > @@ -819,6 +829,76 @@ \subsubsection{Alarm Operation}\label{sec:Device Types / RTC Device / Device Ope
> >  To prevent the above issues, the driver also marks buffers in the alarmq
> >  as available only after completing the above steps for all clocks.
> >  
> > +\devicenormative{\paragraph}{Alarm Operation}{Device Types / RTC Device / Device Operation / Alarm Operation}
> > +
> > +The device MAY retain both alarm time and alarm enabled status of a
> > +clock across a device reset.
> > +
> > +If the device did not retain alarm time and alarm enabled status of a
> > +clock across a device reset, the device MUST initialize alarm time to 0.
> > +
> > +If the device did not retain alarm time and alarm enabled status of a
> > +clock across a device reset, the device MUST disable the alarm.
> > +
> > +If VIRTIO_RTC_F_ALARM was negotiated, the device MUST support the alarm
> > +messages, VIRTIO_RTC_REQ_READ_ALARM, VIRTIO_RTC_REQ_SET_ALARM,
> > +VIRTIO_RTC_REQ_SET_ALARM_ENABLED, and VIRTIO_RTC_NOTIF_ALARM, for one or
> > +more clocks.
> > +
> > +If VIRTIO_RTC_F_ALARM was not negotiated, the device MUST NOT support the
> > +alarm messages.
> 
> `has been negotiated ...` I think there are others below.

Do you propose s/was not negotiated/has not been negotiated/? Or also to
avoid negations?

Thanks for the comments,

Peter

> 
> > +
> > +The device MUST set the VIRTIO_RTC_FLAG_ALARM_CAP flag in \field{struct
> > +virtio_rtc_resp_clock_cap.flags} if the respective clock supports alarm
> > +messages, and clear the flag otherwise.
> > +
> > +The device MUST consider it an alarm expiration event when the
> > +associated clock progresses (also: steps) from a time prior to the alarm
> > +time to the alarm time, or to a time after the alarm time, while the
> > +alarm is enabled.
> > +
> > +The device MUST consider it an alarm expiration event when the
> > +driver sets an alarm time which the associated clock has already reached
> > +or passed, while also setting the alarm to enabled.
> > +
> > +The device MUST consider it an alarm expiration event when the driver
> > +sets the alarm to enabled, if the clock has already reached or passed
> > +the alarm time.
> > +
> > +If the device retained alarm time and alarm enabled status of a clock
> > +across a device reset, and the clock has already reached or passed the
> > +alarm time, the device MUST consider this device reset an alarm
> > +expiration event, if the alarm is enabled.
> > +
> > +If an alarm expiration event E happens, the device MUST start serving
> > +the alarm expiration event E.
> > +
> > +If the device is currently serving an alarm expiration event E, the
> > +device MUST send a single VIRTIO_RTC_NOTIF_ALARM notification for E, as
> > +soon as an alarmq buffer is available for this purpose.
> > +
> > +While the device is serving an alarm expiration event, the device MAY
> > +execute implementation-specific alarm actions.
> > +
> > +The device MAY ignore the device status when executing
> > +implementation-specific alarm actions.
> > +
> > +The device MAY ignore whether VIRTIO_RTC_F_ALARM was negotiated when
> > +executing implementation-specific alarm actions.
> > +
> > +If the driver successfully requests VIRTIO_RTC_REQ_SET_ALARM, or
> > +VIRTIO_RTC_REQ_SET_ALARM_ENABLED, for clock C, the device MUST stop
> > +serving any previous alarm expiration event for C before the device
> > +marks the message as used.
> > +
> > +If a clock C steps to a time previous to C's alarm time, the device MUST
> > +stop serving any previous alarm expiration event for C, within a grace
> > +period.
> > +
> > +If an alarm expiration event happens for clock C, the device MUST stop
> > +serving any previous alarm expiration event for C, within a grace
> > +period.
> > +
> >  \paragraph{Alarm Control Requests}
> >  
> >  If VIRTIO_RTC_F_ALARM is negotiated,
> > @@ -913,6 +993,59 @@ \subsubsection{Alarm Operation}\label{sec:Device Types / RTC Device / Device Ope
> >  
> >  \end{description}
> >  
> > +\drivernormative{\subparagraph}{Alarm Control Requests}{Device Types / RTC Device / Device Operation / Alarm Operation / Alarm Control Requests}
> > +
> > +For VIRTIO_RTC_REQ_SET_ALARM and for any clock type listed in this
> > +specification, the driver MUST use the nanosecond as unit for the
> > +\field{alarm_time} field.
> > +
> > +\devicenormative{\subparagraph}{Alarm Control Requests}{Device Types / RTC Device / Device Operation / Alarm Operation / Alarm Control Requests}
> > +
> > +If VIRTIO_RTC_F_ALARM was not negotiated, the device MUST set status
> > +VIRTIO_RTC_S_ENODEV for VIRTIO_RTC_REQ_READ_ALARM,
> > +VIRTIO_RTC_REQ_SET_ALARM, and VIRTIO_RTC_REQ_SET_ALARM_ENABLED.
> > +
> > +If the clock does not support alarm messages, the device MUST set status
> > +VIRTIO_RTC_S_ENODEV for VIRTIO_RTC_REQ_READ_ALARM,
> > +VIRTIO_RTC_REQ_SET_ALARM, and VIRTIO_RTC_REQ_SET_ALARM_ENABLED.
> > +
> > +For VIRTIO_RTC_REQ_READ_ALARM, the device MUST set the
> > +\field{alarm_time} field to the alarm time.
> > +
> > +For VIRTIO_RTC_REQ_READ_ALARM, the device MUST set the
> > +VIRTIO_RTC_FLAG_ALARM_ENABLED flag in the \field{flags} field if the
> > +alarm is enabled, and clear the flag otherwise.
> > +
> > +For VIRTIO_RTC_REQ_READ_ALARM and for any clock type listed in this
> > +specification, the device MUST use the nanosecond as unit for the
> > +\field{alarm_time} field.
> > +
> > +For VIRTIO_RTC_REQ_SET_ALARM, the device MUST accept any
> > +\field{alarm_time} value.
> > +
> > +If the device sets status VIRTIO_RTC_S_OK for VIRTIO_RTC_REQ_SET_ALARM,
> > +the device MUST set the alarm time to the time represented by the
> > +\field{alarm_time} field.
> > +
> > +If the device sets status VIRTIO_RTC_S_OK for VIRTIO_RTC_REQ_SET_ALARM,
> > +the device MUST enable the alarm if VIRTIO_RTC_FLAG_ALARM_ENABLED is set
> > +in the \field{flags} field.
> > +
> > +If the device sets status VIRTIO_RTC_S_OK for VIRTIO_RTC_REQ_SET_ALARM,
> > +the device MUST disable the alarm if VIRTIO_RTC_FLAG_ALARM_ENABLED is
> > +cleared in the \field{flags} field.
> > +
> > +If the device sets status VIRTIO_RTC_S_OK for
> > +VIRTIO_RTC_REQ_SET_ALARM_ENABLED, the device MUST enable the alarm if
> > +VIRTIO_RTC_FLAG_ALARM_ENABLED is set in the \field{flags} field.
> > +
> > +If the device sets status VIRTIO_RTC_S_OK for
> > +VIRTIO_RTC_REQ_SET_ALARM_ENABLED, the device MUST disable the alarm if
> > +VIRTIO_RTC_FLAG_ALARM_ENABLED is cleared in the \field{flags} field.
> > +
> > +If the device sets status VIRTIO_RTC_S_OK for
> > +VIRTIO_RTC_REQ_SET_ALARM_ENABLED, the device MUST retain the alarm time.
> > +
> >  \paragraph{Alarm Notifications}
> >  
> >  If the alarmq is present, the driver should make buffers available in
> > @@ -948,3 +1081,20 @@ \subsubsection{Alarm Operation}\label{sec:Device Types / RTC Device / Device Ope
> >  
> >  \field{clock_id} identifies the expired alarm through its associated
> >  clock.
> > +
> > +\drivernormative{\subparagraph}{Alarm Notifications}{Device Types / RTC Device / Device Operation / Alarm Operation / Alarm Notifications}
> > +
> > +If VIRTIO_RTC_F_ALARM was negotiated, the driver SHOULD populate the
> > +alarmq with buffers.
> > +
> > +The driver MUST allocate enough space for any alarmq message in the
> > +device-writable part of an alarmq buffer.
> > +
> > +If the driver receives a VIRTIO_RTC_NOTIF_ALARM notification, the driver
> > +SHOULD read the associated clock instead of assuming that the alarm time
> > +which the driver set last has been reached.
> > +
> > +\devicenormative{\subparagraph}{Alarm Notifications}{Device Types / RTC Device / Device Operation / Alarm Operation / Alarm Notifications}
> > +
> > +The device MUST NOT send a VIRTIO_RTC_NOTIF_ALARM notification for a
> > +clock which does not support alarm messages.
> > diff --git a/device-types/rtc/device-conformance.tex b/device-types/rtc/device-conformance.tex
> > index 4303cd450542..705691a7319f 100644
> > --- a/device-types/rtc/device-conformance.tex
> > +++ b/device-types/rtc/device-conformance.tex
> > @@ -3,7 +3,11 @@
> >  An RTC device MUST conform to the following normative statements:
> >  
> >  \begin{itemize}
> > +\item \ref{devicenormative:Device Types / RTC Device / Feature bits}
> >  \item \ref{devicenormative:Device Types / RTC Device / Device Operation}
> >  \item \ref{devicenormative:Device Types / RTC Device / Device Operation / Control Requests}
> >  \item \ref{devicenormative:Device Types / RTC Device / Device Operation / Read Requests}
> > +\item \ref{devicenormative:Device Types / RTC Device / Device Operation / Alarm Operation}
> > +\item \ref{devicenormative:Device Types / RTC Device / Device Operation / Alarm Operation / Alarm Control Requests}
> > +\item \ref{devicenormative:Device Types / RTC Device / Device Operation / Alarm Operation / Alarm Notifications}
> >  \end{itemize}
> > diff --git a/device-types/rtc/driver-conformance.tex b/device-types/rtc/driver-conformance.tex
> > index 689c18d158d0..a87c4cde99c2 100644
> > --- a/device-types/rtc/driver-conformance.tex
> > +++ b/device-types/rtc/driver-conformance.tex
> > @@ -6,4 +6,6 @@
> >  \item \ref{drivernormative:Device Types / RTC Device / Device Operation}
> >  \item \ref{drivernormative:Device Types / RTC Device / Device Operation / Control Requests}
> >  \item \ref{drivernormative:Device Types / RTC Device / Device Operation / Read Requests}
> > +\item \ref{drivernormative:Device Types / RTC Device / Device Operation / Alarm Operation / Alarm Control Requests}
> > +\item \ref{drivernormative:Device Types / RTC Device / Device Operation / Alarm Operation / Alarm Notifications}
> >  \end{itemize}
> > -- 
> > 2.43.0
> > 
> 

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

[Peter Hilber]

On Wed, Apr 16, 2025 at 11:43:25AM -0400, Michael S. Tsirkin wrote:
> 
> 
> Good work. I sent some comments but they are pretty minor. Thanks!
> 
> 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.
> 
> A bit more text on the motivation, when to do you intend to use this
> device, would be good.

I will add this.

Thanks for the comments!

Peter

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

[Peter Hilber]

On Wed, Apr 16, 2025 at 11:33:44AM -0400, Michael S. Tsirkin wrote:
> On Thu, Mar 06, 2025 at 10:51:09AM +0100, Peter Hilber wrote:
> > The virtio-rtc device provides information about current time through
> > one or more clocks. As such, it is a Real-Time Clock (RTC) device.
> > 
> > The normative statements for this device follow in the next patch.
> > 
> > For this device, there is an RFC Linux kernel driver which is being
> > upstreamed, and a proprietary device implementation.
> > 
> > Miscellaneous
> > -------------
> > 
> > The spec does not specify how a driver should interpret clock readings,
> > esp. also not how to perform clock synchronization.
> > 
> > The device uses the "Timer/Clock" device id which is already part of the
> > specification. This device id was registered a long time ago and should
> > be unused according to the author's information. The name "RTC" was
> > determined to be the best for a device which focuses on current time.
> > 
> > Signed-off-by: Peter Hilber <quic_philber@quicinc.com>
> > ---
> > 
> > Notes:
> >     v8:
> >     
> >     - Change word order from "field X" to "the X field" (Matias Ezequiel
> >       Vara Larsen).
> >     
> >     - Split up sentences about implementation-specific definitions (Matias
> >       Ezequiel Vara Larsen).
> >     
> >     v7:
> >     
> >     - Remove leap second and performance indications from struct
> >       virtio_rtc_resp_read_cross. Remove backing definitions.
> >     
> >     - Add wording change which was previously mistakenly placed in last
> >       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 [8].
> >     
> >     - Add dedicated clock types for UTC leap second smearing (David
> >       Woodhouse).
> >     
> >     - Extend leap second indications.
> >     
> >     - Split UTC-TAI offset and fractional offset due to smearing (David
> >       Woodhouse).
> >     
> >     - Remove requirement that TAI offset must not be a whole second while
> >       clock is being smeared.
> >     
> >     - Align bit widths, and some names, with '[RFC PATCH v4] ptp: Add
> >       vDSO-style vmclock support' [8].
> >     
> >     - 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.
> >     
> >     v4:
> >     
> >     - Drop distinction of Arm Generic Timer virtual and physical counter [7].
> >     
> >     - Add requirement that device should assume that driver reads clock from
> >       first vCPU (David Woodhouse) [6].
> >     
> >     - Formatting and wording improvements.
> >     
> >     v3:
> >     
> >     - Address comments from Parav Pandit.
> >     
> >     - Split off normative requirements into a second commit [2].
> >     
> >     - Merge readq and controlq into requestq [3].
> >     
> >     - Don't guard cross-timestamping with feature bit [3].
> >     
> >     - Pad request headers to 64 bit [2].
> >     
> >     - Rename Virtio status codes to match UNIX error names [2].
> >     
> >     - Avoid Virtio status code clashes with net controlq ack values.
> >     
> >     - Reword to refer more to "requests", rather than "messages" [2].
> >     
> >     - Rephrase some sentences [2].
> >     
> >     - Use integer data types without "__" prefixes [2].
> >     
> >     - Reduce clock id width to 16 bits [5].
> >     
> >     - Make VIRTIO_RTC_FLAG_CROSS_CAP a bit mask rather than a bit index.
> >     
> >     v2:
> >     
> >     - Address comments from Cornelia Huck.
> >     
> >     - Add VIRTIO_RTC_M_CROSS_CAP message [1].
> >     
> >     - Fix various minor issues and improve wording [1].
> >     
> >     - Add several clarifications regarding device error statuses.
> >     
> >     [1] https://lists.oasis-open.org/archives/virtio-comment/202304/msg00523.html
> >     [2] https://lore.kernel.org/virtio-comment/b59a7dda-06fe-cff9-df61-b90aa4e50836@opensynergy.com/t/#mffb93800fea11d6dda9e151078abedd6ff1c0f1e
> >     [3] https://lore.kernel.org/virtio-comment/b59a7dda-06fe-cff9-df61-b90aa4e50836@opensynergy.com/t/#m94efd0aa9b9c2b96a246b79ef8bfc3bf64ebe791
> >     [4] https://lore.kernel.org/lkml/20230630171052.985577-1-peter.hilber@opensynergy.com/T/#m65fa1d715933360498c4e33d7225e4220215a9d6
> >     [5] https://lore.kernel.org/virtio-comment/b59a7dda-06fe-cff9-df61-b90aa4e50836@opensynergy.com/t/#mf00ce330228c28556d735eb9597469048c5d8b62
> >     [6] https://lore.kernel.org/lkml/d796d9a5-8eda-4528-a6d8-1c4eba24aa1e@opensynergy.com/
> >     [7] https://lore.kernel.org/all/20231218064253.9734-2-peter.hilber@opensynergy.com/
> >     [8] https://lore.kernel.org/lkml/20240708092924.1473461-1-dwmw2@infradead.org/
> > 
> >  content.tex                      |   3 +-
> >  device-types/rtc/description.tex | 428 +++++++++++++++++++++++++++++++
> >  introduction.tex                 |   6 +
> >  3 files changed, 436 insertions(+), 1 deletion(-)
> >  create mode 100644 device-types/rtc/description.tex
> > 
> > diff --git a/content.tex b/content.tex
> > index 67b1bf3c35ab..b1d93a8aebb4 100644
> > --- a/content.tex
> > +++ b/content.tex
> > @@ -684,7 +684,7 @@ \chapter{Device Types}\label{sec:Device Types}
> >  \hline
> >  16         &   GPU device       \\
> >  \hline
> > -17         &   Timer/Clock device \\
> > +17         &   RTC (Timer/Clock) device \\
> 
> 
> Do you want to change it to Real Time Clock here then?

OK.

> 
> >  \hline
> >  18         &   Input device \\
> >  \hline
> > @@ -776,6 +776,7 @@ \chapter{Device Types}\label{sec:Device Types}
> >  \input{device-types/pmem/description.tex}
> >  \input{device-types/can/description.tex}
> >  \input{device-types/spi/description.tex}
> > +\input{device-types/rtc/description.tex}
> >  
> >  \chapter{Reserved Feature Bits}\label{sec:Reserved Feature Bits}
> >  
> > diff --git a/device-types/rtc/description.tex b/device-types/rtc/description.tex
> > new file mode 100644
> > index 000000000000..5d8cf91a6991
> > --- /dev/null
> > +++ b/device-types/rtc/description.tex
> > @@ -0,0 +1,428 @@
> > +\section{RTC Device}\label{sec:Device Types / RTC Device}
> > +
> > +The RTC (Real Time Clock) device provides information about current
> > +time. The device can provide different clocks, e.g.\ for the UTC or TAI
> > +time standards, or for physical time elapsed since some past epoch. The
> > +driver can read the clocks with simple or more accurate methods.
> > +
> > +\subsection{Device ID}\label{sec:Device Types / RTC Device / Device ID}
> > +
> > +17
> > +
> > +\subsection{Virtqueues}\label{sec:Device Types / RTC Device / Virtqueues}
> > +
> > +\begin{description}
> > +\item[0] requestq
> > +\end{description}
> > +
> > +The driver enqueues requests to the requestq.
> > +
> > +\subsection{Feature bits}\label{sec:Device Types / RTC Device / Feature bits}
> > +
> > +No device-specific feature bits are defined yet.
> 
> Just say:
> 
> None
> 
> like SPI
> 
> or
> 
> None currently defined.
> 
> like entropy.

OK.

> 
> 
> 
> > +\subsection{Device configuration layout}\label{sec:Device Types / RTC Device / Device configuration layout}
> > +
> > +There is no configuration data for the device.
> 
> None currently defined.
> 
> configuration data is not a thing

OK.

> 
> 
> > +\subsection{Device Initialization}\label{sec:Device Types / RTC Device / Device Initialization}
> > +
> > +The device determines the set of clocks. The device can provide zero or
> > +more clocks.
> > +
> > +\subsection{Device Operation}\label{sec:Device Types / RTC Device / Device Operation}
> > +
> > +For the requestq, the driver sends a message with a request, and
> > +receives the response in the device-writable part of the message.
> 
> 
> Hmm. This confuses two things.
> 
> The device-writable part is in the buffer.
> Message type is the request type.

How about this?

	For the requestq, the driver sends a message with a request. The
	device fills in the message response and returns the message.

> 
> 
> > The
> > +requestq uses common request and response headers.
> > +
> > +\begin{lstlisting}
> > +/* common request header */
> > +struct virtio_rtc_req_head {
> > +        le16 msg_type;
> > +        u8 reserved[6];
> > +};
> > +
> > +/* common response header */
> > +struct virtio_rtc_resp_head {
> > +        u8 status;
> > +        u8 reserved[7];
> > +};
> > +\end{lstlisting}
> > +
> > +The \field{msg_type} field identifies the message type.
> > +
> > +The \field{status} field indicates whether the device successfully
> > +executed the request. The device sets the \field{status} field to one of
> > +the following values:
> > +
> > +\begin{lstlisting}
> > +#define VIRTIO_RTC_S_OK         0
> > +#define VIRTIO_RTC_S_EOPNOTSUPP 2
> > +#define VIRTIO_RTC_S_ENODEV     3
> > +#define VIRTIO_RTC_S_EINVAL     4
> > +#define VIRTIO_RTC_S_EIO        5
> > +\end{lstlisting}
> > +
> > +VIRTIO_RTC_S_OK indicates that the device successfully executed the
> > +request.
> > +
> > +If \field{status} is not VIRTIO_RTC_S_OK, the value of other response
> > +fields is undefined.
> > +
> > +VIRTIO_RTC_S_EOPNOTSUPP indicates that the device could not execute the
> > +specific request due to an implementation limitation. The device also
> > +returns status VIRTIO_RTC_S_EOPNOTSUPP for requests with unknown values
> > +in the fields \field{msg_type} or \field{hw_counter}.
> > +
> > +VIRTIO_RTC_S_ENODEV indicates that the \field{clock_id} field value
> > +supplied with the request does not identify a clock.
> > +
> > +VIRTIO_RTC_S_EINVAL indicates that
> 
> either? or both?

Can be either or both (inclusive "or"). I will state this more explicitly.

> 
> > +
> > +\begin{itemize}
> > +\item the driver request values are not allowed by the specification or
> 
> how do you mean? not recognized by the device? what do you expect
> driver to do? assert basically? no well behaved driver will
> encounter it right?

This would indicate a bug in the driver or device. A well-behaved driver
should not get any error from the device, ever.

For a Linux kernel driver, I am not sure if the driver should stop using
the device immediately, though.

> 
> 
> 
> 
> > +\item the device read-only part of the message, or the device write-only
> > +        part of the message, is too small to fit the actual message.
> 
> what is the actual message? do you mean the read-only part is too
> small to fit the request or the write-only part is too small to
> fit the response?

Yes. I will rephrase this.

> 
> 
> > +\end{itemize}
> > +
> > +VIRTIO_RTC_S_EIO indicates that the device did not execute the request
> > +due to an error which was not caused by invalid input from the driver.
> > +
> > +All \field{reserved} fields are written as zero, and their value is
> > +ignored.
> > +
> > +The set of clocks does not change after feature negotiation completion,
> > +until device reset. The set of clocks should not change on device reset
> > +either (similar to negotiated features). Clock identifiers are
> > +zero-based, dense indices. All fields
> 
> in which structure? within request structures?

Within request structures, and within the notification structure added
in patch 3. I will mention this.

> 
> > named \field{clock_id} contain
> > +clock identifiers.
> > +
> > +\subsubsection{Common Definitions}\label{sec:Device Types / RTC Device / Device Operation / Common Definitions}
> > +
> > +This section makes common definitions.
> > +
> > +\paragraph{Clock Types}\label{sec:Device Types / RTC Device / Device Operation / Common Definitions / Clock Types}
> > +
> > +The following clock types are defined:
> > +
> > +\begin{lstlisting}
> > +#define VIRTIO_RTC_CLOCK_UTC                    0
> > +#define VIRTIO_RTC_CLOCK_TAI                    1
> > +#define VIRTIO_RTC_CLOCK_MONOTONIC              2
> > +#define VIRTIO_RTC_CLOCK_UTC_SMEARED            3
> > +#define VIRTIO_RTC_CLOCK_UTC_MAYBE_SMEARED      4
> > +\end{lstlisting}
> > +
> > +\begin{description}
> > +
> > +\item[VIRTIO_RTC_CLOCK_UTC] uses the UTC (Coordinated Universal Time)
> > +        time standard. This clock uses the time epoch of January 1,
> > +        1970, 00:00 UTC. This is the same epoch as \emph{Unix time}. The
> > +        clock's seconds since the epoch are related to UTC time as
> > +        defined by \hyperref[intro:EPOCH]{EPOCH}.
> > +
> > +        This clock observes positive and negative leap seconds as
> > +        announced by standard bodies. At the start of leap seconds, the
> > +        clock steps accordingly.
> > +
> > +\item[VIRTIO_RTC_CLOCK_TAI] uses the TAI (International Atomic Time)
> > +        time standard. This clock uses the time epoch of January 1,
> > +        1970, 00:00 TAI.
> > +
> > +\item[VIRTIO_RTC_CLOCK_MONOTONIC] uses monotonic physical time (SI
> > +        seconds subdivisions) since some unspecified epoch. The epoch is
> > +        before or during device reset.
> > +
> > +\item[VIRTIO_RTC_CLOCK_UTC_SMEARED] deviates from the UTC standard by
> > +        smearing time in the vicinity of a leap second. This avoids
> > +        clock steps due to UTC leap seconds. Otherwise, this clock is
> > +        similar to VIRTIO_RTC_CLOCK_UTC.
> > +
> > +\item[VIRTIO_RTC_CLOCK_UTC_MAYBE_SMEARED] This clock
> > +
> > +\begin{itemize}
> > +\item may deviate from the UTC standard by smearing time in the vicinity
> > +        of a leap second (similar to VIRTIO_RTC_CLOCK_UTC_SMEARED), or
> > +
> > +\item may step at the start of leap seconds like VIRTIO_RTC_CLOCK_UTC.
> > +\end{itemize}
> > +
> > +A clock of type VIRTIO_RTC_CLOCK_UTC_MAYBE_SMEARED can change this
> > +behavior for every leap second.
> > +
> > +\end{description}
> > +
> > +In the following, \emph{UTC-like clock} designates any clock of type
> > +VIRTIO_RTC_CLOCK_UTC, VIRTIO_RTC_CLOCK_UTC_SMEARED, or
> > +VIRTIO_RTC_CLOCK_UTC_MAYBE_SMEARED.
> > +
> > +Additional clock types may be standardized in the future.
> > +Implementation-specific definitions of clock types are not recommended.
> > +Implementation-specific definitions use ids between 0xF0 and 0xFF.
> > +
> > +\paragraph{Smearing Variants}\label{sec:Device Types / RTC Device / Device Operation / Common Definitions / Smearing Variants}
> > +
> > +Leap second \emph{smearing variants} describe the deviation from the UTC
> > +standard in the vicinity of a leap second. The following smearing
> > +variants are currently defined:
> > +
> > +\begin{lstlisting}
> > +#define VIRTIO_RTC_SMEAR_UNSPECIFIED    0
> > +#define VIRTIO_RTC_SMEAR_NOON_LINEAR    1
> > +#define VIRTIO_RTC_SMEAR_UTC_SLS        2
> > +\end{lstlisting}
> > +
> > +\begin{description}
> > +
> > +        \item[VIRTIO_RTC_SMEAR_UNSPECIFIED] means that it is unspecified
> > +                how time is smeared in the vicinity of leap seconds.
> > +
> > +        \item[VIRTIO_RTC_SMEAR_NOON_LINEAR] specifies a linear smear
> > +                from noon prior to the leap second until noon after the
> > +                leap second.
> > +
> > +        \item[VIRTIO_RTC_SMEAR_UTC_SLS] specifies a linear smear as per
> > +                the \hyperref[intro:UTC-SLS]{UTC-SLS} proposal.
> > +
> > +\end{description}
> > +
> > +Clocks of type VIRTIO_RTC_CLOCK_UTC_SMEARED always behave according to a
> > +smearing variant. The smearing variant does not change over the clock's
> > +lifetime.
> > +
> > +For clocks of type VIRTIO_RTC_CLOCK_UTC_MAYBE_SMEARED, it is unspecified
> > +whether leap seconds are smeared, and how leap seconds are smeared.
> > +
> > +Additional smearing variants may be standardized in the future.
> > +Implementation-specific definitions of smearing variants are not
> > +recommended. Implementation-specific definitions use ids greater than or
> > +equal to 0xF0.
> > +
> > +In the following, \emph{leap smearing clock} designates
> 
> here, and elsewhere, it's confusing whether itemization is for either
> or both.

I will rephrase.

> 
> > +\begin{itemize}
> > +
> > +\item any clock of type VIRTIO_RTC_CLOCK_UTC_SMEARED
> > +
> > +\item any clock of type VIRTIO_RTC_CLOCK_UTC_MAYBE_SMEARED at any time
> > +        when the clock is smearing a leap second.
> > +
> > +\end{itemize}
> > +
> > +\paragraph{Hardware Counters}\label{sec:Device Types / RTC Device / Device Operation / Common Definitions / Hardware Counters}
> > +
> > +The following hardware counter identifiers are specified:
> > +
> > +\begin{lstlisting}
> > +/* Arm Generic Timer Counter-timer Virtual Count Register (CNTVCT_EL0) */
> > +#define VIRTIO_RTC_COUNTER_ARM_VCT      0
> > +/* x86 Time-Stamp Counter */
> > +#define VIRTIO_RTC_COUNTER_X86_TSC      1
> > +/* Invalid */
> > +#define VIRTIO_RTC_COUNTER_INVALID   0xFF
> > +\end{lstlisting}
> > +
> > +Additional hardware counter identifiers may be standardized in the
> > +future. Implementation-specific hardware counter identifiers are not
> > +recommended. Implementation-specific hardware counter identifiers have
> > +values between 0xF0 and 0xFE.
> 
> Maybe something like "and are reserved for experimental implementations".

OK.

> 
> 
> > +
> > +\subsubsection{Control Requests}\label{sec:Device Types / RTC Device / Device Operation / Control Requests}
> > +
> > +Through \emph{control requests}, the driver requests information about
> > +the device capabilities. The driver enqueues control requests in the
> > +requestq.
> > +
> > +\begin{description}
> > +
> > +\item[VIRTIO_RTC_REQ_CFG] discovers the number of clocks.
> > +
> > +\begin{lstlisting}
> > +#define VIRTIO_RTC_REQ_CFG 0x1000 /* message type */
> > +
> > +struct virtio_rtc_req_cfg {
> > +        struct virtio_rtc_req_head head;
> > +        /* no request params */
> > +};
> > +
> > +struct virtio_rtc_resp_cfg {
> > +        struct virtio_rtc_resp_head head;
> > +        le16 num_clocks;
> > +        u8 reserved[6];
> > +};
> > +\end{lstlisting}
> > +
> > +Field \field{num_clocks} contains the number of clocks. A device
> > +provides zero or more clocks. Valid clock ids are those smaller than
> > +\field{num_clocks}.
> > +
> > +\item[VIRTIO_RTC_REQ_CLOCK_CAP] discovers the capabilities of the clock
> > +identified by the \field{clock_id} field.
> > +
> > +\begin{lstlisting}
> > +#define VIRTIO_RTC_REQ_CLOCK_CAP 0x1001 /* message type */
> > +
> > +struct virtio_rtc_req_clock_cap {
> > +        struct virtio_rtc_req_head head;
> > +        le16 clock_id;
> > +        u8 reserved[6];
> > +};
> > +
> > +struct virtio_rtc_resp_clock_cap {
> > +        struct virtio_rtc_resp_head head;
> > +        u8 type;
> > +        u8 leap_second_smearing;
> > +        u8 reserved[6];
> > +};
> > +\end{lstlisting}
> > +
> > +The \field{type} field identifies the clock type. A device provides
> > +zero or more clocks for a clock type.
> > +
> > +Clocks of type VIRTIO_RTC_CLOCK_UTC_SMEARED indicate the \emph{smearing
> > +variant} through field \field{leap_second_smearing}. All other clocks
> > +set \field{leap_second_smearing} to VIRTIO_RTC_SMEAR_UNSPECIFIED.
> > +
> > +\item[VIRTIO_RTC_REQ_CROSS_CAP] discovers whether the device supports
> > +cross-timestamping for a particular pair of clock and hardware counter.
> > +
> > +\begin{lstlisting}
> > +#define VIRTIO_RTC_REQ_CROSS_CAP 0x1002 /* message type */
> > +
> > +struct virtio_rtc_req_cross_cap {
> > +        struct virtio_rtc_req_head head;
> > +        le16 clock_id;
> > +        u8 hw_counter;
> > +        u8 reserved[5];
> > +};
> > +
> > +
> > +struct virtio_rtc_resp_cross_cap {
> > +        struct virtio_rtc_resp_head head;
> > +#define VIRTIO_RTC_FLAG_CROSS_CAP       (1 << 0)
> > +        u8 flags;
> > +        u8 reserved[7];
> > +};
> > +\end{lstlisting}
> > +
> > +The \field{clock_id} field identifies the clock, and the
> > +\field{hw_counter} field identifies the hardware counter, for which
> > +cross-timestamp support is probed. The device sets the
> > +VIRTIO_RTC_FLAG_CROSS_CAP flag in the \field{flags} field if the clock
> > +supports cross-timestamping for the particular clock and hardware
> > +counter, and clears the flag otherwise.
> > +
> > +\end{description}
> > +
> > +\subsubsection{Read Requests}\label{sec:Device Types / RTC Device / Device Operation / Read Requests}
> > +
> > +Through \emph{read requests}, the driver requests clock readings from
> > +the device. The driver enqueues read requests in the requestq. The
> > +device obtains device-side clock readings and forwards these clock
> > +readings to the driver. The driver may enhance and interpret the clock
> > +readings through methods which are beyond the scope of this
> > +specification.
> > +
> > +Once DRIVER_OK has been set, the device should support reading every
> > +clock, even when a clock may yet have to be aligned to reference time
> > +sources.
> > +
> > +In general,
> > +
> > +\begin{itemize}
> > +\item clocks may jump backwards or forward, and
> > +\item the clock frequency may change. Clocks may be \emph{slewed},
> > +        i.e.\ clocks may run at a frequency other than their current
> > +        best frequency estimate.
> > +\end{itemize}
> > +
> > +As long as a clock does not jump backwards, the driver clock readings
> > +through read request responses increase monotonically:
> > +
> > +\begin{itemize}
> > +\item As long as a clock does not jump backwards in-between device-side
> > +        clock readings, the driver-side readings for that clock increase
> > +        monotonically as well, in the order in which the driver
> > +        marks read requests as available.
> > +
> > +\item The device marks read requests for the same clock as used in
> > +        the order in which the messages were marked as available.
> 
> buffers are available

s/messages were marked as available/buffers are available/ ?

> 
> > +\end{itemize}
> > +
> > +For a clock of type VIRTIO_RTC_CLOCK_MONOTONIC, the device always returns
> > +monotonically increasing clock readings through read request responses.
> > +
> > +The unit of all \field{clock_reading} fields is 1
> > +nanosecond.\footnote{For time epochs in year 1970 or later, this means
> > +that time until at least year 2553 can be represented in the \field{le64
> > +clock_reading} fields.}
> > +
> > +\begin{description}
> > +
> > +\item[VIRTIO_RTC_REQ_READ] reads the clock identified by the
> > +\field{clock_id} field. The device supports this message for every
> > +clock.
> > +
> > +\begin{lstlisting}
> > +#define VIRTIO_RTC_REQ_READ 0x0001 /* message type */
> > +
> > +struct virtio_rtc_req_read {
> > +        struct virtio_rtc_req_head head;
> > +        le16 clock_id;
> > +        u8 reserved[6];
> > +};
> > +
> > +struct virtio_rtc_resp_read {
> > +        struct virtio_rtc_resp_head head;
> > +        le64 clock_reading;
> > +};
> > +\end{lstlisting}
> > +
> > +\field{clock_reading} is a device-side clock reading obtained after the
> > +message was marked as available.
> > +
> > +\item[VIRTIO_RTC_REQ_READ_CROSS] returns a cross-timestamp for the clock
> > +identified by the \field{clock_id} field.\footnote{Cross-timestamping
> > +is similar to the ptp_kvm mechanism in the Linux kernel.} This message
> > +may yield better performance than using VIRTIO_RTC_REQ_READ.
> > +
> > +The driver can determine whether the device supports
> > +VIRTIO_RTC_REQ_READ_CROSS for a specific clock and \field{hw_counter}
> > +through VIRTIO_RTC_REQ_CROSS_CAP.
> > +
> > +\begin{lstlisting}
> > +#define VIRTIO_RTC_REQ_READ_CROSS 0x0002 /* message type */
> > +
> > +struct virtio_rtc_req_read_cross {
> > +        struct virtio_rtc_req_head head;
> > +        le16 clock_id;
> > +        u8 hw_counter;
> > +        u8 reserved[5];
> > +};
> > +
> > +struct virtio_rtc_resp_read_cross {
> > +        struct virtio_rtc_resp_head head;
> > +        le64 clock_reading;
> > +        le64 counter_cycles;
> > +};
> > +\end{lstlisting}
> > +
> > +The \field{hw_counter} field specifies the hardware counter for which
> > +the driver requests a cross-timestamp.
> > +
> > +Cross-timestamping returns a \field{clock_reading}, and an associated
> > +hardware counter value, \field{counter_cycles}. The
> > +\field{counter_cycles} field is the approximate or precise value which
> > +the driver would have read at the \field{clock_reading} time instant
> > +from the hardware counter identified by \field{hw_counter}. How the
> > +device determines the value which the driver would have seen is beyond
> > +the scope of this specification.
> 
> Not sure how it's beyond the scope. What exactly do you have
> in mind? The following paragraph hints at the fact you have
> some idea?

Determining the counter value seen by the driver requires the device to
determine any difference of the counter offsets or counter multipliers
applied for device and driver.

These settings may be set by a third entity such as a hypervisor and may
even change. I do not think that generally valid recommendations on how
to determine the value can be given.

Maybe I can add

	To determine the \field{counter_cycles} value, the device
	converts the hardware counter value the device has read,
	accounting for any differences in counter offsets or counter
	multipliers between device and driver at the time of the
	reading.

Thanks for the comments,

Peter

> 
> > In case hardware counter reads differ
> > +among CPUs used by the driver, the device should assume that the driver
> > +reads the hardware counter from the CPU which the driver enumerates as
> > +the first.
> > +
> > +The hardware counter identifiers are defined in
> > +\ref{sec:Device Types / RTC Device / Device Operation / Common Definitions / Hardware Counters}.
> > +
> > +\end{description}
> > diff --git a/introduction.tex b/introduction.tex
> > index e60298a4d78b..34f9485bc393 100644
> > --- a/introduction.tex
> > +++ b/introduction.tex
> > @@ -168,6 +168,12 @@ \section{Normative References}\label{sec:Normative References}
> >      Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP
> >      14, RFC 8174, DOI 10.17487/RFC8174, May 2017
> >          \newline\url{http://www.ietf.org/rfc/rfc8174.txt}\\
> > +	\phantomsection\label{intro:EPOCH}\textbf{[EPOCH]} &
> > +    POSIX.1-2024, Base Definitions, Seconds Since the Epoch
> > +	\newline\url{https://pubs.opengroup.org/onlinepubs/9799919799/basedefs/V1_chap04.html#tag_04_19}\\
> > +	\phantomsection\label{intro:UTC-SLS}\textbf{[UTC-SLS]} &
> > +    UTC with Smoothed Leap Seconds (UTC-SLS)
> > +	\newline\url{https://www.cl.cam.ac.uk/~mgk25/time/utc-sls/}\\
> >  \end{longtable}
> >  
> >  \section{Non-Normative References}
> > -- 
> > 2.43.0
> > 
> 

Re: [PATCH v8 2/4] virtio-rtc: Add initial normative statements

[Peter Hilber]

On Wed, Apr 16, 2025 at 11:42:01AM -0400, Michael S. Tsirkin wrote:
> On Thu, Mar 06, 2025 at 10:51:10AM +0100, Peter Hilber wrote:
> > Add the normative statements for the initial device specification.
> > 
> > Signed-off-by: Peter Hilber <quic_philber@quicinc.com>
> > ---
> > 
> > Notes:
> >     v8:
> >     
> >     - Drop requirement to ignore reserved fields in the device-readable part
> >       of the message (Matias Ezequiel Vara Larsen).
> >     
> >     - Drop requirement about returning same status in response to identical
> >       requests (Matias Ezequiel Vara Larsen).
> >     
> >     - Reword requirements about size mismatches for device
> >       read-only/write-only parts of the message (Matias Ezequiel Vara
> >       Larsen).
> >     
> >     - Change word order from "field X" to "the X field" (Matias Ezequiel
> >       Vara Larsen).
> >     
> >     v7:
> >     
> >     - Remove obsolete requirements for leap second indication.
> >     
> >     v6:
> >     
> >     - Update requirements to make leap second status information optional if
> >       if the clock smears (or might smear) leap seconds.
> >     
> >     - Allow indicating VIRTIO_RTC_SMEAR_UNSPECIFIED for
> >       VIRTIO_RTC_CLOCK_SMEARED.
> >     
> >     - Shorten some requirements by omitting redundant information.
> >     
> >     v5:
> >     
> >     - Update normative statements to match v5 changes to non-normative
> >       statements (patch 1).
> >     
> >     v4:
> >     
> >     - Require driver to set unused flags to zero.
> >     
> >     - Update normative statements to match v4 changes to non-normative
> >       statements (patch 1).
> >     
> >     - Improve formatting.
> > 
> >  conformance.tex                         |   2 +
> >  device-types/rtc/description.tex        | 272 +++++++++++++++++++++++-
> >  device-types/rtc/device-conformance.tex |   9 +
> >  device-types/rtc/driver-conformance.tex |   9 +
> >  4 files changed, 288 insertions(+), 4 deletions(-)
> >  create mode 100644 device-types/rtc/device-conformance.tex
> >  create mode 100644 device-types/rtc/driver-conformance.tex
> > 
> > diff --git a/conformance.tex b/conformance.tex
> > index d92a2369488e..4ce86a525e84 100644
> > --- a/conformance.tex
> > +++ b/conformance.tex
> > @@ -162,6 +162,7 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets}
> >  \input{device-types/pmem/driver-conformance.tex}
> >  \input{device-types/can/driver-conformance.tex}
> >  \input{device-types/spi/driver-conformance.tex}
> > +\input{device-types/rtc/driver-conformance.tex}
> >  
> >  \conformance{\section}{Device Conformance}\label{sec:Conformance / Device Conformance}
> >  
> > @@ -254,6 +255,7 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets}
> >  \input{device-types/pmem/device-conformance.tex}
> >  \input{device-types/can/device-conformance.tex}
> >  \input{device-types/spi/device-conformance.tex}
> > +\input{device-types/rtc/device-conformance.tex}
> >  
> >  \conformance{\section}{Legacy Interface: Transitional Device and Transitional Driver Conformance}\label{sec:Conformance / Legacy Interface: Transitional Device and Transitional Driver Conformance}
> >  A conformant implementation MUST be either transitional or
> > diff --git a/device-types/rtc/description.tex b/device-types/rtc/description.tex
> > index 5d8cf91a6991..f2a3907de511 100644
> > --- a/device-types/rtc/description.tex
> > +++ b/device-types/rtc/description.tex
> > @@ -73,7 +73,7 @@ \subsection{Device Operation}\label{sec:Device Types / RTC Device / Device Opera
> >  VIRTIO_RTC_S_EOPNOTSUPP indicates that the device could not execute the
> >  specific request due to an implementation limitation. The device also
> >  returns status VIRTIO_RTC_S_EOPNOTSUPP for requests with unknown values
> > -in the fields \field{msg_type} or \field{hw_counter}.
> > +in the \field{msg_type} or \field{hw_counter} fields.
> >  
> >  VIRTIO_RTC_S_ENODEV indicates that the \field{clock_id} field value
> >  supplied with the request does not identify a clock.
> > @@ -98,6 +98,106 @@ \subsection{Device Operation}\label{sec:Device Types / RTC Device / Device Opera
> >  zero-based, dense indices. All fields named \field{clock_id} contain
> >  clock identifiers.
> >  
> > +\drivernormative{\subsubsection}{Device Operation}{Device Types / RTC Device / Device Operation}
> > +
> > +If the \field{struct virtio_rtc_resp_head} field \field{status} is not
> > +VIRTIO_RTC_S_OK, the driver MUST NOT interpret response fields other
> > +than \field{status}.
> > +
> > +The driver MUST set \emph{reserved} fields in the device-readable part
> > +of the message to zero.
> > +
> > +The driver MUST set unnamed bits in \emph{flags} fields in the
> > +device-readable part of the message to zero.
> 
> 
> This is problematic, it should depend on features negotiated
> not on features listed in the spec as we will not
> remember to change this and break drivers.
> Just add in the description explanation which flags are legal for each request,
> then refer to that.

OK.

> 
> 
> > +
> > +The driver MUST NOT interpret \emph{reserved} fields in the
> > +device-writable part of the message.
> > +
> > +The driver MUST NOT interpret unnamed bits in \emph{flags} fields in the
> > +device-writable part of the message.
> 
> same though a bit less of a problem here.

I will change this in a similar way as above.

> 
> 
> > +
> > +The driver MUST put the request into the device-readable part of the
> > +message.
> > +
> > +The driver MUST allocate enough space for the response in the
> > +device-writable part of a requestq message.
> > +
> > +\devicenormative{\subsubsection}{Device Operation}{Device Types / RTC Device / Device Operation}
> > +
> > +For \field{struct virtio_rtc_resp_head}, the device MUST set the
> > +\field{status} field to VIRTIO_RTC_S_OK if the device successfully
> > +executed the request.
> > +
> > +For \field{struct virtio_rtc_resp_head}, the device MUST set the
> > +\field{status} field to a status other than VIRTIO_RTC_S_OK if the
> > +device did not successfully execute the request.
> > +
> > +For \field{struct virtio_rtc_resp_head}, the device MUST set the
> > +\field{status} field to VIRTIO_RTC_S_EOPNOTSUPP if the device could not
> > +execute the specific request due to an implementation limitation.
> > +
> > +For \field{struct virtio_rtc_resp_head}, the device MUST set the
> > +\field{status} field to VIRTIO_RTC_S_EOPNOTSUPP for a request with a
> > +value of the \field{msg_type} field which is not described in this
> > +specification.
> > +
> > +For \field{struct virtio_rtc_resp_head}, the device MUST set the
> > +\field{status} field to VIRTIO_RTC_S_EOPNOTSUPP for a request with a
> > +value of the \field{hw_counter} field which is neither described in this
> > +specification nor otherwise known to the implementation.
> > +
> > +For \field{struct virtio_rtc_resp_head}, the device MUST set the
> > +\field{status} field to VIRTIO_RTC_S_ENODEV if the \field{clock_id}
> > +field value supplied with the request does not identify a clock.
> > +
> > +For \field{struct virtio_rtc_resp_head}, the device MUST set the
> > +\field{status} field to VIRTIO_RTC_S_EINVAL if the request values are
> > +inconsistent with the specification and if the inconsistence is not
> > +described by the requirements which stipulate status
> > +VIRTIO_RTC_S_EOPNOTSUPP or VIRTIO_RTC_S_ENODEV.
> > +
> > +For \field{struct virtio_rtc_resp_head}, the device MUST set the
> > +\field{status} field to VIRTIO_RTC_S_EINVAL if the request specified in
> > +the request header through the \field{msg_type} field does not fit into
> > +the device read-only part of the actual message.
> > +
> > +For \field{struct virtio_rtc_resp_head}, the device MUST set the
> > +\field{status} field to VIRTIO_RTC_S_EINVAL if the response specified in
> > +the request header through the \field{msg_type} field does not fit into
> > +the device write-only part of the actual message, unless the
> > +\field{status} field does not fit into the device write-only part.
> > +
> > +For \field{struct virtio_rtc_resp_head}, the device MUST NOT set the
> > +\field{status} field if the \field{status} field does not fit into the
> > +device write-only part.
> > +
> > +For \field{struct virtio_rtc_resp_head}, the device MUST set the
> > +\field{status} field to VIRTIO_RTC_S_EIO if none of the previous
> > +requirements in this document stipulated another \field{status}.
> > +
> > +If the device read-only part of a message M is bigger than the size of
> > +the request specified for message M, the device MUST ignore the
> > +additional space.
> > +
> > +If the device write-only part of a message M is bigger than the size of
> > +the response specified for message M, the device MUST ignore the
> > +additional space.
> > +
> > +The device MUST set \emph{reserved} fields in the device-writable part
> > +of the message to zero.
> > +
> > +The device MUST set unnamed bits in \emph{flags} fields in the
> > +device-writable part of the message to zero.
> > +
> > +After feature negotiation completion the device MUST NOT change the set
> > +of clocks until device reset.
> > +
> > +The device SHOULD NOT change the set of clocks on a device reset after
> > +the first device reset.
> 
> really SHUOLD is more appropriate
> 
> and first in what sense? here is the text for features:
> 
> 
> 	If a device has successfully negotiated a set of features 
> 	at least once (by accepting the FEATURES_OK \field{device 
> 	status} bit during device initialization), then it SHOULD
> 	NOT fail re-negotiation of the same set of features after
> 	a device or system reset.  Failure to do so would interfere
> 	with resuming from suspend and error recovery.
> 
> do something similar and be specific pls.

OK.

Thanks for the comments,

Peter

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

[Michael S. Tsirkin]

On Thu, Apr 17, 2025 at 05:14:00PM +0200, Peter Hilber wrote:
> On Wed, Apr 16, 2025 at 11:33:44AM -0400, Michael S. Tsirkin wrote:
> > On Thu, Mar 06, 2025 at 10:51:09AM +0100, Peter Hilber wrote:
> > > The virtio-rtc device provides information about current time through
> > > one or more clocks. As such, it is a Real-Time Clock (RTC) device.
> > > 
> > > The normative statements for this device follow in the next patch.
> > > 
> > > For this device, there is an RFC Linux kernel driver which is being
> > > upstreamed, and a proprietary device implementation.
> > > 
> > > Miscellaneous
> > > -------------
> > > 
> > > The spec does not specify how a driver should interpret clock readings,
> > > esp. also not how to perform clock synchronization.
> > > 
> > > The device uses the "Timer/Clock" device id which is already part of the
> > > specification. This device id was registered a long time ago and should
> > > be unused according to the author's information. The name "RTC" was
> > > determined to be the best for a device which focuses on current time.
> > > 
> > > Signed-off-by: Peter Hilber <quic_philber@quicinc.com>
> > > ---
> > > 
> > > Notes:
> > >     v8:
> > >     
> > >     - Change word order from "field X" to "the X field" (Matias Ezequiel
> > >       Vara Larsen).
> > >     
> > >     - Split up sentences about implementation-specific definitions (Matias
> > >       Ezequiel Vara Larsen).
> > >     
> > >     v7:
> > >     
> > >     - Remove leap second and performance indications from struct
> > >       virtio_rtc_resp_read_cross. Remove backing definitions.
> > >     
> > >     - Add wording change which was previously mistakenly placed in last
> > >       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 [8].
> > >     
> > >     - Add dedicated clock types for UTC leap second smearing (David
> > >       Woodhouse).
> > >     
> > >     - Extend leap second indications.
> > >     
> > >     - Split UTC-TAI offset and fractional offset due to smearing (David
> > >       Woodhouse).
> > >     
> > >     - Remove requirement that TAI offset must not be a whole second while
> > >       clock is being smeared.
> > >     
> > >     - Align bit widths, and some names, with '[RFC PATCH v4] ptp: Add
> > >       vDSO-style vmclock support' [8].
> > >     
> > >     - 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.
> > >     
> > >     v4:
> > >     
> > >     - Drop distinction of Arm Generic Timer virtual and physical counter [7].
> > >     
> > >     - Add requirement that device should assume that driver reads clock from
> > >       first vCPU (David Woodhouse) [6].
> > >     
> > >     - Formatting and wording improvements.
> > >     
> > >     v3:
> > >     
> > >     - Address comments from Parav Pandit.
> > >     
> > >     - Split off normative requirements into a second commit [2].
> > >     
> > >     - Merge readq and controlq into requestq [3].
> > >     
> > >     - Don't guard cross-timestamping with feature bit [3].
> > >     
> > >     - Pad request headers to 64 bit [2].
> > >     
> > >     - Rename Virtio status codes to match UNIX error names [2].
> > >     
> > >     - Avoid Virtio status code clashes with net controlq ack values.
> > >     
> > >     - Reword to refer more to "requests", rather than "messages" [2].
> > >     
> > >     - Rephrase some sentences [2].
> > >     
> > >     - Use integer data types without "__" prefixes [2].
> > >     
> > >     - Reduce clock id width to 16 bits [5].
> > >     
> > >     - Make VIRTIO_RTC_FLAG_CROSS_CAP a bit mask rather than a bit index.
> > >     
> > >     v2:
> > >     
> > >     - Address comments from Cornelia Huck.
> > >     
> > >     - Add VIRTIO_RTC_M_CROSS_CAP message [1].
> > >     
> > >     - Fix various minor issues and improve wording [1].
> > >     
> > >     - Add several clarifications regarding device error statuses.
> > >     
> > >     [1] https://lists.oasis-open.org/archives/virtio-comment/202304/msg00523.html
> > >     [2] https://lore.kernel.org/virtio-comment/b59a7dda-06fe-cff9-df61-b90aa4e50836@opensynergy.com/t/#mffb93800fea11d6dda9e151078abedd6ff1c0f1e
> > >     [3] https://lore.kernel.org/virtio-comment/b59a7dda-06fe-cff9-df61-b90aa4e50836@opensynergy.com/t/#m94efd0aa9b9c2b96a246b79ef8bfc3bf64ebe791
> > >     [4] https://lore.kernel.org/lkml/20230630171052.985577-1-peter.hilber@opensynergy.com/T/#m65fa1d715933360498c4e33d7225e4220215a9d6
> > >     [5] https://lore.kernel.org/virtio-comment/b59a7dda-06fe-cff9-df61-b90aa4e50836@opensynergy.com/t/#mf00ce330228c28556d735eb9597469048c5d8b62
> > >     [6] https://lore.kernel.org/lkml/d796d9a5-8eda-4528-a6d8-1c4eba24aa1e@opensynergy.com/
> > >     [7] https://lore.kernel.org/all/20231218064253.9734-2-peter.hilber@opensynergy.com/
> > >     [8] https://lore.kernel.org/lkml/20240708092924.1473461-1-dwmw2@infradead.org/
> > > 
> > >  content.tex                      |   3 +-
> > >  device-types/rtc/description.tex | 428 +++++++++++++++++++++++++++++++
> > >  introduction.tex                 |   6 +
> > >  3 files changed, 436 insertions(+), 1 deletion(-)
> > >  create mode 100644 device-types/rtc/description.tex
> > > 
> > > diff --git a/content.tex b/content.tex
> > > index 67b1bf3c35ab..b1d93a8aebb4 100644
> > > --- a/content.tex
> > > +++ b/content.tex
> > > @@ -684,7 +684,7 @@ \chapter{Device Types}\label{sec:Device Types}
> > >  \hline
> > >  16         &   GPU device       \\
> > >  \hline
> > > -17         &   Timer/Clock device \\
> > > +17         &   RTC (Timer/Clock) device \\
> > 
> > 
> > Do you want to change it to Real Time Clock here then?
> 
> OK.
> 
> > 
> > >  \hline
> > >  18         &   Input device \\
> > >  \hline
> > > @@ -776,6 +776,7 @@ \chapter{Device Types}\label{sec:Device Types}
> > >  \input{device-types/pmem/description.tex}
> > >  \input{device-types/can/description.tex}
> > >  \input{device-types/spi/description.tex}
> > > +\input{device-types/rtc/description.tex}
> > >  
> > >  \chapter{Reserved Feature Bits}\label{sec:Reserved Feature Bits}
> > >  
> > > diff --git a/device-types/rtc/description.tex b/device-types/rtc/description.tex
> > > new file mode 100644
> > > index 000000000000..5d8cf91a6991
> > > --- /dev/null
> > > +++ b/device-types/rtc/description.tex
> > > @@ -0,0 +1,428 @@
> > > +\section{RTC Device}\label{sec:Device Types / RTC Device}
> > > +
> > > +The RTC (Real Time Clock) device provides information about current
> > > +time. The device can provide different clocks, e.g.\ for the UTC or TAI
> > > +time standards, or for physical time elapsed since some past epoch. The
> > > +driver can read the clocks with simple or more accurate methods.
> > > +
> > > +\subsection{Device ID}\label{sec:Device Types / RTC Device / Device ID}
> > > +
> > > +17
> > > +
> > > +\subsection{Virtqueues}\label{sec:Device Types / RTC Device / Virtqueues}
> > > +
> > > +\begin{description}
> > > +\item[0] requestq
> > > +\end{description}
> > > +
> > > +The driver enqueues requests to the requestq.
> > > +
> > > +\subsection{Feature bits}\label{sec:Device Types / RTC Device / Feature bits}
> > > +
> > > +No device-specific feature bits are defined yet.
> > 
> > Just say:
> > 
> > None
> > 
> > like SPI
> > 
> > or
> > 
> > None currently defined.
> > 
> > like entropy.
> 
> OK.
> 
> > 
> > 
> > 
> > > +\subsection{Device configuration layout}\label{sec:Device Types / RTC Device / Device configuration layout}
> > > +
> > > +There is no configuration data for the device.
> > 
> > None currently defined.
> > 
> > configuration data is not a thing
> 
> OK.
> 
> > 
> > 
> > > +\subsection{Device Initialization}\label{sec:Device Types / RTC Device / Device Initialization}
> > > +
> > > +The device determines the set of clocks. The device can provide zero or
> > > +more clocks.
> > > +
> > > +\subsection{Device Operation}\label{sec:Device Types / RTC Device / Device Operation}
> > > +
> > > +For the requestq, the driver sends a message with a request, and
> > > +receives the response in the device-writable part of the message.
> > 
> > 
> > Hmm. This confuses two things.
> > 
> > The device-writable part is in the buffer.
> > Message type is the request type.
> 
> How about this?
> 
> 	For the requestq, the driver sends a message with a request. The
> 	device fills in the message response and returns the message.


returns the message is not a thing.
really the consept of message is extraneous.
what you want it to mean is mostly a buffer.
we have terminology for that: make available, use.
Just use it do not come up with your own.

> 
> > 
> > 
> > > The
> > > +requestq uses common request and response headers.
> > > +
> > > +\begin{lstlisting}
> > > +/* common request header */
> > > +struct virtio_rtc_req_head {
> > > +        le16 msg_type;
> > > +        u8 reserved[6];
> > > +};
> > > +
> > > +/* common response header */
> > > +struct virtio_rtc_resp_head {
> > > +        u8 status;
> > > +        u8 reserved[7];
> > > +};
> > > +\end{lstlisting}
> > > +
> > > +The \field{msg_type} field identifies the message type.
> > > +
> > > +The \field{status} field indicates whether the device successfully
> > > +executed the request. The device sets the \field{status} field to one of
> > > +the following values:
> > > +
> > > +\begin{lstlisting}
> > > +#define VIRTIO_RTC_S_OK         0
> > > +#define VIRTIO_RTC_S_EOPNOTSUPP 2
> > > +#define VIRTIO_RTC_S_ENODEV     3
> > > +#define VIRTIO_RTC_S_EINVAL     4
> > > +#define VIRTIO_RTC_S_EIO        5
> > > +\end{lstlisting}
> > > +
> > > +VIRTIO_RTC_S_OK indicates that the device successfully executed the
> > > +request.
> > > +
> > > +If \field{status} is not VIRTIO_RTC_S_OK, the value of other response
> > > +fields is undefined.
> > > +
> > > +VIRTIO_RTC_S_EOPNOTSUPP indicates that the device could not execute the
> > > +specific request due to an implementation limitation. The device also
> > > +returns status VIRTIO_RTC_S_EOPNOTSUPP for requests with unknown values
> > > +in the fields \field{msg_type} or \field{hw_counter}.
> > > +
> > > +VIRTIO_RTC_S_ENODEV indicates that the \field{clock_id} field value
> > > +supplied with the request does not identify a clock.
> > > +
> > > +VIRTIO_RTC_S_EINVAL indicates that
> > 
> > either? or both?
> 
> Can be either or both (inclusive "or"). I will state this more explicitly.
> 
> > 
> > > +
> > > +\begin{itemize}
> > > +\item the driver request values are not allowed by the specification or
> > 
> > how do you mean? not recognized by the device? what do you expect
> > driver to do? assert basically? no well behaved driver will
> > encounter it right?
> 
> This would indicate a bug in the driver or device. A well-behaved driver
> should not get any error from the device, ever.

worth clarifying

> For a Linux kernel driver, I am not sure if the driver should stop using
> the device immediately, though.
> 
> > 
> > 
> > 
> > 
> > > +\item the device read-only part of the message, or the device write-only
> > > +        part of the message, is too small to fit the actual message.
> > 
> > what is the actual message? do you mean the read-only part is too
> > small to fit the request or the write-only part is too small to
> > fit the response?
> 
> Yes. I will rephrase this.
> 
> > 
> > 
> > > +\end{itemize}
> > > +
> > > +VIRTIO_RTC_S_EIO indicates that the device did not execute the request
> > > +due to an error which was not caused by invalid input from the driver.
> > > +
> > > +All \field{reserved} fields are written as zero, and their value is
> > > +ignored.
> > > +
> > > +The set of clocks does not change after feature negotiation completion,
> > > +until device reset. The set of clocks should not change on device reset
> > > +either (similar to negotiated features). Clock identifiers are
> > > +zero-based, dense indices. All fields
> > 
> > in which structure? within request structures?
> 
> Within request structures, and within the notification structure added
> in patch 3. I will mention this.
> 
> > 
> > > named \field{clock_id} contain
> > > +clock identifiers.
> > > +
> > > +\subsubsection{Common Definitions}\label{sec:Device Types / RTC Device / Device Operation / Common Definitions}
> > > +
> > > +This section makes common definitions.
> > > +
> > > +\paragraph{Clock Types}\label{sec:Device Types / RTC Device / Device Operation / Common Definitions / Clock Types}
> > > +
> > > +The following clock types are defined:
> > > +
> > > +\begin{lstlisting}
> > > +#define VIRTIO_RTC_CLOCK_UTC                    0
> > > +#define VIRTIO_RTC_CLOCK_TAI                    1
> > > +#define VIRTIO_RTC_CLOCK_MONOTONIC              2
> > > +#define VIRTIO_RTC_CLOCK_UTC_SMEARED            3
> > > +#define VIRTIO_RTC_CLOCK_UTC_MAYBE_SMEARED      4
> > > +\end{lstlisting}
> > > +
> > > +\begin{description}
> > > +
> > > +\item[VIRTIO_RTC_CLOCK_UTC] uses the UTC (Coordinated Universal Time)
> > > +        time standard. This clock uses the time epoch of January 1,
> > > +        1970, 00:00 UTC. This is the same epoch as \emph{Unix time}. The
> > > +        clock's seconds since the epoch are related to UTC time as
> > > +        defined by \hyperref[intro:EPOCH]{EPOCH}.
> > > +
> > > +        This clock observes positive and negative leap seconds as
> > > +        announced by standard bodies. At the start of leap seconds, the
> > > +        clock steps accordingly.
> > > +
> > > +\item[VIRTIO_RTC_CLOCK_TAI] uses the TAI (International Atomic Time)
> > > +        time standard. This clock uses the time epoch of January 1,
> > > +        1970, 00:00 TAI.
> > > +
> > > +\item[VIRTIO_RTC_CLOCK_MONOTONIC] uses monotonic physical time (SI
> > > +        seconds subdivisions) since some unspecified epoch. The epoch is
> > > +        before or during device reset.
> > > +
> > > +\item[VIRTIO_RTC_CLOCK_UTC_SMEARED] deviates from the UTC standard by
> > > +        smearing time in the vicinity of a leap second. This avoids
> > > +        clock steps due to UTC leap seconds. Otherwise, this clock is
> > > +        similar to VIRTIO_RTC_CLOCK_UTC.
> > > +
> > > +\item[VIRTIO_RTC_CLOCK_UTC_MAYBE_SMEARED] This clock
> > > +
> > > +\begin{itemize}
> > > +\item may deviate from the UTC standard by smearing time in the vicinity
> > > +        of a leap second (similar to VIRTIO_RTC_CLOCK_UTC_SMEARED), or
> > > +
> > > +\item may step at the start of leap seconds like VIRTIO_RTC_CLOCK_UTC.
> > > +\end{itemize}
> > > +
> > > +A clock of type VIRTIO_RTC_CLOCK_UTC_MAYBE_SMEARED can change this
> > > +behavior for every leap second.
> > > +
> > > +\end{description}
> > > +
> > > +In the following, \emph{UTC-like clock} designates any clock of type
> > > +VIRTIO_RTC_CLOCK_UTC, VIRTIO_RTC_CLOCK_UTC_SMEARED, or
> > > +VIRTIO_RTC_CLOCK_UTC_MAYBE_SMEARED.
> > > +
> > > +Additional clock types may be standardized in the future.
> > > +Implementation-specific definitions of clock types are not recommended.
> > > +Implementation-specific definitions use ids between 0xF0 and 0xFF.
> > > +
> > > +\paragraph{Smearing Variants}\label{sec:Device Types / RTC Device / Device Operation / Common Definitions / Smearing Variants}
> > > +
> > > +Leap second \emph{smearing variants} describe the deviation from the UTC
> > > +standard in the vicinity of a leap second. The following smearing
> > > +variants are currently defined:
> > > +
> > > +\begin{lstlisting}
> > > +#define VIRTIO_RTC_SMEAR_UNSPECIFIED    0
> > > +#define VIRTIO_RTC_SMEAR_NOON_LINEAR    1
> > > +#define VIRTIO_RTC_SMEAR_UTC_SLS        2
> > > +\end{lstlisting}
> > > +
> > > +\begin{description}
> > > +
> > > +        \item[VIRTIO_RTC_SMEAR_UNSPECIFIED] means that it is unspecified
> > > +                how time is smeared in the vicinity of leap seconds.
> > > +
> > > +        \item[VIRTIO_RTC_SMEAR_NOON_LINEAR] specifies a linear smear
> > > +                from noon prior to the leap second until noon after the
> > > +                leap second.
> > > +
> > > +        \item[VIRTIO_RTC_SMEAR_UTC_SLS] specifies a linear smear as per
> > > +                the \hyperref[intro:UTC-SLS]{UTC-SLS} proposal.
> > > +
> > > +\end{description}
> > > +
> > > +Clocks of type VIRTIO_RTC_CLOCK_UTC_SMEARED always behave according to a
> > > +smearing variant. The smearing variant does not change over the clock's
> > > +lifetime.
> > > +
> > > +For clocks of type VIRTIO_RTC_CLOCK_UTC_MAYBE_SMEARED, it is unspecified
> > > +whether leap seconds are smeared, and how leap seconds are smeared.
> > > +
> > > +Additional smearing variants may be standardized in the future.
> > > +Implementation-specific definitions of smearing variants are not
> > > +recommended. Implementation-specific definitions use ids greater than or
> > > +equal to 0xF0.
> > > +
> > > +In the following, \emph{leap smearing clock} designates
> > 
> > here, and elsewhere, it's confusing whether itemization is for either
> > or both.
> 
> I will rephrase.
> 
> > 
> > > +\begin{itemize}
> > > +
> > > +\item any clock of type VIRTIO_RTC_CLOCK_UTC_SMEARED
> > > +
> > > +\item any clock of type VIRTIO_RTC_CLOCK_UTC_MAYBE_SMEARED at any time
> > > +        when the clock is smearing a leap second.
> > > +
> > > +\end{itemize}
> > > +
> > > +\paragraph{Hardware Counters}\label{sec:Device Types / RTC Device / Device Operation / Common Definitions / Hardware Counters}
> > > +
> > > +The following hardware counter identifiers are specified:
> > > +
> > > +\begin{lstlisting}
> > > +/* Arm Generic Timer Counter-timer Virtual Count Register (CNTVCT_EL0) */
> > > +#define VIRTIO_RTC_COUNTER_ARM_VCT      0
> > > +/* x86 Time-Stamp Counter */
> > > +#define VIRTIO_RTC_COUNTER_X86_TSC      1
> > > +/* Invalid */
> > > +#define VIRTIO_RTC_COUNTER_INVALID   0xFF
> > > +\end{lstlisting}
> > > +
> > > +Additional hardware counter identifiers may be standardized in the
> > > +future. Implementation-specific hardware counter identifiers are not
> > > +recommended. Implementation-specific hardware counter identifiers have
> > > +values between 0xF0 and 0xFE.
> > 
> > Maybe something like "and are reserved for experimental implementations".
> 
> OK.
> 
> > 
> > 
> > > +
> > > +\subsubsection{Control Requests}\label{sec:Device Types / RTC Device / Device Operation / Control Requests}
> > > +
> > > +Through \emph{control requests}, the driver requests information about
> > > +the device capabilities. The driver enqueues control requests in the
> > > +requestq.
> > > +
> > > +\begin{description}
> > > +
> > > +\item[VIRTIO_RTC_REQ_CFG] discovers the number of clocks.
> > > +
> > > +\begin{lstlisting}
> > > +#define VIRTIO_RTC_REQ_CFG 0x1000 /* message type */
> > > +
> > > +struct virtio_rtc_req_cfg {
> > > +        struct virtio_rtc_req_head head;
> > > +        /* no request params */
> > > +};
> > > +
> > > +struct virtio_rtc_resp_cfg {
> > > +        struct virtio_rtc_resp_head head;
> > > +        le16 num_clocks;
> > > +        u8 reserved[6];
> > > +};
> > > +\end{lstlisting}
> > > +
> > > +Field \field{num_clocks} contains the number of clocks. A device
> > > +provides zero or more clocks. Valid clock ids are those smaller than
> > > +\field{num_clocks}.
> > > +
> > > +\item[VIRTIO_RTC_REQ_CLOCK_CAP] discovers the capabilities of the clock
> > > +identified by the \field{clock_id} field.
> > > +
> > > +\begin{lstlisting}
> > > +#define VIRTIO_RTC_REQ_CLOCK_CAP 0x1001 /* message type */
> > > +
> > > +struct virtio_rtc_req_clock_cap {
> > > +        struct virtio_rtc_req_head head;
> > > +        le16 clock_id;
> > > +        u8 reserved[6];
> > > +};
> > > +
> > > +struct virtio_rtc_resp_clock_cap {
> > > +        struct virtio_rtc_resp_head head;
> > > +        u8 type;
> > > +        u8 leap_second_smearing;
> > > +        u8 reserved[6];
> > > +};
> > > +\end{lstlisting}
> > > +
> > > +The \field{type} field identifies the clock type. A device provides
> > > +zero or more clocks for a clock type.
> > > +
> > > +Clocks of type VIRTIO_RTC_CLOCK_UTC_SMEARED indicate the \emph{smearing
> > > +variant} through field \field{leap_second_smearing}. All other clocks
> > > +set \field{leap_second_smearing} to VIRTIO_RTC_SMEAR_UNSPECIFIED.
> > > +
> > > +\item[VIRTIO_RTC_REQ_CROSS_CAP] discovers whether the device supports
> > > +cross-timestamping for a particular pair of clock and hardware counter.
> > > +
> > > +\begin{lstlisting}
> > > +#define VIRTIO_RTC_REQ_CROSS_CAP 0x1002 /* message type */
> > > +
> > > +struct virtio_rtc_req_cross_cap {
> > > +        struct virtio_rtc_req_head head;
> > > +        le16 clock_id;
> > > +        u8 hw_counter;
> > > +        u8 reserved[5];
> > > +};
> > > +
> > > +
> > > +struct virtio_rtc_resp_cross_cap {
> > > +        struct virtio_rtc_resp_head head;
> > > +#define VIRTIO_RTC_FLAG_CROSS_CAP       (1 << 0)
> > > +        u8 flags;
> > > +        u8 reserved[7];
> > > +};
> > > +\end{lstlisting}
> > > +
> > > +The \field{clock_id} field identifies the clock, and the
> > > +\field{hw_counter} field identifies the hardware counter, for which
> > > +cross-timestamp support is probed. The device sets the
> > > +VIRTIO_RTC_FLAG_CROSS_CAP flag in the \field{flags} field if the clock
> > > +supports cross-timestamping for the particular clock and hardware
> > > +counter, and clears the flag otherwise.
> > > +
> > > +\end{description}
> > > +
> > > +\subsubsection{Read Requests}\label{sec:Device Types / RTC Device / Device Operation / Read Requests}
> > > +
> > > +Through \emph{read requests}, the driver requests clock readings from
> > > +the device. The driver enqueues read requests in the requestq. The
> > > +device obtains device-side clock readings and forwards these clock
> > > +readings to the driver. The driver may enhance and interpret the clock
> > > +readings through methods which are beyond the scope of this
> > > +specification.
> > > +
> > > +Once DRIVER_OK has been set, the device should support reading every
> > > +clock, even when a clock may yet have to be aligned to reference time
> > > +sources.
> > > +
> > > +In general,
> > > +
> > > +\begin{itemize}
> > > +\item clocks may jump backwards or forward, and
> > > +\item the clock frequency may change. Clocks may be \emph{slewed},
> > > +        i.e.\ clocks may run at a frequency other than their current
> > > +        best frequency estimate.
> > > +\end{itemize}
> > > +
> > > +As long as a clock does not jump backwards, the driver clock readings
> > > +through read request responses increase monotonically:
> > > +
> > > +\begin{itemize}
> > > +\item As long as a clock does not jump backwards in-between device-side
> > > +        clock readings, the driver-side readings for that clock increase
> > > +        monotonically as well, in the order in which the driver
> > > +        marks read requests as available.
> > > +
> > > +\item The device marks read requests for the same clock as used in
> > > +        the order in which the messages were marked as available.
> > 
> > buffers are available
> 
> s/messages were marked as available/buffers are available/ ?

yes
also used

> > 
> > > +\end{itemize}
> > > +
> > > +For a clock of type VIRTIO_RTC_CLOCK_MONOTONIC, the device always returns
> > > +monotonically increasing clock readings through read request responses.
> > > +
> > > +The unit of all \field{clock_reading} fields is 1
> > > +nanosecond.\footnote{For time epochs in year 1970 or later, this means
> > > +that time until at least year 2553 can be represented in the \field{le64
> > > +clock_reading} fields.}
> > > +
> > > +\begin{description}
> > > +
> > > +\item[VIRTIO_RTC_REQ_READ] reads the clock identified by the
> > > +\field{clock_id} field. The device supports this message for every
> > > +clock.
> > > +
> > > +\begin{lstlisting}
> > > +#define VIRTIO_RTC_REQ_READ 0x0001 /* message type */
> > > +
> > > +struct virtio_rtc_req_read {
> > > +        struct virtio_rtc_req_head head;
> > > +        le16 clock_id;
> > > +        u8 reserved[6];
> > > +};
> > > +
> > > +struct virtio_rtc_resp_read {
> > > +        struct virtio_rtc_resp_head head;
> > > +        le64 clock_reading;
> > > +};
> > > +\end{lstlisting}
> > > +
> > > +\field{clock_reading} is a device-side clock reading obtained after the
> > > +message was marked as available.
> > > +
> > > +\item[VIRTIO_RTC_REQ_READ_CROSS] returns a cross-timestamp for the clock
> > > +identified by the \field{clock_id} field.\footnote{Cross-timestamping
> > > +is similar to the ptp_kvm mechanism in the Linux kernel.} This message
> > > +may yield better performance than using VIRTIO_RTC_REQ_READ.
> > > +
> > > +The driver can determine whether the device supports
> > > +VIRTIO_RTC_REQ_READ_CROSS for a specific clock and \field{hw_counter}
> > > +through VIRTIO_RTC_REQ_CROSS_CAP.
> > > +
> > > +\begin{lstlisting}
> > > +#define VIRTIO_RTC_REQ_READ_CROSS 0x0002 /* message type */
> > > +
> > > +struct virtio_rtc_req_read_cross {
> > > +        struct virtio_rtc_req_head head;
> > > +        le16 clock_id;
> > > +        u8 hw_counter;
> > > +        u8 reserved[5];
> > > +};
> > > +
> > > +struct virtio_rtc_resp_read_cross {
> > > +        struct virtio_rtc_resp_head head;
> > > +        le64 clock_reading;
> > > +        le64 counter_cycles;
> > > +};
> > > +\end{lstlisting}
> > > +
> > > +The \field{hw_counter} field specifies the hardware counter for which
> > > +the driver requests a cross-timestamp.
> > > +
> > > +Cross-timestamping returns a \field{clock_reading}, and an associated
> > > +hardware counter value, \field{counter_cycles}. The
> > > +\field{counter_cycles} field is the approximate or precise value which
> > > +the driver would have read at the \field{clock_reading} time instant
> > > +from the hardware counter identified by \field{hw_counter}. How the
> > > +device determines the value which the driver would have seen is beyond
> > > +the scope of this specification.
> > 
> > Not sure how it's beyond the scope. What exactly do you have
> > in mind? The following paragraph hints at the fact you have
> > some idea?
> 
> Determining the counter value seen by the driver requires the device to
> determine any difference of the counter offsets or counter multipliers
> applied for device and driver.
> 
> These settings may be set by a third entity such as a hypervisor and may
> even change. I do not think that generally valid recommendations on how
> to determine the value can be given.
> 
> Maybe I can add
> 
> 	To determine the \field{counter_cycles} value, the device
> 	converts the hardware counter value the device has read,
> 	accounting for any differences in counter offsets or counter
> 	multipliers between device and driver at the time of the
> 	reading.
> 
> Thanks for the comments,
> 
> Peter
> 
> > 
> > > In case hardware counter reads differ
> > > +among CPUs used by the driver, the device should assume that the driver
> > > +reads the hardware counter from the CPU which the driver enumerates as
> > > +the first.
> > > +
> > > +The hardware counter identifiers are defined in
> > > +\ref{sec:Device Types / RTC Device / Device Operation / Common Definitions / Hardware Counters}.
> > > +
> > > +\end{description}
> > > diff --git a/introduction.tex b/introduction.tex
> > > index e60298a4d78b..34f9485bc393 100644
> > > --- a/introduction.tex
> > > +++ b/introduction.tex
> > > @@ -168,6 +168,12 @@ \section{Normative References}\label{sec:Normative References}
> > >      Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP
> > >      14, RFC 8174, DOI 10.17487/RFC8174, May 2017
> > >          \newline\url{http://www.ietf.org/rfc/rfc8174.txt}\\
> > > +	\phantomsection\label{intro:EPOCH}\textbf{[EPOCH]} &
> > > +    POSIX.1-2024, Base Definitions, Seconds Since the Epoch
> > > +	\newline\url{https://pubs.opengroup.org/onlinepubs/9799919799/basedefs/V1_chap04.html#tag_04_19}\\
> > > +	\phantomsection\label{intro:UTC-SLS}\textbf{[UTC-SLS]} &
> > > +    UTC with Smoothed Leap Seconds (UTC-SLS)
> > > +	\newline\url{https://www.cl.cam.ac.uk/~mgk25/time/utc-sls/}\\
> > >  \end{longtable}
> > >  
> > >  \section{Non-Normative References}
> > > -- 
> > > 2.43.0
> > > 
> > 

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

[Peter Hilber]

On Thu, Apr 17, 2025 at 12:14:59PM -0400, Michael S. Tsirkin wrote:
> On Thu, Apr 17, 2025 at 05:14:00PM +0200, Peter Hilber wrote:
> > On Wed, Apr 16, 2025 at 11:33:44AM -0400, Michael S. Tsirkin wrote:
> > > On Thu, Mar 06, 2025 at 10:51:09AM +0100, Peter Hilber wrote:
> > > > The virtio-rtc device provides information about current time through
> > > > one or more clocks. As such, it is a Real-Time Clock (RTC) device.
> > > > 
> > > > The normative statements for this device follow in the next patch.
> > > > 
> > > > For this device, there is an RFC Linux kernel driver which is being
> > > > upstreamed, and a proprietary device implementation.
> > > > 
> > > > Miscellaneous
> > > > -------------
> > > > 
> > > > The spec does not specify how a driver should interpret clock readings,
> > > > esp. also not how to perform clock synchronization.
> > > > 
> > > > The device uses the "Timer/Clock" device id which is already part of the
> > > > specification. This device id was registered a long time ago and should
> > > > be unused according to the author's information. The name "RTC" was
> > > > determined to be the best for a device which focuses on current time.
> > > > 
> > > > Signed-off-by: Peter Hilber <quic_philber@quicinc.com>
> > > > ---
> > > > 
> > > > Notes:
> > > >     v8:
> > > >     
> > > >     - Change word order from "field X" to "the X field" (Matias Ezequiel
> > > >       Vara Larsen).
> > > >     
> > > >     - Split up sentences about implementation-specific definitions (Matias
> > > >       Ezequiel Vara Larsen).
> > > >     
> > > >     v7:
> > > >     
> > > >     - Remove leap second and performance indications from struct
> > > >       virtio_rtc_resp_read_cross. Remove backing definitions.
> > > >     
> > > >     - Add wording change which was previously mistakenly placed in last
> > > >       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 [8].
> > > >     
> > > >     - Add dedicated clock types for UTC leap second smearing (David
> > > >       Woodhouse).
> > > >     
> > > >     - Extend leap second indications.
> > > >     
> > > >     - Split UTC-TAI offset and fractional offset due to smearing (David
> > > >       Woodhouse).
> > > >     
> > > >     - Remove requirement that TAI offset must not be a whole second while
> > > >       clock is being smeared.
> > > >     
> > > >     - Align bit widths, and some names, with '[RFC PATCH v4] ptp: Add
> > > >       vDSO-style vmclock support' [8].
> > > >     
> > > >     - 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.
> > > >     
> > > >     v4:
> > > >     
> > > >     - Drop distinction of Arm Generic Timer virtual and physical counter [7].
> > > >     
> > > >     - Add requirement that device should assume that driver reads clock from
> > > >       first vCPU (David Woodhouse) [6].
> > > >     
> > > >     - Formatting and wording improvements.
> > > >     
> > > >     v3:
> > > >     
> > > >     - Address comments from Parav Pandit.
> > > >     
> > > >     - Split off normative requirements into a second commit [2].
> > > >     
> > > >     - Merge readq and controlq into requestq [3].
> > > >     
> > > >     - Don't guard cross-timestamping with feature bit [3].
> > > >     
> > > >     - Pad request headers to 64 bit [2].
> > > >     
> > > >     - Rename Virtio status codes to match UNIX error names [2].
> > > >     
> > > >     - Avoid Virtio status code clashes with net controlq ack values.
> > > >     
> > > >     - Reword to refer more to "requests", rather than "messages" [2].
> > > >     
> > > >     - Rephrase some sentences [2].
> > > >     
> > > >     - Use integer data types without "__" prefixes [2].
> > > >     
> > > >     - Reduce clock id width to 16 bits [5].
> > > >     
> > > >     - Make VIRTIO_RTC_FLAG_CROSS_CAP a bit mask rather than a bit index.
> > > >     
> > > >     v2:
> > > >     
> > > >     - Address comments from Cornelia Huck.
> > > >     
> > > >     - Add VIRTIO_RTC_M_CROSS_CAP message [1].
> > > >     
> > > >     - Fix various minor issues and improve wording [1].
> > > >     
> > > >     - Add several clarifications regarding device error statuses.
> > > >     
> > > >     [1] https://lists.oasis-open.org/archives/virtio-comment/202304/msg00523.html
> > > >     [2] https://lore.kernel.org/virtio-comment/b59a7dda-06fe-cff9-df61-b90aa4e50836@opensynergy.com/t/#mffb93800fea11d6dda9e151078abedd6ff1c0f1e
> > > >     [3] https://lore.kernel.org/virtio-comment/b59a7dda-06fe-cff9-df61-b90aa4e50836@opensynergy.com/t/#m94efd0aa9b9c2b96a246b79ef8bfc3bf64ebe791
> > > >     [4] https://lore.kernel.org/lkml/20230630171052.985577-1-peter.hilber@opensynergy.com/T/#m65fa1d715933360498c4e33d7225e4220215a9d6
> > > >     [5] https://lore.kernel.org/virtio-comment/b59a7dda-06fe-cff9-df61-b90aa4e50836@opensynergy.com/t/#mf00ce330228c28556d735eb9597469048c5d8b62
> > > >     [6] https://lore.kernel.org/lkml/d796d9a5-8eda-4528-a6d8-1c4eba24aa1e@opensynergy.com/
> > > >     [7] https://lore.kernel.org/all/20231218064253.9734-2-peter.hilber@opensynergy.com/
> > > >     [8] https://lore.kernel.org/lkml/20240708092924.1473461-1-dwmw2@infradead.org/
> > > > 
> > > >  content.tex                      |   3 +-
> > > >  device-types/rtc/description.tex | 428 +++++++++++++++++++++++++++++++
> > > >  introduction.tex                 |   6 +
> > > >  3 files changed, 436 insertions(+), 1 deletion(-)
> > > >  create mode 100644 device-types/rtc/description.tex
> > > > 
> > > > diff --git a/content.tex b/content.tex
> > > > index 67b1bf3c35ab..b1d93a8aebb4 100644
> > > > --- a/content.tex
> > > > +++ b/content.tex
> > > > @@ -684,7 +684,7 @@ \chapter{Device Types}\label{sec:Device Types}
> > > >  \hline
> > > >  16         &   GPU device       \\
> > > >  \hline
> > > > -17         &   Timer/Clock device \\
> > > > +17         &   RTC (Timer/Clock) device \\
> > > 
> > > 
> > > Do you want to change it to Real Time Clock here then?
> > 
> > OK.
> > 
> > > 
> > > >  \hline
> > > >  18         &   Input device \\
> > > >  \hline
> > > > @@ -776,6 +776,7 @@ \chapter{Device Types}\label{sec:Device Types}
> > > >  \input{device-types/pmem/description.tex}
> > > >  \input{device-types/can/description.tex}
> > > >  \input{device-types/spi/description.tex}
> > > > +\input{device-types/rtc/description.tex}
> > > >  
> > > >  \chapter{Reserved Feature Bits}\label{sec:Reserved Feature Bits}
> > > >  
> > > > diff --git a/device-types/rtc/description.tex b/device-types/rtc/description.tex
> > > > new file mode 100644
> > > > index 000000000000..5d8cf91a6991
> > > > --- /dev/null
> > > > +++ b/device-types/rtc/description.tex
> > > > @@ -0,0 +1,428 @@
> > > > +\section{RTC Device}\label{sec:Device Types / RTC Device}
> > > > +
> > > > +The RTC (Real Time Clock) device provides information about current
> > > > +time. The device can provide different clocks, e.g.\ for the UTC or TAI
> > > > +time standards, or for physical time elapsed since some past epoch. The
> > > > +driver can read the clocks with simple or more accurate methods.
> > > > +
> > > > +\subsection{Device ID}\label{sec:Device Types / RTC Device / Device ID}
> > > > +
> > > > +17
> > > > +
> > > > +\subsection{Virtqueues}\label{sec:Device Types / RTC Device / Virtqueues}
> > > > +
> > > > +\begin{description}
> > > > +\item[0] requestq
> > > > +\end{description}
> > > > +
> > > > +The driver enqueues requests to the requestq.
> > > > +
> > > > +\subsection{Feature bits}\label{sec:Device Types / RTC Device / Feature bits}
> > > > +
> > > > +No device-specific feature bits are defined yet.
> > > 
> > > Just say:
> > > 
> > > None
> > > 
> > > like SPI
> > > 
> > > or
> > > 
> > > None currently defined.
> > > 
> > > like entropy.
> > 
> > OK.
> > 
> > > 
> > > 
> > > 
> > > > +\subsection{Device configuration layout}\label{sec:Device Types / RTC Device / Device configuration layout}
> > > > +
> > > > +There is no configuration data for the device.
> > > 
> > > None currently defined.
> > > 
> > > configuration data is not a thing
> > 
> > OK.
> > 
> > > 
> > > 
> > > > +\subsection{Device Initialization}\label{sec:Device Types / RTC Device / Device Initialization}
> > > > +
> > > > +The device determines the set of clocks. The device can provide zero or
> > > > +more clocks.
> > > > +
> > > > +\subsection{Device Operation}\label{sec:Device Types / RTC Device / Device Operation}
> > > > +
> > > > +For the requestq, the driver sends a message with a request, and
> > > > +receives the response in the device-writable part of the message.
> > > 
> > > 
> > > Hmm. This confuses two things.
> > > 
> > > The device-writable part is in the buffer.
> > > Message type is the request type.
> > 
> > How about this?
> > 
> > 	For the requestq, the driver sends a message with a request. The
> > 	device fills in the message response and returns the message.
> 
> 
> returns the message is not a thing.
> really the consept of message is extraneous.
> what you want it to mean is mostly a buffer.
> we have terminology for that: make available, use.
> Just use it do not come up with your own.

OK. I think I could rephrase like this:

	The driver makes a request available in the requestq. The device
	fills in the response and uses the buffer.

As for msg_type (message type), I can change this to req_type resp.
notif_type (for the alarmq). However, to me, the message concept seems
to be somewhat established, and useful, at a higher level in the
existing spec.

> 
> > 
> > > 
> > > 
> > > > The
> > > > +requestq uses common request and response headers.
> > > > +
> > > > +\begin{lstlisting}
> > > > +/* common request header */
> > > > +struct virtio_rtc_req_head {
> > > > +        le16 msg_type;
> > > > +        u8 reserved[6];
> > > > +};
> > > > +
> > > > +/* common response header */
> > > > +struct virtio_rtc_resp_head {
> > > > +        u8 status;
> > > > +        u8 reserved[7];
> > > > +};
> > > > +\end{lstlisting}
> > > > +
> > > > +The \field{msg_type} field identifies the message type.
> > > > +
> > > > +The \field{status} field indicates whether the device successfully
> > > > +executed the request. The device sets the \field{status} field to one of
> > > > +the following values:
> > > > +
> > > > +\begin{lstlisting}
> > > > +#define VIRTIO_RTC_S_OK         0
> > > > +#define VIRTIO_RTC_S_EOPNOTSUPP 2
> > > > +#define VIRTIO_RTC_S_ENODEV     3
> > > > +#define VIRTIO_RTC_S_EINVAL     4
> > > > +#define VIRTIO_RTC_S_EIO        5
> > > > +\end{lstlisting}
> > > > +
> > > > +VIRTIO_RTC_S_OK indicates that the device successfully executed the
> > > > +request.
> > > > +
> > > > +If \field{status} is not VIRTIO_RTC_S_OK, the value of other response
> > > > +fields is undefined.
> > > > +
> > > > +VIRTIO_RTC_S_EOPNOTSUPP indicates that the device could not execute the
> > > > +specific request due to an implementation limitation. The device also
> > > > +returns status VIRTIO_RTC_S_EOPNOTSUPP for requests with unknown values
> > > > +in the fields \field{msg_type} or \field{hw_counter}.
> > > > +
> > > > +VIRTIO_RTC_S_ENODEV indicates that the \field{clock_id} field value
> > > > +supplied with the request does not identify a clock.
> > > > +
> > > > +VIRTIO_RTC_S_EINVAL indicates that
> > > 
> > > either? or both?
> > 
> > Can be either or both (inclusive "or"). I will state this more explicitly.
> > 
> > > 
> > > > +
> > > > +\begin{itemize}
> > > > +\item the driver request values are not allowed by the specification or
> > > 
> > > how do you mean? not recognized by the device? what do you expect
> > > driver to do? assert basically? no well behaved driver will
> > > encounter it right?
> > 
> > This would indicate a bug in the driver or device. A well-behaved driver
> > should not get any error from the device, ever.
> 
> worth clarifying

OK.

> 
> > For a Linux kernel driver, I am not sure if the driver should stop using
> > the device immediately, though.
> > 
> > > 
> > > 
> > > 
> > > 
> > > > +\item the device read-only part of the message, or the device write-only
> > > > +        part of the message, is too small to fit the actual message.
> > > 
> > > what is the actual message? do you mean the read-only part is too
> > > small to fit the request or the write-only part is too small to
> > > fit the response?
> > 
> > Yes. I will rephrase this.
> > 
> > > 
> > > 
> > > > +\end{itemize}
> > > > +
> > > > +VIRTIO_RTC_S_EIO indicates that the device did not execute the request
> > > > +due to an error which was not caused by invalid input from the driver.
> > > > +
> > > > +All \field{reserved} fields are written as zero, and their value is
> > > > +ignored.
> > > > +
> > > > +The set of clocks does not change after feature negotiation completion,
> > > > +until device reset. The set of clocks should not change on device reset
> > > > +either (similar to negotiated features). Clock identifiers are
> > > > +zero-based, dense indices. All fields
> > > 
> > > in which structure? within request structures?
> > 
> > Within request structures, and within the notification structure added
> > in patch 3. I will mention this.
> > 
> > > 
> > > > named \field{clock_id} contain
> > > > +clock identifiers.
> > > > +
> > > > +\subsubsection{Common Definitions}\label{sec:Device Types / RTC Device / Device Operation / Common Definitions}
> > > > +
> > > > +This section makes common definitions.
> > > > +
> > > > +\paragraph{Clock Types}\label{sec:Device Types / RTC Device / Device Operation / Common Definitions / Clock Types}
> > > > +
> > > > +The following clock types are defined:
> > > > +
> > > > +\begin{lstlisting}
> > > > +#define VIRTIO_RTC_CLOCK_UTC                    0
> > > > +#define VIRTIO_RTC_CLOCK_TAI                    1
> > > > +#define VIRTIO_RTC_CLOCK_MONOTONIC              2
> > > > +#define VIRTIO_RTC_CLOCK_UTC_SMEARED            3
> > > > +#define VIRTIO_RTC_CLOCK_UTC_MAYBE_SMEARED      4
> > > > +\end{lstlisting}
> > > > +
> > > > +\begin{description}
> > > > +
> > > > +\item[VIRTIO_RTC_CLOCK_UTC] uses the UTC (Coordinated Universal Time)
> > > > +        time standard. This clock uses the time epoch of January 1,
> > > > +        1970, 00:00 UTC. This is the same epoch as \emph{Unix time}. The
> > > > +        clock's seconds since the epoch are related to UTC time as
> > > > +        defined by \hyperref[intro:EPOCH]{EPOCH}.
> > > > +
> > > > +        This clock observes positive and negative leap seconds as
> > > > +        announced by standard bodies. At the start of leap seconds, the
> > > > +        clock steps accordingly.
> > > > +
> > > > +\item[VIRTIO_RTC_CLOCK_TAI] uses the TAI (International Atomic Time)
> > > > +        time standard. This clock uses the time epoch of January 1,
> > > > +        1970, 00:00 TAI.
> > > > +
> > > > +\item[VIRTIO_RTC_CLOCK_MONOTONIC] uses monotonic physical time (SI
> > > > +        seconds subdivisions) since some unspecified epoch. The epoch is
> > > > +        before or during device reset.
> > > > +
> > > > +\item[VIRTIO_RTC_CLOCK_UTC_SMEARED] deviates from the UTC standard by
> > > > +        smearing time in the vicinity of a leap second. This avoids
> > > > +        clock steps due to UTC leap seconds. Otherwise, this clock is
> > > > +        similar to VIRTIO_RTC_CLOCK_UTC.
> > > > +
> > > > +\item[VIRTIO_RTC_CLOCK_UTC_MAYBE_SMEARED] This clock
> > > > +
> > > > +\begin{itemize}
> > > > +\item may deviate from the UTC standard by smearing time in the vicinity
> > > > +        of a leap second (similar to VIRTIO_RTC_CLOCK_UTC_SMEARED), or
> > > > +
> > > > +\item may step at the start of leap seconds like VIRTIO_RTC_CLOCK_UTC.
> > > > +\end{itemize}
> > > > +
> > > > +A clock of type VIRTIO_RTC_CLOCK_UTC_MAYBE_SMEARED can change this
> > > > +behavior for every leap second.
> > > > +
> > > > +\end{description}
> > > > +
> > > > +In the following, \emph{UTC-like clock} designates any clock of type
> > > > +VIRTIO_RTC_CLOCK_UTC, VIRTIO_RTC_CLOCK_UTC_SMEARED, or
> > > > +VIRTIO_RTC_CLOCK_UTC_MAYBE_SMEARED.
> > > > +
> > > > +Additional clock types may be standardized in the future.
> > > > +Implementation-specific definitions of clock types are not recommended.
> > > > +Implementation-specific definitions use ids between 0xF0 and 0xFF.
> > > > +
> > > > +\paragraph{Smearing Variants}\label{sec:Device Types / RTC Device / Device Operation / Common Definitions / Smearing Variants}
> > > > +
> > > > +Leap second \emph{smearing variants} describe the deviation from the UTC
> > > > +standard in the vicinity of a leap second. The following smearing
> > > > +variants are currently defined:
> > > > +
> > > > +\begin{lstlisting}
> > > > +#define VIRTIO_RTC_SMEAR_UNSPECIFIED    0
> > > > +#define VIRTIO_RTC_SMEAR_NOON_LINEAR    1
> > > > +#define VIRTIO_RTC_SMEAR_UTC_SLS        2
> > > > +\end{lstlisting}
> > > > +
> > > > +\begin{description}
> > > > +
> > > > +        \item[VIRTIO_RTC_SMEAR_UNSPECIFIED] means that it is unspecified
> > > > +                how time is smeared in the vicinity of leap seconds.
> > > > +
> > > > +        \item[VIRTIO_RTC_SMEAR_NOON_LINEAR] specifies a linear smear
> > > > +                from noon prior to the leap second until noon after the
> > > > +                leap second.
> > > > +
> > > > +        \item[VIRTIO_RTC_SMEAR_UTC_SLS] specifies a linear smear as per
> > > > +                the \hyperref[intro:UTC-SLS]{UTC-SLS} proposal.
> > > > +
> > > > +\end{description}
> > > > +
> > > > +Clocks of type VIRTIO_RTC_CLOCK_UTC_SMEARED always behave according to a
> > > > +smearing variant. The smearing variant does not change over the clock's
> > > > +lifetime.
> > > > +
> > > > +For clocks of type VIRTIO_RTC_CLOCK_UTC_MAYBE_SMEARED, it is unspecified
> > > > +whether leap seconds are smeared, and how leap seconds are smeared.
> > > > +
> > > > +Additional smearing variants may be standardized in the future.
> > > > +Implementation-specific definitions of smearing variants are not
> > > > +recommended. Implementation-specific definitions use ids greater than or
> > > > +equal to 0xF0.
> > > > +
> > > > +In the following, \emph{leap smearing clock} designates
> > > 
> > > here, and elsewhere, it's confusing whether itemization is for either
> > > or both.
> > 
> > I will rephrase.
> > 
> > > 
> > > > +\begin{itemize}
> > > > +
> > > > +\item any clock of type VIRTIO_RTC_CLOCK_UTC_SMEARED
> > > > +
> > > > +\item any clock of type VIRTIO_RTC_CLOCK_UTC_MAYBE_SMEARED at any time
> > > > +        when the clock is smearing a leap second.
> > > > +
> > > > +\end{itemize}
> > > > +
> > > > +\paragraph{Hardware Counters}\label{sec:Device Types / RTC Device / Device Operation / Common Definitions / Hardware Counters}
> > > > +
> > > > +The following hardware counter identifiers are specified:
> > > > +
> > > > +\begin{lstlisting}
> > > > +/* Arm Generic Timer Counter-timer Virtual Count Register (CNTVCT_EL0) */
> > > > +#define VIRTIO_RTC_COUNTER_ARM_VCT      0
> > > > +/* x86 Time-Stamp Counter */
> > > > +#define VIRTIO_RTC_COUNTER_X86_TSC      1
> > > > +/* Invalid */
> > > > +#define VIRTIO_RTC_COUNTER_INVALID   0xFF
> > > > +\end{lstlisting}
> > > > +
> > > > +Additional hardware counter identifiers may be standardized in the
> > > > +future. Implementation-specific hardware counter identifiers are not
> > > > +recommended. Implementation-specific hardware counter identifiers have
> > > > +values between 0xF0 and 0xFE.
> > > 
> > > Maybe something like "and are reserved for experimental implementations".
> > 
> > OK.
> > 
> > > 
> > > 
> > > > +
> > > > +\subsubsection{Control Requests}\label{sec:Device Types / RTC Device / Device Operation / Control Requests}
> > > > +
> > > > +Through \emph{control requests}, the driver requests information about
> > > > +the device capabilities. The driver enqueues control requests in the
> > > > +requestq.
> > > > +
> > > > +\begin{description}
> > > > +
> > > > +\item[VIRTIO_RTC_REQ_CFG] discovers the number of clocks.
> > > > +
> > > > +\begin{lstlisting}
> > > > +#define VIRTIO_RTC_REQ_CFG 0x1000 /* message type */
> > > > +
> > > > +struct virtio_rtc_req_cfg {
> > > > +        struct virtio_rtc_req_head head;
> > > > +        /* no request params */
> > > > +};
> > > > +
> > > > +struct virtio_rtc_resp_cfg {
> > > > +        struct virtio_rtc_resp_head head;
> > > > +        le16 num_clocks;
> > > > +        u8 reserved[6];
> > > > +};
> > > > +\end{lstlisting}
> > > > +
> > > > +Field \field{num_clocks} contains the number of clocks. A device
> > > > +provides zero or more clocks. Valid clock ids are those smaller than
> > > > +\field{num_clocks}.
> > > > +
> > > > +\item[VIRTIO_RTC_REQ_CLOCK_CAP] discovers the capabilities of the clock
> > > > +identified by the \field{clock_id} field.
> > > > +
> > > > +\begin{lstlisting}
> > > > +#define VIRTIO_RTC_REQ_CLOCK_CAP 0x1001 /* message type */
> > > > +
> > > > +struct virtio_rtc_req_clock_cap {
> > > > +        struct virtio_rtc_req_head head;
> > > > +        le16 clock_id;
> > > > +        u8 reserved[6];
> > > > +};
> > > > +
> > > > +struct virtio_rtc_resp_clock_cap {
> > > > +        struct virtio_rtc_resp_head head;
> > > > +        u8 type;
> > > > +        u8 leap_second_smearing;
> > > > +        u8 reserved[6];
> > > > +};
> > > > +\end{lstlisting}
> > > > +
> > > > +The \field{type} field identifies the clock type. A device provides
> > > > +zero or more clocks for a clock type.
> > > > +
> > > > +Clocks of type VIRTIO_RTC_CLOCK_UTC_SMEARED indicate the \emph{smearing
> > > > +variant} through field \field{leap_second_smearing}. All other clocks
> > > > +set \field{leap_second_smearing} to VIRTIO_RTC_SMEAR_UNSPECIFIED.
> > > > +
> > > > +\item[VIRTIO_RTC_REQ_CROSS_CAP] discovers whether the device supports
> > > > +cross-timestamping for a particular pair of clock and hardware counter.
> > > > +
> > > > +\begin{lstlisting}
> > > > +#define VIRTIO_RTC_REQ_CROSS_CAP 0x1002 /* message type */
> > > > +
> > > > +struct virtio_rtc_req_cross_cap {
> > > > +        struct virtio_rtc_req_head head;
> > > > +        le16 clock_id;
> > > > +        u8 hw_counter;
> > > > +        u8 reserved[5];
> > > > +};
> > > > +
> > > > +
> > > > +struct virtio_rtc_resp_cross_cap {
> > > > +        struct virtio_rtc_resp_head head;
> > > > +#define VIRTIO_RTC_FLAG_CROSS_CAP       (1 << 0)
> > > > +        u8 flags;
> > > > +        u8 reserved[7];
> > > > +};
> > > > +\end{lstlisting}
> > > > +
> > > > +The \field{clock_id} field identifies the clock, and the
> > > > +\field{hw_counter} field identifies the hardware counter, for which
> > > > +cross-timestamp support is probed. The device sets the
> > > > +VIRTIO_RTC_FLAG_CROSS_CAP flag in the \field{flags} field if the clock
> > > > +supports cross-timestamping for the particular clock and hardware
> > > > +counter, and clears the flag otherwise.
> > > > +
> > > > +\end{description}
> > > > +
> > > > +\subsubsection{Read Requests}\label{sec:Device Types / RTC Device / Device Operation / Read Requests}
> > > > +
> > > > +Through \emph{read requests}, the driver requests clock readings from
> > > > +the device. The driver enqueues read requests in the requestq. The
> > > > +device obtains device-side clock readings and forwards these clock
> > > > +readings to the driver. The driver may enhance and interpret the clock
> > > > +readings through methods which are beyond the scope of this
> > > > +specification.
> > > > +
> > > > +Once DRIVER_OK has been set, the device should support reading every
> > > > +clock, even when a clock may yet have to be aligned to reference time
> > > > +sources.
> > > > +
> > > > +In general,
> > > > +
> > > > +\begin{itemize}
> > > > +\item clocks may jump backwards or forward, and
> > > > +\item the clock frequency may change. Clocks may be \emph{slewed},
> > > > +        i.e.\ clocks may run at a frequency other than their current
> > > > +        best frequency estimate.
> > > > +\end{itemize}
> > > > +
> > > > +As long as a clock does not jump backwards, the driver clock readings
> > > > +through read request responses increase monotonically:
> > > > +
> > > > +\begin{itemize}
> > > > +\item As long as a clock does not jump backwards in-between device-side
> > > > +        clock readings, the driver-side readings for that clock increase
> > > > +        monotonically as well, in the order in which the driver
> > > > +        marks read requests as available.
> > > > +
> > > > +\item The device marks read requests for the same clock as used in
> > > > +        the order in which the messages were marked as available.
> > > 
> > > buffers are available
> > 
> > s/messages were marked as available/buffers are available/ ?
> 
> yes
> also used
> 

OK.

Thanks for the reply,

Peter

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

[Michael S. Tsirkin]

On Tue, Apr 22, 2025 at 12:47:18PM +0200, Peter Hilber wrote:
> On Thu, Apr 17, 2025 at 12:14:59PM -0400, Michael S. Tsirkin wrote:
> > On Thu, Apr 17, 2025 at 05:14:00PM +0200, Peter Hilber wrote:
> > > On Wed, Apr 16, 2025 at 11:33:44AM -0400, Michael S. Tsirkin wrote:
> > > > On Thu, Mar 06, 2025 at 10:51:09AM +0100, Peter Hilber wrote:
> > > > > The virtio-rtc device provides information about current time through
> > > > > one or more clocks. As such, it is a Real-Time Clock (RTC) device.
> > > > > 
> > > > > The normative statements for this device follow in the next patch.
> > > > > 
> > > > > For this device, there is an RFC Linux kernel driver which is being
> > > > > upstreamed, and a proprietary device implementation.
> > > > > 
> > > > > Miscellaneous
> > > > > -------------
> > > > > 
> > > > > The spec does not specify how a driver should interpret clock readings,
> > > > > esp. also not how to perform clock synchronization.
> > > > > 
> > > > > The device uses the "Timer/Clock" device id which is already part of the
> > > > > specification. This device id was registered a long time ago and should
> > > > > be unused according to the author's information. The name "RTC" was
> > > > > determined to be the best for a device which focuses on current time.
> > > > > 
> > > > > Signed-off-by: Peter Hilber <quic_philber@quicinc.com>
> > > > > ---
> > > > > 
> > > > > Notes:
> > > > >     v8:
> > > > >     
> > > > >     - Change word order from "field X" to "the X field" (Matias Ezequiel
> > > > >       Vara Larsen).
> > > > >     
> > > > >     - Split up sentences about implementation-specific definitions (Matias
> > > > >       Ezequiel Vara Larsen).
> > > > >     
> > > > >     v7:
> > > > >     
> > > > >     - Remove leap second and performance indications from struct
> > > > >       virtio_rtc_resp_read_cross. Remove backing definitions.
> > > > >     
> > > > >     - Add wording change which was previously mistakenly placed in last
> > > > >       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 [8].
> > > > >     
> > > > >     - Add dedicated clock types for UTC leap second smearing (David
> > > > >       Woodhouse).
> > > > >     
> > > > >     - Extend leap second indications.
> > > > >     
> > > > >     - Split UTC-TAI offset and fractional offset due to smearing (David
> > > > >       Woodhouse).
> > > > >     
> > > > >     - Remove requirement that TAI offset must not be a whole second while
> > > > >       clock is being smeared.
> > > > >     
> > > > >     - Align bit widths, and some names, with '[RFC PATCH v4] ptp: Add
> > > > >       vDSO-style vmclock support' [8].
> > > > >     
> > > > >     - 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.
> > > > >     
> > > > >     v4:
> > > > >     
> > > > >     - Drop distinction of Arm Generic Timer virtual and physical counter [7].
> > > > >     
> > > > >     - Add requirement that device should assume that driver reads clock from
> > > > >       first vCPU (David Woodhouse) [6].
> > > > >     
> > > > >     - Formatting and wording improvements.
> > > > >     
> > > > >     v3:
> > > > >     
> > > > >     - Address comments from Parav Pandit.
> > > > >     
> > > > >     - Split off normative requirements into a second commit [2].
> > > > >     
> > > > >     - Merge readq and controlq into requestq [3].
> > > > >     
> > > > >     - Don't guard cross-timestamping with feature bit [3].
> > > > >     
> > > > >     - Pad request headers to 64 bit [2].
> > > > >     
> > > > >     - Rename Virtio status codes to match UNIX error names [2].
> > > > >     
> > > > >     - Avoid Virtio status code clashes with net controlq ack values.
> > > > >     
> > > > >     - Reword to refer more to "requests", rather than "messages" [2].
> > > > >     
> > > > >     - Rephrase some sentences [2].
> > > > >     
> > > > >     - Use integer data types without "__" prefixes [2].
> > > > >     
> > > > >     - Reduce clock id width to 16 bits [5].
> > > > >     
> > > > >     - Make VIRTIO_RTC_FLAG_CROSS_CAP a bit mask rather than a bit index.
> > > > >     
> > > > >     v2:
> > > > >     
> > > > >     - Address comments from Cornelia Huck.
> > > > >     
> > > > >     - Add VIRTIO_RTC_M_CROSS_CAP message [1].
> > > > >     
> > > > >     - Fix various minor issues and improve wording [1].
> > > > >     
> > > > >     - Add several clarifications regarding device error statuses.
> > > > >     
> > > > >     [1] https://lists.oasis-open.org/archives/virtio-comment/202304/msg00523.html
> > > > >     [2] https://lore.kernel.org/virtio-comment/b59a7dda-06fe-cff9-df61-b90aa4e50836@opensynergy.com/t/#mffb93800fea11d6dda9e151078abedd6ff1c0f1e
> > > > >     [3] https://lore.kernel.org/virtio-comment/b59a7dda-06fe-cff9-df61-b90aa4e50836@opensynergy.com/t/#m94efd0aa9b9c2b96a246b79ef8bfc3bf64ebe791
> > > > >     [4] https://lore.kernel.org/lkml/20230630171052.985577-1-peter.hilber@opensynergy.com/T/#m65fa1d715933360498c4e33d7225e4220215a9d6
> > > > >     [5] https://lore.kernel.org/virtio-comment/b59a7dda-06fe-cff9-df61-b90aa4e50836@opensynergy.com/t/#mf00ce330228c28556d735eb9597469048c5d8b62
> > > > >     [6] https://lore.kernel.org/lkml/d796d9a5-8eda-4528-a6d8-1c4eba24aa1e@opensynergy.com/
> > > > >     [7] https://lore.kernel.org/all/20231218064253.9734-2-peter.hilber@opensynergy.com/
> > > > >     [8] https://lore.kernel.org/lkml/20240708092924.1473461-1-dwmw2@infradead.org/
> > > > > 
> > > > >  content.tex                      |   3 +-
> > > > >  device-types/rtc/description.tex | 428 +++++++++++++++++++++++++++++++
> > > > >  introduction.tex                 |   6 +
> > > > >  3 files changed, 436 insertions(+), 1 deletion(-)
> > > > >  create mode 100644 device-types/rtc/description.tex
> > > > > 
> > > > > diff --git a/content.tex b/content.tex
> > > > > index 67b1bf3c35ab..b1d93a8aebb4 100644
> > > > > --- a/content.tex
> > > > > +++ b/content.tex
> > > > > @@ -684,7 +684,7 @@ \chapter{Device Types}\label{sec:Device Types}
> > > > >  \hline
> > > > >  16         &   GPU device       \\
> > > > >  \hline
> > > > > -17         &   Timer/Clock device \\
> > > > > +17         &   RTC (Timer/Clock) device \\
> > > > 
> > > > 
> > > > Do you want to change it to Real Time Clock here then?
> > > 
> > > OK.
> > > 
> > > > 
> > > > >  \hline
> > > > >  18         &   Input device \\
> > > > >  \hline
> > > > > @@ -776,6 +776,7 @@ \chapter{Device Types}\label{sec:Device Types}
> > > > >  \input{device-types/pmem/description.tex}
> > > > >  \input{device-types/can/description.tex}
> > > > >  \input{device-types/spi/description.tex}
> > > > > +\input{device-types/rtc/description.tex}
> > > > >  
> > > > >  \chapter{Reserved Feature Bits}\label{sec:Reserved Feature Bits}
> > > > >  
> > > > > diff --git a/device-types/rtc/description.tex b/device-types/rtc/description.tex
> > > > > new file mode 100644
> > > > > index 000000000000..5d8cf91a6991
> > > > > --- /dev/null
> > > > > +++ b/device-types/rtc/description.tex
> > > > > @@ -0,0 +1,428 @@
> > > > > +\section{RTC Device}\label{sec:Device Types / RTC Device}
> > > > > +
> > > > > +The RTC (Real Time Clock) device provides information about current
> > > > > +time. The device can provide different clocks, e.g.\ for the UTC or TAI
> > > > > +time standards, or for physical time elapsed since some past epoch. The
> > > > > +driver can read the clocks with simple or more accurate methods.
> > > > > +
> > > > > +\subsection{Device ID}\label{sec:Device Types / RTC Device / Device ID}
> > > > > +
> > > > > +17
> > > > > +
> > > > > +\subsection{Virtqueues}\label{sec:Device Types / RTC Device / Virtqueues}
> > > > > +
> > > > > +\begin{description}
> > > > > +\item[0] requestq
> > > > > +\end{description}
> > > > > +
> > > > > +The driver enqueues requests to the requestq.
> > > > > +
> > > > > +\subsection{Feature bits}\label{sec:Device Types / RTC Device / Feature bits}
> > > > > +
> > > > > +No device-specific feature bits are defined yet.
> > > > 
> > > > Just say:
> > > > 
> > > > None
> > > > 
> > > > like SPI
> > > > 
> > > > or
> > > > 
> > > > None currently defined.
> > > > 
> > > > like entropy.
> > > 
> > > OK.
> > > 
> > > > 
> > > > 
> > > > 
> > > > > +\subsection{Device configuration layout}\label{sec:Device Types / RTC Device / Device configuration layout}
> > > > > +
> > > > > +There is no configuration data for the device.
> > > > 
> > > > None currently defined.
> > > > 
> > > > configuration data is not a thing
> > > 
> > > OK.
> > > 
> > > > 
> > > > 
> > > > > +\subsection{Device Initialization}\label{sec:Device Types / RTC Device / Device Initialization}
> > > > > +
> > > > > +The device determines the set of clocks. The device can provide zero or
> > > > > +more clocks.
> > > > > +
> > > > > +\subsection{Device Operation}\label{sec:Device Types / RTC Device / Device Operation}
> > > > > +
> > > > > +For the requestq, the driver sends a message with a request, and
> > > > > +receives the response in the device-writable part of the message.
> > > > 
> > > > 
> > > > Hmm. This confuses two things.
> > > > 
> > > > The device-writable part is in the buffer.
> > > > Message type is the request type.
> > > 
> > > How about this?
> > > 
> > > 	For the requestq, the driver sends a message with a request. The
> > > 	device fills in the message response and returns the message.
> > 
> > 
> > returns the message is not a thing.
> > really the consept of message is extraneous.
> > what you want it to mean is mostly a buffer.
> > we have terminology for that: make available, use.
> > Just use it do not come up with your own.
> 
> OK. I think I could rephrase like this:
> 
> 	The driver makes a request available in the requestq. The device
> 	fills in the response and uses the buffer.

Sounds good.

> As for msg_type (message type), I can change this to req_type resp.
> notif_type (for the alarmq). However, to me, the message concept seems
> to be somewhat established, and useful, at a higher level in the
> existing spec.

It's not really used in this patch and not defined in the spec. If you
want to use it, define it.

> > 
> > > 
> > > > 
> > > > 
> > > > > The
> > > > > +requestq uses common request and response headers.
> > > > > +
> > > > > +\begin{lstlisting}
> > > > > +/* common request header */
> > > > > +struct virtio_rtc_req_head {
> > > > > +        le16 msg_type;
> > > > > +        u8 reserved[6];
> > > > > +};
> > > > > +
> > > > > +/* common response header */
> > > > > +struct virtio_rtc_resp_head {
> > > > > +        u8 status;
> > > > > +        u8 reserved[7];
> > > > > +};
> > > > > +\end{lstlisting}
> > > > > +
> > > > > +The \field{msg_type} field identifies the message type.
> > > > > +
> > > > > +The \field{status} field indicates whether the device successfully
> > > > > +executed the request. The device sets the \field{status} field to one of
> > > > > +the following values:
> > > > > +
> > > > > +\begin{lstlisting}
> > > > > +#define VIRTIO_RTC_S_OK         0
> > > > > +#define VIRTIO_RTC_S_EOPNOTSUPP 2
> > > > > +#define VIRTIO_RTC_S_ENODEV     3
> > > > > +#define VIRTIO_RTC_S_EINVAL     4
> > > > > +#define VIRTIO_RTC_S_EIO        5
> > > > > +\end{lstlisting}
> > > > > +
> > > > > +VIRTIO_RTC_S_OK indicates that the device successfully executed the
> > > > > +request.
> > > > > +
> > > > > +If \field{status} is not VIRTIO_RTC_S_OK, the value of other response
> > > > > +fields is undefined.
> > > > > +
> > > > > +VIRTIO_RTC_S_EOPNOTSUPP indicates that the device could not execute the
> > > > > +specific request due to an implementation limitation. The device also
> > > > > +returns status VIRTIO_RTC_S_EOPNOTSUPP for requests with unknown values
> > > > > +in the fields \field{msg_type} or \field{hw_counter}.
> > > > > +
> > > > > +VIRTIO_RTC_S_ENODEV indicates that the \field{clock_id} field value
> > > > > +supplied with the request does not identify a clock.
> > > > > +
> > > > > +VIRTIO_RTC_S_EINVAL indicates that
> > > > 
> > > > either? or both?
> > > 
> > > Can be either or both (inclusive "or"). I will state this more explicitly.
> > > 
> > > > 
> > > > > +
> > > > > +\begin{itemize}
> > > > > +\item the driver request values are not allowed by the specification or
> > > > 
> > > > how do you mean? not recognized by the device? what do you expect
> > > > driver to do? assert basically? no well behaved driver will
> > > > encounter it right?
> > > 
> > > This would indicate a bug in the driver or device. A well-behaved driver
> > > should not get any error from the device, ever.
> > 
> > worth clarifying
> 
> OK.
> 
> > 
> > > For a Linux kernel driver, I am not sure if the driver should stop using
> > > the device immediately, though.
> > > 
> > > > 
> > > > 
> > > > 
> > > > 
> > > > > +\item the device read-only part of the message, or the device write-only
> > > > > +        part of the message, is too small to fit the actual message.
> > > > 
> > > > what is the actual message? do you mean the read-only part is too
> > > > small to fit the request or the write-only part is too small to
> > > > fit the response?
> > > 
> > > Yes. I will rephrase this.
> > > 
> > > > 
> > > > 
> > > > > +\end{itemize}
> > > > > +
> > > > > +VIRTIO_RTC_S_EIO indicates that the device did not execute the request
> > > > > +due to an error which was not caused by invalid input from the driver.
> > > > > +
> > > > > +All \field{reserved} fields are written as zero, and their value is
> > > > > +ignored.
> > > > > +
> > > > > +The set of clocks does not change after feature negotiation completion,
> > > > > +until device reset. The set of clocks should not change on device reset
> > > > > +either (similar to negotiated features). Clock identifiers are
> > > > > +zero-based, dense indices. All fields
> > > > 
> > > > in which structure? within request structures?
> > > 
> > > Within request structures, and within the notification structure added
> > > in patch 3. I will mention this.
> > > 
> > > > 
> > > > > named \field{clock_id} contain
> > > > > +clock identifiers.
> > > > > +
> > > > > +\subsubsection{Common Definitions}\label{sec:Device Types / RTC Device / Device Operation / Common Definitions}
> > > > > +
> > > > > +This section makes common definitions.
> > > > > +
> > > > > +\paragraph{Clock Types}\label{sec:Device Types / RTC Device / Device Operation / Common Definitions / Clock Types}
> > > > > +
> > > > > +The following clock types are defined:
> > > > > +
> > > > > +\begin{lstlisting}
> > > > > +#define VIRTIO_RTC_CLOCK_UTC                    0
> > > > > +#define VIRTIO_RTC_CLOCK_TAI                    1
> > > > > +#define VIRTIO_RTC_CLOCK_MONOTONIC              2
> > > > > +#define VIRTIO_RTC_CLOCK_UTC_SMEARED            3
> > > > > +#define VIRTIO_RTC_CLOCK_UTC_MAYBE_SMEARED      4
> > > > > +\end{lstlisting}
> > > > > +
> > > > > +\begin{description}
> > > > > +
> > > > > +\item[VIRTIO_RTC_CLOCK_UTC] uses the UTC (Coordinated Universal Time)
> > > > > +        time standard. This clock uses the time epoch of January 1,
> > > > > +        1970, 00:00 UTC. This is the same epoch as \emph{Unix time}. The
> > > > > +        clock's seconds since the epoch are related to UTC time as
> > > > > +        defined by \hyperref[intro:EPOCH]{EPOCH}.
> > > > > +
> > > > > +        This clock observes positive and negative leap seconds as
> > > > > +        announced by standard bodies. At the start of leap seconds, the
> > > > > +        clock steps accordingly.
> > > > > +
> > > > > +\item[VIRTIO_RTC_CLOCK_TAI] uses the TAI (International Atomic Time)
> > > > > +        time standard. This clock uses the time epoch of January 1,
> > > > > +        1970, 00:00 TAI.
> > > > > +
> > > > > +\item[VIRTIO_RTC_CLOCK_MONOTONIC] uses monotonic physical time (SI
> > > > > +        seconds subdivisions) since some unspecified epoch. The epoch is
> > > > > +        before or during device reset.
> > > > > +
> > > > > +\item[VIRTIO_RTC_CLOCK_UTC_SMEARED] deviates from the UTC standard by
> > > > > +        smearing time in the vicinity of a leap second. This avoids
> > > > > +        clock steps due to UTC leap seconds. Otherwise, this clock is
> > > > > +        similar to VIRTIO_RTC_CLOCK_UTC.
> > > > > +
> > > > > +\item[VIRTIO_RTC_CLOCK_UTC_MAYBE_SMEARED] This clock
> > > > > +
> > > > > +\begin{itemize}
> > > > > +\item may deviate from the UTC standard by smearing time in the vicinity
> > > > > +        of a leap second (similar to VIRTIO_RTC_CLOCK_UTC_SMEARED), or
> > > > > +
> > > > > +\item may step at the start of leap seconds like VIRTIO_RTC_CLOCK_UTC.
> > > > > +\end{itemize}
> > > > > +
> > > > > +A clock of type VIRTIO_RTC_CLOCK_UTC_MAYBE_SMEARED can change this
> > > > > +behavior for every leap second.
> > > > > +
> > > > > +\end{description}
> > > > > +
> > > > > +In the following, \emph{UTC-like clock} designates any clock of type
> > > > > +VIRTIO_RTC_CLOCK_UTC, VIRTIO_RTC_CLOCK_UTC_SMEARED, or
> > > > > +VIRTIO_RTC_CLOCK_UTC_MAYBE_SMEARED.
> > > > > +
> > > > > +Additional clock types may be standardized in the future.
> > > > > +Implementation-specific definitions of clock types are not recommended.
> > > > > +Implementation-specific definitions use ids between 0xF0 and 0xFF.
> > > > > +
> > > > > +\paragraph{Smearing Variants}\label{sec:Device Types / RTC Device / Device Operation / Common Definitions / Smearing Variants}
> > > > > +
> > > > > +Leap second \emph{smearing variants} describe the deviation from the UTC
> > > > > +standard in the vicinity of a leap second. The following smearing
> > > > > +variants are currently defined:
> > > > > +
> > > > > +\begin{lstlisting}
> > > > > +#define VIRTIO_RTC_SMEAR_UNSPECIFIED    0
> > > > > +#define VIRTIO_RTC_SMEAR_NOON_LINEAR    1
> > > > > +#define VIRTIO_RTC_SMEAR_UTC_SLS        2
> > > > > +\end{lstlisting}
> > > > > +
> > > > > +\begin{description}
> > > > > +
> > > > > +        \item[VIRTIO_RTC_SMEAR_UNSPECIFIED] means that it is unspecified
> > > > > +                how time is smeared in the vicinity of leap seconds.
> > > > > +
> > > > > +        \item[VIRTIO_RTC_SMEAR_NOON_LINEAR] specifies a linear smear
> > > > > +                from noon prior to the leap second until noon after the
> > > > > +                leap second.
> > > > > +
> > > > > +        \item[VIRTIO_RTC_SMEAR_UTC_SLS] specifies a linear smear as per
> > > > > +                the \hyperref[intro:UTC-SLS]{UTC-SLS} proposal.
> > > > > +
> > > > > +\end{description}
> > > > > +
> > > > > +Clocks of type VIRTIO_RTC_CLOCK_UTC_SMEARED always behave according to a
> > > > > +smearing variant. The smearing variant does not change over the clock's
> > > > > +lifetime.
> > > > > +
> > > > > +For clocks of type VIRTIO_RTC_CLOCK_UTC_MAYBE_SMEARED, it is unspecified
> > > > > +whether leap seconds are smeared, and how leap seconds are smeared.
> > > > > +
> > > > > +Additional smearing variants may be standardized in the future.
> > > > > +Implementation-specific definitions of smearing variants are not
> > > > > +recommended. Implementation-specific definitions use ids greater than or
> > > > > +equal to 0xF0.
> > > > > +
> > > > > +In the following, \emph{leap smearing clock} designates
> > > > 
> > > > here, and elsewhere, it's confusing whether itemization is for either
> > > > or both.
> > > 
> > > I will rephrase.
> > > 
> > > > 
> > > > > +\begin{itemize}
> > > > > +
> > > > > +\item any clock of type VIRTIO_RTC_CLOCK_UTC_SMEARED
> > > > > +
> > > > > +\item any clock of type VIRTIO_RTC_CLOCK_UTC_MAYBE_SMEARED at any time
> > > > > +        when the clock is smearing a leap second.
> > > > > +
> > > > > +\end{itemize}
> > > > > +
> > > > > +\paragraph{Hardware Counters}\label{sec:Device Types / RTC Device / Device Operation / Common Definitions / Hardware Counters}
> > > > > +
> > > > > +The following hardware counter identifiers are specified:
> > > > > +
> > > > > +\begin{lstlisting}
> > > > > +/* Arm Generic Timer Counter-timer Virtual Count Register (CNTVCT_EL0) */
> > > > > +#define VIRTIO_RTC_COUNTER_ARM_VCT      0
> > > > > +/* x86 Time-Stamp Counter */
> > > > > +#define VIRTIO_RTC_COUNTER_X86_TSC      1
> > > > > +/* Invalid */
> > > > > +#define VIRTIO_RTC_COUNTER_INVALID   0xFF
> > > > > +\end{lstlisting}
> > > > > +
> > > > > +Additional hardware counter identifiers may be standardized in the
> > > > > +future. Implementation-specific hardware counter identifiers are not
> > > > > +recommended. Implementation-specific hardware counter identifiers have
> > > > > +values between 0xF0 and 0xFE.
> > > > 
> > > > Maybe something like "and are reserved for experimental implementations".
> > > 
> > > OK.
> > > 
> > > > 
> > > > 
> > > > > +
> > > > > +\subsubsection{Control Requests}\label{sec:Device Types / RTC Device / Device Operation / Control Requests}
> > > > > +
> > > > > +Through \emph{control requests}, the driver requests information about
> > > > > +the device capabilities. The driver enqueues control requests in the
> > > > > +requestq.
> > > > > +
> > > > > +\begin{description}
> > > > > +
> > > > > +\item[VIRTIO_RTC_REQ_CFG] discovers the number of clocks.
> > > > > +
> > > > > +\begin{lstlisting}
> > > > > +#define VIRTIO_RTC_REQ_CFG 0x1000 /* message type */
> > > > > +
> > > > > +struct virtio_rtc_req_cfg {
> > > > > +        struct virtio_rtc_req_head head;
> > > > > +        /* no request params */
> > > > > +};
> > > > > +
> > > > > +struct virtio_rtc_resp_cfg {
> > > > > +        struct virtio_rtc_resp_head head;
> > > > > +        le16 num_clocks;
> > > > > +        u8 reserved[6];
> > > > > +};
> > > > > +\end{lstlisting}
> > > > > +
> > > > > +Field \field{num_clocks} contains the number of clocks. A device
> > > > > +provides zero or more clocks. Valid clock ids are those smaller than
> > > > > +\field{num_clocks}.
> > > > > +
> > > > > +\item[VIRTIO_RTC_REQ_CLOCK_CAP] discovers the capabilities of the clock
> > > > > +identified by the \field{clock_id} field.
> > > > > +
> > > > > +\begin{lstlisting}
> > > > > +#define VIRTIO_RTC_REQ_CLOCK_CAP 0x1001 /* message type */
> > > > > +
> > > > > +struct virtio_rtc_req_clock_cap {
> > > > > +        struct virtio_rtc_req_head head;
> > > > > +        le16 clock_id;
> > > > > +        u8 reserved[6];
> > > > > +};
> > > > > +
> > > > > +struct virtio_rtc_resp_clock_cap {
> > > > > +        struct virtio_rtc_resp_head head;
> > > > > +        u8 type;
> > > > > +        u8 leap_second_smearing;
> > > > > +        u8 reserved[6];
> > > > > +};
> > > > > +\end{lstlisting}
> > > > > +
> > > > > +The \field{type} field identifies the clock type. A device provides
> > > > > +zero or more clocks for a clock type.
> > > > > +
> > > > > +Clocks of type VIRTIO_RTC_CLOCK_UTC_SMEARED indicate the \emph{smearing
> > > > > +variant} through field \field{leap_second_smearing}. All other clocks
> > > > > +set \field{leap_second_smearing} to VIRTIO_RTC_SMEAR_UNSPECIFIED.
> > > > > +
> > > > > +\item[VIRTIO_RTC_REQ_CROSS_CAP] discovers whether the device supports
> > > > > +cross-timestamping for a particular pair of clock and hardware counter.
> > > > > +
> > > > > +\begin{lstlisting}
> > > > > +#define VIRTIO_RTC_REQ_CROSS_CAP 0x1002 /* message type */
> > > > > +
> > > > > +struct virtio_rtc_req_cross_cap {
> > > > > +        struct virtio_rtc_req_head head;
> > > > > +        le16 clock_id;
> > > > > +        u8 hw_counter;
> > > > > +        u8 reserved[5];
> > > > > +};
> > > > > +
> > > > > +
> > > > > +struct virtio_rtc_resp_cross_cap {
> > > > > +        struct virtio_rtc_resp_head head;
> > > > > +#define VIRTIO_RTC_FLAG_CROSS_CAP       (1 << 0)
> > > > > +        u8 flags;
> > > > > +        u8 reserved[7];
> > > > > +};
> > > > > +\end{lstlisting}
> > > > > +
> > > > > +The \field{clock_id} field identifies the clock, and the
> > > > > +\field{hw_counter} field identifies the hardware counter, for which
> > > > > +cross-timestamp support is probed. The device sets the
> > > > > +VIRTIO_RTC_FLAG_CROSS_CAP flag in the \field{flags} field if the clock
> > > > > +supports cross-timestamping for the particular clock and hardware
> > > > > +counter, and clears the flag otherwise.
> > > > > +
> > > > > +\end{description}
> > > > > +
> > > > > +\subsubsection{Read Requests}\label{sec:Device Types / RTC Device / Device Operation / Read Requests}
> > > > > +
> > > > > +Through \emph{read requests}, the driver requests clock readings from
> > > > > +the device. The driver enqueues read requests in the requestq. The
> > > > > +device obtains device-side clock readings and forwards these clock
> > > > > +readings to the driver. The driver may enhance and interpret the clock
> > > > > +readings through methods which are beyond the scope of this
> > > > > +specification.
> > > > > +
> > > > > +Once DRIVER_OK has been set, the device should support reading every
> > > > > +clock, even when a clock may yet have to be aligned to reference time
> > > > > +sources.
> > > > > +
> > > > > +In general,
> > > > > +
> > > > > +\begin{itemize}
> > > > > +\item clocks may jump backwards or forward, and
> > > > > +\item the clock frequency may change. Clocks may be \emph{slewed},
> > > > > +        i.e.\ clocks may run at a frequency other than their current
> > > > > +        best frequency estimate.
> > > > > +\end{itemize}
> > > > > +
> > > > > +As long as a clock does not jump backwards, the driver clock readings
> > > > > +through read request responses increase monotonically:
> > > > > +
> > > > > +\begin{itemize}
> > > > > +\item As long as a clock does not jump backwards in-between device-side
> > > > > +        clock readings, the driver-side readings for that clock increase
> > > > > +        monotonically as well, in the order in which the driver
> > > > > +        marks read requests as available.
> > > > > +
> > > > > +\item The device marks read requests for the same clock as used in
> > > > > +        the order in which the messages were marked as available.
> > > > 
> > > > buffers are available
> > > 
> > > s/messages were marked as available/buffers are available/ ?
> > 
> > yes
> > also used
> > 
> 
> OK.
> 
> Thanks for the reply,
> 
> Peter

Re: [PATCH v8 3/4] virtio-rtc: Add alarm feature

[Peter Hilber]

On Thu, Apr 17, 2025 at 05:05:00PM +0200, Peter Hilber wrote:
> On Wed, Apr 16, 2025 at 10:17:33AM +0200, Matias Ezequiel Vara Larsen wrote:
> > On Thu, Mar 06, 2025 at 10:51:11AM +0100, Peter Hilber wrote:
> > > Add the VIRTIO_RTC_F_ALARM feature (without normative statements).
> > > 
> > > The intended use case is: A driver needs to react when an alarm time has
> > > been reached, but at alarm time, the driver may be in a sleep state or
> > > powered off. The alarm feature can resume and notify the driver in this
> > > case. Alarms may be retained across device resets (including reset on
> > > boot).
> > > 
> > > Peculiarities
> > > -------------
> > > 
> > > Unlike usual alarm clocks, a virtio-rtc alarm-capable clock may step
> > > autonomously at any time: An alarm may change back from "expired" to
> > > "not expired" before the driver has started processing an alarm
> > > notification.
> > > 
> > > To address the above, and the device resets, define "alarm expiration"
> > > in such a way that the driver always has a chance to react to an alarm,
> > > and make the device always responsible for notifying the driver about an
> > > alarm expiration.
> > > 
> > > The VIRTIO_RTC_REQ_SET_ALARM_ENABLED request is there so that the Linux
> > > ioctls RTC_AIE_ON and RTC_AIE_OFF only need to emit one request.
> > > 
> > > Signed-off-by: Peter Hilber <quic_philber@quicinc.com>
> > > ---
> > > 

[...]

> > > +An alarm \emph{expiration} becomes obsolete
> > > +
> > > +\begin{itemize}
> > > +\item when the driver disables the alarm, or
> > > +
> > > +\item when the driver sets an alarm time, or
> > > +
> > > +\item when the clock jumps backwards, before the alarm time, or
> > > +
> > > +\item when another alarm expiration event happens.
> > > +\end{itemize}
> > > +
> > > +If an alarm expiration becomes obsolete, it is unspecified which alarm
> > > +actions the device executes for this alarm expiration, and the device
> > > +stops executing these alarm actions after a grace period.
> > 
> > Can't you leave this paragraph implementation-specific and thus
> > removing it completely?
> 
> OK.

It seems complicated to me. If the device does not stop alarm actions
when the driver disables the alarm, it becomes impossible to reliably
clear the device state ("start with a clean slate", as per the
discussion in [2]). For this, v8 has the requirement

	If the driver successfully requests VIRTIO_RTC_REQ_SET_ALARM, or
	VIRTIO_RTC_REQ_SET_ALARM_ENABLED, for clock C, the device MUST
	stop serving any previous alarm expiration event for C before
	the device marks the message as used.

This is the only hard requirement which restricts a v8 implementation,
every other alarm action could still be done within an indefinite "grace
period".

I think the "grace period" related requirements should be dropped, so
that the behavior is essentially implementation-specific apart from
stopping the alarm action when the driver disables the alarm. Maybe I
can change the last paragraph cited from the patch like the following:

	If an alarm expiration becomes obsolete, it is unspecified which
	alarm actions the device executes for this alarm expiration.
	When the driver disables an alarm, the device stops any alarm
	action for this alarm before using the buffer.

Best regards,

Peter

[2] https://lore.kernel.org/virtio-comment/a284ed4f-9ca1-4b8a-8c79-beec5040bd6b@opensynergy.com/