Skip to contentSkip to conversation

virtio-rtc: Add device specification

RFC PATCH In review Peter Hilber 2 participants 34 messages May 22, 2024 – Aug 9, 2024 PTP vmclock support

lore
Share & tools
lore
#0 lore raw

v4 cover virtio-rtc: Add device specification

This iteration of the virtio-rtc RFC spec adds leap second indication and performance indication. It also incorporates the results of previous discussions.

While the virtio-comment mailing list was unavailable, a discussion about leap second indication and performance indication took place on the Linux kernel mailing list [1]. As an outcome of this discussion [1], the RFC spec v4 now adds leap second indication and performance indication. The respective changes are for now gathered in patch 5.

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 also indicates when and 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
---------

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/[email protected]/

Peter Hilber (5):
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
virtio-rtc: Indicate leap seconds and clock performance

 conformance.tex                         |    2 +
 content.tex                             |    3 +-
 device-types/rtc/description.tex        | 1236 +++++++++++++++++++++++
 device-types/rtc/device-conformance.tex |   13 +
 device-types/rtc/driver-conformance.tex |   11 +
 5 files changed, 1264 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: 37c6a406678a5ee891fdf5671298cb4fcfa517f2

Signature · 1 line
2.43.0
#1 lore raw

RFC PATCH v4 1/5 virtio-rtc: Add initial device specification

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.

---

Notes:
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/[email protected]/t/#mffb93800fea11d6dda9e151078abedd6ff1c0f1e
[3] https://lore.kernel.org/virtio-comment/[email protected]/t/#m94efd0aa9b9c2b96a246b79ef8bfc3bf64ebe791
[4] https://lore.kernel.org/lkml/[email protected]/T/#m65fa1d715933360498c4e33d7225e4220215a9d6
[5] https://lore.kernel.org/virtio-comment/[email protected]/t/#mf00ce330228c28556d735eb9597469048c5d8b62
[6] https://lore.kernel.org/lkml/[email protected]/
[7] https://lore.kernel.org/all/[email protected]/

 content.tex                      |   3 +-
 device-types/rtc/description.tex | 328 +++++++++++++++++++++++++++++++
 2 files changed, 330 insertions(+), 1 deletion(-)
 create mode 100644 device-types/rtc/description.tex
content.tex +2 -1
index d7d544eefa06..9e60f8f94c64 100644
@@ -683,7 +683,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
@@ -773,6 +773,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}
 
device-types/rtc/description.tex new file +328 -0

328 lines not on this page · raw message

Signature · 1 line
2.43.0
#2 lore raw

RFC PATCH v4 2/5 virtio-rtc: Add initial normative statements

In reply to Peter Hilber

Add the normative statements for the initial device specification.

---

Notes:
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        | 214 ++++++++++++++++++++++++
 device-types/rtc/device-conformance.tex |   9 +
 device-types/rtc/driver-conformance.tex |   9 +
 4 files changed, 234 insertions(+)
 create mode 100644 device-types/rtc/device-conformance.tex
 create mode 100644 device-types/rtc/driver-conformance.tex
conformance.tex +2 -0
index 183c05944d1d..899e0fe67544 100644
@@ -159,6 +159,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}
 
@@ -248,6 +249,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
device-types/rtc/description.tex +214 -0

229 lines not on this page · raw message

device-types/rtc/device-conformance.tex new file +9 -0
new file mode 100644
index 000000000000..4303cd450542
@@ -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}
device-types/rtc/driver-conformance.tex new file +9 -0
new file mode 100644
index 000000000000..689c18d158d0
@@ -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}
Signature · 1 line
2.43.0
#3 lore raw

RFC PATCH v4 3/5 virtio-rtc: Add alarm feature

In reply to 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 the driver may be in a sleep state or powered off at alarm time. 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.

---

Notes:
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/[email protected]/

 device-types/rtc/description.tex | 270 ++++++++++++++++++++++++++++++-
 1 file changed, 268 insertions(+), 2 deletions(-)
device-types/rtc/description.tex +268 -2
index 28c1517f3543..8a51a70d615b 100644
@@ -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}
 
@@ -247,7 +258,8 @@ \subsubsection{Control Requests}\label{sec:Device Types / RTC Device / Device Op
 struct virtio_rtc_resp_clock_cap {
 	struct virtio_rtc_resp_head head;
 	le16 type;
-	u8 reserved[6];
+	u8 flags;
+	u8 reserved[5];
 };
 \end{lstlisting}
 
@@ -277,6 +289,15 @@ \subsubsection{Control Requests}\label{sec:Device Types / RTC Device / Device Op
 Implementation-specific clock type definitions are not recommended and
 use a clock type id greater than or equal to 0xF000.
 
+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, flag VIRTIO_RTC_FLAG_ALARM_CAP
+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.
 
@@ -540,3 +561,248 @@ \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
 field \field{clock_reading}.
+
+\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, or
+
+\item when the driver sets an alarm time which is not in the future, or
+
+\item when the device is reset, if the alarm time is retained and not in
+	the future.\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 expiration becomes obsolete
+
+\begin{itemize}
+\item once the clock jumps backwards, before the alarm time, or
+
+\item once the driver sets an alarm time, or
+
+\item once 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 driver-visible settings of an alarm consist of two elements:
+
+\begin{itemize}
+\item \field{driver_alarm_time}, a valid time for the corresponding
+	clock, and
+
+\item \field{alarm_enabled}, a boolean. While \field{alarm_enabled} is
+	true, \field{driver_alarm_time} is the actual alarm time.
+	While \field{alarm_enabled} is false, the device will act as if
+	the alarm time was in the future, so that the alarm will not
+	expire.
+\end{itemize}
+
+The device supports all \field{driver_alarm_time} values which the
+driver can request through alarm control requests.
+
+Initially, \field{driver_alarm_time} is the epoch of the clock ($0$),
+and \field{alarm_enabled} is false.
+
+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.
+Field \field{alarm_time} returns \field{driver_alarm_time}. In field
+\field{flags}, flag VIRTIO_RTC_FLAG_ALARM_ENABLED indicates whether
+\field{alarm_enabled} is true.
+
+\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.
+Field \field{alarm_time} sets \field{driver_alarm_time}. If flag
+VIRTIO_RTC_FLAG_ALARM_ENABLED is set in field \field{flags}, the device
+sets \field{alarm_enabled} to true; otherwise, the device sets
+\field{alarm_enabled} to false.
+
+\item[VIRTIO_RTC_REQ_SET_ALARM_ENABLED] sets \field{alarm_enabled}.
+
+\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
+flag VIRTIO_RTC_FLAG_ALARM_ENABLED is set in field \field{flags}, the
+device sets \field{alarm_enabled} to true; otherwise, the device sets
+\field{alarm_enabled} to false.
+
+When processing this request, the device retains
+\field{driver_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.
Signature · 1 line
2.43.0
#4 lore raw

RFC PATCH v4 4/5 virtio-rtc: Add normative statements for alarm feature

In reply to Peter Hilber

Add the normative statements for the alarm feature added previously.

---

Notes:
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        | 157 ++++++++++++++++++++++++
 device-types/rtc/device-conformance.tex |   4 +
 device-types/rtc/driver-conformance.tex |   2 +
 3 files changed, 163 insertions(+)
device-types/rtc/description.tex +157 -0
index 8a51a70d615b..8fbeef33fac9 100644
@@ -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.
@@ -562,6 +567,12 @@ \subsubsection{Read Requests}\label{sec:Device Types / RTC Device / Device Opera
 this specification, the device MUST use the nanosecond as unit for
 field \field{clock_reading}.
 
+If VIRTIO_RTC_F_ALARM was negotiated, and the device sent an alarm
+notification N for clock C with alarm time A, the device MUST, for all
+read requests of C which the driver marks as available after the device
+marked N as used, return a \field{clock_reading} which does not precede
+A, unless 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
@@ -675,6 +686,79 @@ \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 \field{driver_alarm_time} and
+\field{alarm_enabled} of a clock across a device reset.
+
+If the device did not retain \field{driver_alarm_time} and
+\field{alarm_enabled} of a clock across a device reset, the device MUST
+initialize \field{driver_alarm_time} to 0.
+
+If the device did not retain \field{driver_alarm_time} and
+\field{alarm_enabled} of a clock across a device reset, the device MUST
+initialize \field{alarm_enabled} to false.
+
+While \field{alarm_enabled} for a clock is true, the device MUST set the
+alarm time to \field{driver_alarm_time}.
+
+While \field{alarm_enabled} for a clock is false, the device MUST act as
+if the alarm time was in the future.
+
+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 flag VIRTIO_RTC_FLAG_ALARM_CAP 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.
+
+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.
+
+If the device retained \field{driver_alarm_time} and
+\field{alarm_enabled} 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 an alarm expiration event E happens, the device MUST start serving
+the alarm expiration event E.
+
+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.
+
+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.
+
 \paragraph{Alarm Control Requests}
 
 If VIRTIO_RTC_F_ALARM is negotiated,
@@ -771,6 +855,62 @@ \subsubsection{Alarm Operation}\label{sec:Device Types / RTC Device / Device Ope
 \field{driver_alarm_time}.
 \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 field
+\field{alarm_time} to \field{driver_alarm_time}.
+
+For VIRTIO_RTC_REQ_READ_ALARM, the device MUST set flag
+VIRTIO_RTC_FLAG_ALARM_ENABLED in field \field{flags} if
+\field{alarm_enabled} is true, 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 \field{driver_alarm_time} to the time
+represented by field \field{alarm_time}.
+
+If the device sets status VIRTIO_RTC_S_OK for VIRTIO_RTC_REQ_SET_ALARM,
+the device MUST set \field{alarm_enabled} to true if flag
+VIRTIO_RTC_FLAG_ALARM_ENABLED is set in field \field{flags}.
+
+If the device sets status VIRTIO_RTC_S_OK for VIRTIO_RTC_REQ_SET_ALARM,
+the device MUST set \field{alarm_enabled} to false if flag
+VIRTIO_RTC_FLAG_ALARM_ENABLED is cleared in field \field{flags}.
+
+If the device sets status VIRTIO_RTC_S_OK for
+VIRTIO_RTC_REQ_SET_ALARM_ENABLED, the device MUST set
+\field{alarm_enabled} to true if flag VIRTIO_RTC_FLAG_ALARM_ENABLED is
+set in field \field{flags}.
+
+If the device sets status VIRTIO_RTC_S_OK for
+VIRTIO_RTC_REQ_SET_ALARM_ENABLED, the device MUST set
+\field{alarm_enabled} to false if flag VIRTIO_RTC_FLAG_ALARM_ENABLED is
+cleared in field \field{flags}.
+
+If the device sets status VIRTIO_RTC_S_OK for
+VIRTIO_RTC_REQ_SET_ALARM_ENABLED, the device MUST retain
+\field{driver_alarm_time}.
+
 \paragraph{Alarm Notifications}
 
 If the alarmq is present, the driver should make buffers available in
@@ -806,3 +946,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.
device-types/rtc/device-conformance.tex +4 -0
index 4303cd450542..705691a7319f 100644
@@ -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}
device-types/rtc/driver-conformance.tex +2 -0
index 689c18d158d0..a87c4cde99c2 100644
@@ -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}
Signature · 1 line
2.43.0
#5 lore raw

RFC PATCH v4 5/5 virtio-rtc: Indicate leap seconds and clock performance

In reply to Peter Hilber

This adds the following capabilities:

1) Distinguish UTC clocks from UTC-like clocks with leap smearing.

2) UTC leap second and TAI offset indication for cross-timestamps.

3) Clock performance information for cross-timestamps.

This is a backwards incompatible change and as such only presented in a separate patch for now to ease reviewing.

These additions are an outcome of a Linux kernel mailing list discussion [1], which took place while the virtio-comment mailing list was unavailable.

As per [2], UTC leap seconds may be abolished in the medium-term future. The spec does not address this explicitly and drivers which care about it are assumed to know after which date no more leap seconds can be expected.

Normative requirements for 2) and 3) still need to be added.

[1] https://lore.kernel.org/lkml/[email protected]/
[2] https://www.bipm.org/en/cgpm-2022/resolution-4

---

Notes:
v4:

- Distinguish UTC clocks with and without leap smearing (David Woodhouse) [3].

- Add UTC leap second and TAI offset indication (David Woodhouse) [3].

- Add clock performance information (David Woodhouse) [3].

[3] https://lore.kernel.org/lkml/[email protected]/

 device-types/rtc/description.tex | 301 +++++++++++++++++++++++++++++--
 1 file changed, 286 insertions(+), 15 deletions(-)
device-types/rtc/description.tex +286 -15
index 8fbeef33fac9..6fb19f9db022 100644
@@ -263,8 +263,9 @@ \subsubsection{Control Requests}\label{sec:Device Types / RTC Device / Device Op
 struct virtio_rtc_resp_clock_cap {
 	struct virtio_rtc_resp_head head;
 	le16 type;
+	le16 subtype;
 	u8 flags;
-	u8 reserved[5];
+	u8 reserved[3];
 };
 \end{lstlisting}
 
@@ -279,8 +280,10 @@ \subsubsection{Control Requests}\label{sec:Device Types / RTC Device / Device Op
 \end{lstlisting}
 
 VIRTIO_RTC_CLOCK_UTC uses the UTC (Coordinated Universal Time) time
-standard. The device uses the time epoch of January 1, 1970, 00:00
-UTC. This is the same epoch as \emph{Unix time}.
+standard. The device uses the time epoch of January 1, 1970, 00:00 UTC.
+This is the same epoch as \emph{Unix time}. For VIRTIO_RTC_CLOCK_UTC,
+the clock \emph{subtype} specifies whether the clock fully adheres to
+the UTC standard w.r.t.\ leap seconds.
 
 VIRTIO_RTC_CLOCK_TAI uses the TAI (International Atomic Time) time
 standard. The device uses the time epoch of January 1, 1970, 00:00
@@ -290,9 +293,62 @@ \subsubsection{Control Requests}\label{sec:Device Types / RTC Device / Device Op
 subdivisions) since some unspecified epoch. The VIRTIO_RTC_CLOCK_MONO
 epoch is before or during device reset.
 
-Additional clock types may be standardized in the future.
-Implementation-specific clock type definitions are not recommended and
-use a clock type id greater than or equal to 0xF000.
+The \field{subtype} field identifies the clock subtype. The clock
+subtype provides additional information about the clock behavior. The
+following clock subtypes are defined:
+
+\begin{lstlisting}
+#define VIRTIO_RTC_SUBTYPE_STRICT 0
+#define VIRTIO_RTC_SUBTYPE_SMEAR 1
+#define VIRTIO_RTC_SUBTYPE_SMEAR_NOON_LINEAR 2
+#define VIRTIO_RTC_SUBTYPE_LEAP_UNSPECIFIED 3
+\end{lstlisting}
+
+VIRTIO_RTC_SUBTYPE_STRICT means that the clock fully adheres to the
+clock type's time standard (or to the clock type's time scale, if the
+clock type does not refer to a time standard). This is the only subtype
+for clocks which are not of type VIRTIO_RTC_CLOCK_UTC.
+
+For clocks of type VIRTIO_RTC_CLOCK_UTC, VIRTIO_RTC_SUBTYPE_STRICT
+means:
+
+\begin{itemize}
+\item The clock fully adheres to the UTC standard.
+
+\item The clock will observe positive and negative leap seconds as
+	announced by standard bodies.
+
+\item At the start of leap seconds, the clock steps accordingly.
+\end{itemize}
+
+For clocks of type VIRTIO_RTC_CLOCK_UTC, the following additional
+subtypes are also defined:
+
+\begin{itemize}
+\item VIRTIO_RTC_SUBTYPE_SMEAR deviates from the UTC standard by
+	smearing time in the vicinity of the leap second, in a not
+	precisely defined manner. This avoids clock steps due to UTC
+	leap seconds.
+
+\item VIRTIO_RTC_SUBTYPE_SMEAR_NOON_LINEAR is similar to
+	VIRTIO_RTC_SUBTYPE_SMEAR, except that the smear is precisely
+	defined as a linear smear from noon prior to the leap second
+	until noon after the leap second.
+
+\item VIRTIO_RTC_SUBTYPE_LEAP_UNSPECIFIED may deviate from the UTC
+	standard w.r.t.\ leap second introduction in an unspecified way
+	(leap seconds may, or may not, be smeared).
+\end{itemize}
+
+In the following, \emph{leap smearing clock} designates any clock of
+subtype VIRTIO_RTC_SUBTYPE_SMEAR, or
+VIRTIO_RTC_SUBTYPE_SMEAR_NOON_LINEAR.
+
+Additional clock types, and clock subtypes, may be standardized in the
+future.
+
+Implementation-specific definitions of clock type, and clock subtype,
+are not recommended and use ids greater than or equal to 0xF000.
 
 The \field{flags} field provides the following information:
 
@@ -343,11 +399,52 @@ \subsubsection{Control Requests}\label{sec:Device Types / RTC Device / Device Op
 \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).
+time standard (Coordinated Universal Time), except as per the following
+requirements.
 
 For any clock of type VIRTIO_RTC_CLOCK_UTC, the device MUST use the time
 epoch of January 1, 1970, 00:00 UTC.
 
+For any clock of type VIRTIO_RTC_CLOCK_UTC and subtype
+VIRTIO_RTC_SUBTYPE_STRICT, 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 and subtype
+VIRTIO_RTC_SUBTYPE_STRICT, 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 of type VIRTIO_RTC_SUBTYPE_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 of type VIRTIO_RTC_SUBTYPE_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 of type VIRTIO_RTC_SUBTYPE_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 leap smearing clock, the clock MUST correspond to UTC again at
+the latest at the end of the day after the leap second.
+
+For any clock of type VIRTIO_RTC_SUBTYPE_LEAP_UNSPECIFIED, 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).
 
@@ -364,12 +461,172 @@ \subsubsection{Control Requests}\label{sec:Device Types / RTC Device / Device Op
 one of the clock types defined in this specification, or to a value
 greater than or equal to 0xF000.
 
+For VIRTIO_RTC_REQ_CLOCK_CAP, the device MUST set \field{subtype} to one
+of the clock subtypes defined in this specification, or to a value
+greater than or equal to 0xF000.
+
+For VIRTIO_RTC_REQ_CLOCK_CAP, and clock types other than
+VIRTIO_RTC_CLOCK_UTC, the device MUST set \field{subtype} to
+VIRTIO_RTC_SUBTYPE_STRICT.
+
 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{Data Structures}
+
+This section describes reusable data structures.
+
+\paragraph{UTC Specific Data}\label{sec:Device Types / RTC Device / Device Operation / Data Structures / UTC Specific Data}
+
+For clocks of type VIRTIO_RTC_CLOCK_UTC, the device reports information
+about impending and ongoing UTC leap seconds, and about the current UTC
+offset from TAI, through \field{struct virtio_rtc_data_utc}. This
+information applies to the clock reading to which the struct is
+associated to.
+
+\begin{lstlisting}
+struct virtio_rtc_data_utc {
+	le64 tai_offset;
+#define VIRTIO_RTC_LEAP_NONE 0
+#define VIRTIO_RTC_LEAP_PRE_POS 1
+#define VIRTIO_RTC_LEAP_PRE_NEG 2
+#define VIRTIO_RTC_LEAP_POS 3
+#define VIRTIO_RTC_LEAP_NEG 4
+	u8 leap;
+#define VIRTIO_RTC_FLAG_SMEAR (1 << 0)
+#define VIRTIO_RTC_FLAG_TAI_OFFSET (1 << 1)
+	u8 flags;
+	u8 reserved[6];
+};
+\end{lstlisting}
+
+\subparagraph{Leap Second Indication}
+
+For subtype VIRTIO_RTC_SUBTYPE_STRICT, the \field{struct
+virtio_rtc_data_utc.leap} field indicates whether a positive or negative
+leap second will be introduced at the end of the month resp.\ whether a
+leap second is currently in progress.
+
+For a leap smearing clock, the \field{leap} field indicates whether a
+leap smear will start around the next turn of the month resp.\ whether
+the leap second is currently being smeared into the clock.
+
+VIRTIO_RTC_LEAP_NONE indicates that the clock is currently not
+performing leap second related processing, and also not pre-announcing
+an impending leap second.
+
+VIRTIO_RTC_LEAP_PRE_POS resp.\ VIRTIO_RTC_LEAP_PRE_NEG pre-announce a
+positive resp.\ negative leap second. Pre-announcing starts at the
+earliest at the 17th day of the month including the leap second.
+
+For VIRTIO_RTC_SUBTYPE_STRICT, VIRTIO_RTC_LEAP_POS indicates that a
+positive leap second is in progress.
+
+For a leap smearing clock, VIRTIO_RTC_LEAP_PRE_POS resp.\
+VIRTIO_RTC_LEAP_PRE_NEG indicate that the clock is currently slowed down
+resp.\ sped up in order to smear the leap second into the clock.
+
+In field \field{flags}, VIRTIO_RTC_FLAG_SMEAR indicates whether a leap
+second would be, or is being, smeared into the clock, rather than being
+inserted according to the UTC standard.
+
+A clock of subtype VIRTIO_RTC_SUBTYPE_LEAP_UNSPECIFIED can set
+\field{leap} to VIRTIO_RTC_LEAP_NONE regardless of the clock's actual
+leap second state. For clocks of subtype
+VIRTIO_RTC_SUBTYPE_LEAP_UNSPECIFIED, the VIRTIO_RTC_FLAG_SMEAR flag is
+only guaranteed to be correct while \field{leap} is not
+VIRTIO_RTC_LEAP_NONE.
+
+\subparagraph{TAI Offset}
+
+The \field{struct virtio_rtc_data_utc.tai_offset} field indicates the
+offset of the clock from the TAI standard, in the form
+$\mbox{tai_offset} = \mbox{TAI} - \mbox{UTC}$. The offset unit is ns.
+The offset is an integer multiple of a billion ns, i.e.\ corresponds to
+whole seconds, except while the clock is being smeared.
+
+If flag VIRTIO_RTC_FLAG_SMEAR is set, and field \field{leap} equals
+VIRTIO_RTC_LEAP_POS, or VIRTIO_RTC_LEAP_NEG, the offset from TAI does
+not correspond to whole seconds.\footnote{This keeps the impact of the
+	leap second insertion on the UTC offset from TAI unambiguous for
+	every sample of \field{struct virtio_rtc_data_utc}.}
+
+The \field{tai_offset} field is interpreted as a signed integer in
+little-endian, two's complement, representation.
+
+In field \field{flags}, VIRTIO_RTC_FLAG_TAI_OFFSET indicates that the
+TAI offset is valid. The device may only clear this flag for clocks of
+subtype VIRTIO_RTC_SUBTYPE_LEAP_UNSPECIFIED.
+
+\paragraph{Clock Performance Information}\label{sec:Device Types / RTC Device / Device Operation / Data Structures / Clock Performance Information}
+
+The \emph{clock performance} describes the difference between clock
+readings obtained by the driver from the device, and clock readings
+obtained from an ideal clock. Through \field{struct virtio_rtc_perf},
+the device reports the clock performance. \field{struct virtio_rtc_perf}
+describes the performance of a particular clock reading obtained by the
+driver.
+
+\begin{lstlisting}
+struct virtio_rtc_perf {
+	le64 freq_max_error;
+	le64 freq_est_error;
+	le64 phase_max_error;
+	le64 phase_est_error;
+#define VIRTIO_RTC_FLAG_SYNCHRONIZED (1 << 0)
+#define VIRTIO_RTC_FLAG_FREQ_MAX_VALID (1 << 1)
+#define VIRTIO_RTC_FLAG_FREQ_EST_VALID (1 << 2)
+#define VIRTIO_RTC_FLAG_PHASE_MAX_VALID (1 << 3)
+#define VIRTIO_RTC_FLAG_PHASE_EST_VALID (1 << 4)
+	u8 flags;
+	u8 reserved[7];
+};
+\end{lstlisting}
+
+Flag VIRTIO_RTC_FLAG_SYNCHRONIZED in field \field{flags} indicates that
+the device considers the clock synchronized as per the clock type and
+clock subtype requirements. In case of VIRTIO_RTC_CLOCK_UTC, flag
+VIRTIO_RTC_FLAG_SYNCHRONIZED also indicates that the clock is
+synchronized w.r.t.\ the information in \field{struct
+virtio_rtc_data_utc}, as per the clock subtype requirements.
+
+Other fields indicate the accuracy of the clock. Flags indicate whether
+this information is valid.
+
+The clock \emph{frequency error} is the (absolute) drift rate of the
+clock w.r.t.\ the clock type and subtype definition.
+
+Field \field{freq_max_error} is an upper bound to the frequency error of
+the clock. Field \field{freq_est_error} is the device's point estimate
+of the frequency error.
+
+The unit of the \field{freq_max_error} and \field{freq_est_error} fields
+is ppm (parts per million) with a 44-bit fractional part (a field value
+of 1 corresponds to $2^{-44}$ ppm).
+
+The device sets the flag VIRTIO_RTC_FLAG_FREQ_MAX_VALID resp.\
+VIRTIO_RTC_FLAG_FREQ_EST_VALID to indicate that the value of the
+\field{freq_max_error} resp.\ \field{freq_est_error} field is valid.
+
+The clock \emph{phase error} is the absolute value of the offset of the
+clock to an ideal clock according to the clock type and subtype
+definition.
+
+Field \field{phase_max_error} is an upper bound to the absolute offset
+of the clock from the clock type and subtype definition. Field
+\field{phase_est_error} is the device's point estimate of that absolute
+offset.
+
+The unit of the \field{phase_max_error} and \field{phase_est_error}
+fields is 1 nanosecond.
+
+The device sets the flag VIRTIO_RTC_FLAG_PHASE_MAX_VALID resp.\
+VIRTIO_RTC_FLAG_PHASE_EST_VALID to indicate that the value of the
+\field{phase_max_error} resp.\ \field{phase_est_error} field is valid.
+
 \subsubsection{Read Requests}\label{sec:Device Types / RTC Device / Device Operation / Read Requests}
 
 Through \emph{read requests}, the driver requests clock readings from
@@ -392,8 +649,6 @@ \subsubsection{Read Requests}\label{sec:Device Types / RTC Device / Device Opera
 	best frequency estimate.
 \end{itemize}
 
-E.g., a clock of type VIRTIO_RTC_CLOCK_UTC can insert UTC leap seconds.
-
 As long as a clock does not jump backwards, the driver clock readings
 increase monotonically:
 
@@ -458,6 +713,11 @@ \subsubsection{Read Requests}\label{sec:Device Types / RTC Device / Device Opera
 	struct virtio_rtc_resp_head head;
 	le64 clock_reading;
 	le64 counter_cycles;
+	union {
+		u8 reserved[16];
+		struct virtio_rtc_data_utc utc;
+	} type_data;
+	struct virtio_rtc_perf perf;
 };
 \end{lstlisting}
 
@@ -492,6 +752,23 @@ \subsubsection{Read Requests}\label{sec:Device Types / RTC Device / Device Opera
 VIRTIO_RTC_REQ_READ_CROSS for a specific clock and \field{hw_counter}
 through VIRTIO_RTC_REQ_CROSS_CAP.
 
+The field \field{type_data} is a union of clock type-specific extra
+information:
+
+\begin{enumerate}
+
+\item For clock type VIRTIO_RTC_CLOCK_UTC, field \field{type_data.utc}
+	provides information as per
+	\ref{sec:Device Types / RTC Device / Device Operation / Data Structures / UTC Specific Data}.
+
+\item For other clock types, all elements of field
+	\field{type_data.reserved} are 0.
+
+\end{enumerate}
+
+The field \field{perf} provides clock performance information as per
+	\ref{sec:Device Types / RTC Device / Device Operation / Data Structures / Clock Performance Information}.
+
 \end{description}
 
 \drivernormative{\paragraph}{Read Requests}{Device Types / RTC Device / Device Operation / Read Requests}
@@ -505,12 +782,6 @@ \subsubsection{Read Requests}\label{sec:Device Types / RTC Device / Device Opera
 The device SHOULD continuously support reading of all clocks once
 DRIVER_OK has been set.
 
-For any clock of type VIRTIO_RTC_CLOCK_UTC, the device MAY insert UTC
-leap seconds.
-
-For any clock of type VIRTIO_RTC_CLOCK_UTC, the device MAY smear UTC
-leap seconds through clock slewing.
-
 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
Signature · 1 line
2.43.0
maintainer
#6 lore raw

Re: [RFC PATCH v4 5/5] virtio-rtc: Indicate leap seconds and clock performance

Quoted 24 lines · Peter Hilber

 VIRTIO_RTC_CLOCK_UTC uses the UTC (Coordinated Universal Time) time

device-types/rtc/description.tex +4 -2
-standard. The device uses the time epoch of January 1, 1970, 00:00
-UTC. This is the same epoch as \emph{Unix time}.
+standard. The device uses the time epoch of January 1, 1970, 00:00 UTC.
+This is the same epoch as \emph{Unix time}. For VIRTIO_RTC_CLOCK_UTC,
+the clock \emph{subtype} specifies whether the clock fully adheres to
+the UTC standard w.r.t.\ leap seconds.


 VIRTIO_RTC_CLOCK_TAI uses the TAI (International Atomic Time) time standard. The device uses the time epoch of January 1, 1970, 00:00

(quoted diff) +0 -0
@@ -290,9 +293,62 @@ \subsubsection{Control Requests}\label{sec:Device Types / RTC Device / Device Op

 subdivisions) since some unspecified epoch. The VIRTIO_RTC_CLOCK_MONO epoch is before or during device reset.

device-types/rtc/description.tex +6 -3
-Additional clock types may be standardized in the future.
-Implementation-specific clock type definitions are not recommended and
-use a clock type id greater than or equal to 0xF000.
+The \field{subtype} field identifies the clock subtype. The clock
+subtype provides additional information about the clock behavior. The
+following clock subtypes are defined:
+
+\begin{lstlisting}
+#define VIRTIO_RTC_SUBTYPE_STRICT 0

device-types/rtc/description.tex \subsubsection{Control Requests}\label{sec:Device Types / RTC Device / Device Op · line 311

Quoted 10 lines
device-types/rtc/description.tex +10 -0
+#define VIRTIO_RTC_SUBTYPE_SMEAR 1
+#define VIRTIO_RTC_SUBTYPE_SMEAR_NOON_LINEAR 2
+#define VIRTIO_RTC_SUBTYPE_LEAP_UNSPECIFIED 3
+\end{lstlisting}
+
+VIRTIO_RTC_SUBTYPE_STRICT means that the clock fully adheres to the
+clock type's time standard (or to the clock type's time scale, if the
+clock type does not refer to a time standard). This is the only subtype
+for clocks which are not of type VIRTIO_RTC_CLOCK_UTC.
+

I don't think this should be done as 'subtypes'. Just make them types, as *alternatives* to VIRTIO_RTC_CLOCK_UTC and VIRTIO_RTC_CLOCK_TAI.

Anything but VIRTIO_RTC_SUBTYPE_STRICT is *not* actually UTC. You basically say that in what I've cited above.

It shouldn't be misrepresented as such.

#7 lore raw

Re: [RFC PATCH v4 5/5] virtio-rtc: Indicate leap seconds and clock performance

Quoted 39 lines · David Woodhouse
Quoted 24 lines · Peter Hilber

 VIRTIO_RTC_CLOCK_UTC uses the UTC (Coordinated Universal Time) time

device-types/rtc/description.tex +4 -2
-standard. The device uses the time epoch of January 1, 1970, 00:00
-UTC. This is the same epoch as \emph{Unix time}.
+standard. The device uses the time epoch of January 1, 1970, 00:00 UTC.
+This is the same epoch as \emph{Unix time}. For VIRTIO_RTC_CLOCK_UTC,
+the clock \emph{subtype} specifies whether the clock fully adheres to
+the UTC standard w.r.t.\ leap seconds.


 VIRTIO_RTC_CLOCK_TAI uses the TAI (International Atomic Time) time standard. The device uses the time epoch of January 1, 1970, 00:00

(quoted diff) +0 -0
@@ -290,9 +293,62 @@ \subsubsection{Control Requests}\label{sec:Device Types / RTC Device / Device Op

 subdivisions) since some unspecified epoch. The VIRTIO_RTC_CLOCK_MONO epoch is before or during device reset.

device-types/rtc/description.tex +6 -3
-Additional clock types may be standardized in the future.
-Implementation-specific clock type definitions are not recommended and
-use a clock type id greater than or equal to 0xF000.
+The \field{subtype} field identifies the clock subtype. The clock
+subtype provides additional information about the clock behavior. The
+following clock subtypes are defined:
+
+\begin{lstlisting}
+#define VIRTIO_RTC_SUBTYPE_STRICT 0

device-types/rtc/description.tex \subsubsection{Control Requests}\label{sec:Device Types / RTC Device / Device Op · line 311

Quoted 10 lines
device-types/rtc/description.tex +10 -0
+#define VIRTIO_RTC_SUBTYPE_SMEAR 1
+#define VIRTIO_RTC_SUBTYPE_SMEAR_NOON_LINEAR 2
+#define VIRTIO_RTC_SUBTYPE_LEAP_UNSPECIFIED 3
+\end{lstlisting}
+
+VIRTIO_RTC_SUBTYPE_STRICT means that the clock fully adheres to the
+clock type's time standard (or to the clock type's time scale, if the
+clock type does not refer to a time standard). This is the only subtype
+for clocks which are not of type VIRTIO_RTC_CLOCK_UTC.
+

I don't think this should be done as 'subtypes'. Just make them types, as *alternatives* to VIRTIO_RTC_CLOCK_UTC and VIRTIO_RTC_CLOCK_TAI.

Quoted 6 lines

Anything but VIRTIO_RTC_SUBTYPE_STRICT is *not* actually UTC. You basically say that in what I've cited above.

It shouldn't be misrepresented as such.

The idea with subtypes is to be forward-compatible with other, yet unnamed, leap second smearing variants, so that the driver can still recognize them as UTC-like, even if it doesn't know the particular subtype.

But if only linear smearing (and perhaps cosine smearing) would be supported (apart from "unspecified" leap second handling), and the start and end times of smearing would be indicated explicitly, then there would be no need to distinguish subtypes any further.

Then, the smearing subtypes could become designated types.

maintainer
#8 lore raw

Re: [RFC PATCH v4 5/5] virtio-rtc: Indicate leap seconds and clock performance

Quoted 10 lines · Peter Hilber

The idea with subtypes is to be forward-compatible with other, yet unnamed, leap second smearing variants, so that the driver can still recognize them as UTC-like, even if it doesn't know the particular subtype.

But if only linear smearing (and perhaps cosine smearing) would be supported (apart from "unspecified" leap second handling), and the start and end times of smearing would be indicated explicitly, then there would be no need to distinguish subtypes any further.

Then, the smearing subtypes could become designated types.

I don't think we should encourage this concept of "UTC-like". If the clock is subject to smearing, then that is *not* UTC, at least as far as a precision clock is concerned.

And if it's subject to smearing that isn't *explicitly* defined, that's even worse. It's up to a second away from UTC, with a deliberately introduced 'error' which is unpredictable by the guest.

Perhaps the guest could treat such an undefined smearing as a monotonic clock, but nobody who cares about precision should treat it as UTC, surely? Or even "UTC-like".

We should expose only fully-defined smearing algorithms, and if they are fully defined then they can happily be a top-level *type* rather than a subtype, yes? Let's not have anyone accidentally consuming them and thinking they're UTC.

#9 lore raw

Re: [RFC PATCH v4 5/5] virtio-rtc: Indicate leap seconds and clock performance

Quoted 20 lines · David Woodhouse
Quoted 10 lines · Peter Hilber

The idea with subtypes is to be forward-compatible with other, yet unnamed, leap second smearing variants, so that the driver can still recognize them as UTC-like, even if it doesn't know the particular subtype.

But if only linear smearing (and perhaps cosine smearing) would be supported (apart from "unspecified" leap second handling), and the start and end times of smearing would be indicated explicitly, then there would be no need to distinguish subtypes any further.

Then, the smearing subtypes could become designated types.

I don't think we should encourage this concept of "UTC-like". If the clock is subject to smearing, then that is *not* UTC, at least as far as a precision clock is concerned.

And if it's subject to smearing that isn't *explicitly* defined, that's even worse. It's up to a second away from UTC, with a deliberately introduced 'error' which is unpredictable by the guest.

Quoted 10 lines

Perhaps the guest could treat such an undefined smearing as a monotonic clock, but nobody who cares about precision should treat it as UTC, surely? Or even "UTC-like".

We should expose only fully-defined smearing algorithms, and if they are fully defined then they can happily be a top-level *type* rather than a subtype, yes? Let's not have anyone accidentally consuming them and thinking they're UTC.

So my above line of thought would result in three types (not subtypes):

1) UTC

2) UTC-like with leap seconds smeared (with info about smearing:
linear/cosine(?), start, end)

3) UTC-like, with leap second handling not specified

I understand 3) is not suitable for your use cases, but you could identify, and refuse to use, 3) (that would also have been possible with subtypes, though).

maintainer
#10 lore raw

Re: [RFC PATCH v4 5/5] virtio-rtc: Indicate leap seconds and clock performance

Quoted 5 lines · Peter Hilber

So my above line of thought would result in three types (not subtypes):

1) UTC

Quoted 8 lines

2) UTC-like with leap seconds smeared (with info about smearing:
   linear/cosine(?), start, end)

3) UTC-like, with leap second handling not specified

I understand 3) is not suitable for your use cases, but you could identify, and refuse to use, 3) (that would also have been possible with subtypes, though).

Well, there are two use cases I'm trying to take care of.

There's the specific case of virtual machines suffering disruption due to live migration. Phase 1 of that plan only really needs the disruption marker in a shared-memory region, and guests can spot for themselves that their clocks are hosed and abort transactions until NTP has resynced. There's no need to even ponder smearing in that case; it's orthogonal.

Phase 2 of that plan involves exposing the *actual* clock information as calibrated by the host, through the same memory region. And since that involves advertising the *rate* of the oscillator, it's complicated to expose a *smeared* clock as the primary type of the device, as we'd have to expose the smearing_delta_frac_sec and also convey information about how the counter_period_frac_sec varys over time. So it's a whole lot easier to use the structure to convey true UTC/TAI and then let the guest perform the smearing, if it must.

But separately from that, I also want to avoid errors that arise from ambiguity. I don't want people to accidentally use a clock which is not UTC, when they expect UTC.

Which is why I don't like that "UTC-like" label in your option 3. Just call it a 'monotonic' clock, because that's what it is. If you use this clock, you do not objectively know what the time is. As with any monotonic clock being shared through such a device, it presumably has some meaning in the local environment and is useful for communicating with the systems close around you — otherwise, why bother at all? But it is not, and should not be conflated with, UTC.

If you replace the letters "UTC-like" in your option 2 with "not UTC" I'm slightly more OK with that one but for the reasons described in my previous email, I'd rather *enumerate* the defined ways of smearing instead of encouraging a proliferation of them by parameterising it.

maintainer
#11 lore raw

Re: [RFC PATCH v4 5/5] virtio-rtc: Indicate leap seconds and clock performance

In reply to Peter Hilber
Quoted 1 line · Peter Hilber

+This section describes reusable data structures.

I would like to reuse them! Or at least the VIRTIO_RTC_LEAP_xxx values.

Quoted 33 lines
device-types/rtc/description.tex +33 -0
+
+\paragraph{UTC Specific Data}\label{sec:Device Types / RTC Device / Device Operation / Data Structures / UTC Specific Data}
+
+For clocks of type VIRTIO_RTC_CLOCK_UTC, the device reports information
+about impending and ongoing UTC leap seconds, and about the current UTC
+offset from TAI, through \field{struct virtio_rtc_data_utc}. This
+information applies to the clock reading to which the struct is
+associated to.
+
+\begin{lstlisting}
+struct virtio_rtc_data_utc {
+       le64 tai_offset;
+#define VIRTIO_RTC_LEAP_NONE 0
+#define VIRTIO_RTC_LEAP_PRE_POS 1
+#define VIRTIO_RTC_LEAP_PRE_NEG 2
+#define VIRTIO_RTC_LEAP_POS 3
+#define VIRTIO_RTC_LEAP_NEG 4
+       u8 leap;
+#define VIRTIO_RTC_FLAG_SMEAR (1 << 0)
+#define VIRTIO_RTC_FLAG_TAI_OFFSET (1 << 1)
+       u8 flags;
+       u8 reserved[6];
+};
+\end{lstlisting}
+
+\subparagraph{Leap Second Indication}
+
+For subtype VIRTIO_RTC_SUBTYPE_STRICT, the \field{struct
+virtio_rtc_data_utc.leap} field indicates whether a positive or negative
+leap second will be introduced at the end of the month resp.\ whether a
+leap second is currently in progress.
+
+For a leap smearing clock, the \field{leap} field indicates whether a

device-types/rtc/description.tex \subsubsection{Control Requests}\label{sec:Device Types / RTC Device / Device Op · line 523

Quoted 10 lines
device-types/rtc/description.tex +10 -0
+leap smear will start around the next turn of the month resp.\ whether
+the leap second is currently being smeared into the clock.
+
+VIRTIO_RTC_LEAP_NONE indicates that the clock is currently not
+performing leap second related processing, and also not pre-announcing
+an impending leap second.
+
+VIRTIO_RTC_LEAP_PRE_POS resp.\ VIRTIO_RTC_LEAP_PRE_NEG pre-announce a
+positive resp.\ negative leap second. Pre-announcing starts at the
+earliest at the 17th day of the month including the leap second.

Where does 17th come from? Is there an existing precedent for that?

device-types/rtc/description.tex \subsubsection{Control Requests}\label{sec:Device Types / RTC Device / Device Op · line 526

Quoted 2 lines
device-types/rtc/description.tex +2 -0
+For VIRTIO_RTC_SUBTYPE_STRICT, VIRTIO_RTC_LEAP_POS indicates that a
+positive leap second is in progress.

The term "in progress" confused me for a while, as a leap second is an instantaneous jump. Do I understand this correctly... a UTC clock might progress as follows (100ms intervals):

1483228798.8 LEAP_PRE_POS
1483228798.9 LEAP_PRE_POS
1483228799.0 LEAP_POS
1483228799.1 LEAP_POS
1483228799.2 LEAP_POS
1483228799.3 LEAP_POS
1483228799.4 LEAP_POS
1483228799.5 LEAP_POS
1483228799.6 LEAP_POS
1483228799.7 LEAP_POS
1483228799.8 LEAP_POS
1483228799.9 LEAP_POS
1483228799.0 ← jumps back by 1s
1483228799.1

So if the second 1483228799 repeats itself due to a positive leap second, your VIRTIO_RTC_LEAP_POS "in progress" flag is set during the 1st occurrence of that second, and not the 2nd occurrence?

device-types/rtc/description.tex \subsubsection{Control Requests}\label{sec:Device Types / RTC Device / Device Op · line 530

Quoted 3 lines
device-types/rtc/description.tex +3 -0
+For a leap smearing clock, VIRTIO_RTC_LEAP_PRE_POS resp.\
+VIRTIO_RTC_LEAP_PRE_NEG indicate that the clock is currently slowed down
+resp.\ sped up in order to smear the leap second into the clock.

Hm, is this consistent with your earlier statement that PRE_POS/PRE_NEG can be set from the 17th day of the month? Because it isn't true that the clock "is currently slowed down" for all of that time, right?

I think we might want a separate flag to indicate that smearing *is* currently in progress, and that the time reported is not UTC.

(I guess maybe a non-integer value of the tai_offset field might be used to infer that, but I have concerns about that too, because surely that can't be atomically read *with* a given clock pairing, and will be constantly changing during the smearing period?)

device-types/rtc/description.tex \subsubsection{Control Requests}\label{sec:Device Types / RTC Device / Device Op · line 534

Quoted 3 lines
device-types/rtc/description.tex +3 -0
+In field \field{flags}, VIRTIO_RTC_FLAG_SMEAR indicates whether a leap
+second would be, or is being, smeared into the clock, rather than being
+inserted according to the UTC standard.

"would be"... didn't we already indicate that with the clock type and subtype? Perhaps we use this for "is being" and it resolves my above concern?

I think I'd also like to have a 'LEAP_POST_POS' and 'LEAP_POST_NEG' flag which are set for a period of time *after* the occurrence of a leap second. That's helpful for a client to be able to produce a smeared clock when the device is exposing true UTC.

Quoted 4 lines
device-types/rtc/description.tex +4 -0
+A clock of subtype VIRTIO_RTC_SUBTYPE_LEAP_UNSPECIFIED can set
+\field{leap} to VIRTIO_RTC_LEAP_NONE regardless of the clock's actual
+leap second state. For clocks of subtype
+VIRTIO_RTC_SUBTYPE_LEAP_UNSPECIFIED, the VIRTIO_RTC_FLAG_SMEAR flag is

device-types/rtc/description.tex \subsubsection{Control Requests}\label{sec:Device Types / RTC Device / Device Op · line 549

Quoted 10 lines
device-types/rtc/description.tex +10 -0
+only guaranteed to be correct while \field{leap} is not
+VIRTIO_RTC_LEAP_NONE.
+
+\subparagraph{TAI Offset}
+
+The \field{struct virtio_rtc_data_utc.tai_offset} field indicates the
+offset of the clock from the TAI standard, in the form
+$\mbox{tai_offset} = \mbox{TAI} - \mbox{UTC}$. The offset unit is ns.
+The offset is an integer multiple of a billion ns, i.e.\ corresponds to
+whole seconds, except while the clock is being smeared.

There isn't any fundamental reason why this value can't be signed, is there?

device-types/rtc/description.tex \subsubsection{Control Requests}\label{sec:Device Types / RTC Device / Device Op · line 555

Quoted 5 lines
device-types/rtc/description.tex +5 -0
+If flag VIRTIO_RTC_FLAG_SMEAR is set, and field \field{leap} equals
+VIRTIO_RTC_LEAP_POS, or VIRTIO_RTC_LEAP_NEG, the offset from TAI does
+not correspond to whole seconds.\footnote{This keeps the impact of the
+       leap second insertion on the UTC offset from TAI unambiguous for
+       every sample of \field{struct virtio_rtc_data_utc}.}

See question above about the atomicity of this w.r.t any given clock reading. Do we have to return this whole struct virtio_rtc_data_utc as part of every clock reading?

I wonder if we'd do better to keep the UTC←→TAI offset as an integer, and also expose a fractional offset of a given clock reading from UTC, if that's the intent?

Quoted 17 lines
device-types/rtc/description.tex +17 -0
+The \field{tai_offset} field is interpreted as a signed integer in
+little-endian, two's complement, representation.
+
+In field \field{flags}, VIRTIO_RTC_FLAG_TAI_OFFSET indicates that the
+TAI offset is valid. The device may only clear this flag for clocks of
+subtype VIRTIO_RTC_SUBTYPE_LEAP_UNSPECIFIED.
+
+\paragraph{Clock Performance Information}\label{sec:Device Types / RTC Device / Device Operation / Data Structures / Clock Performance Information}
+
+The \emph{clock performance} describes the difference between clock
+readings obtained by the driver from the device, and clock readings
+obtained from an ideal clock. Through \field{struct virtio_rtc_perf},
+the device reports the clock performance. \field{struct virtio_rtc_perf}
+describes the performance of a particular clock reading obtained by the
+driver.
+
+\begin{lstlisting}

device-types/rtc/description.tex \subsubsection{Control Requests}\label{sec:Device Types / RTC Device / Device Op · line 583

Quoted 10 lines
device-types/rtc/description.tex +10 -0
+struct virtio_rtc_perf {
+       le64 freq_max_error;
+       le64 freq_est_error;
+       le64 phase_max_error;
+       le64 phase_est_error;
+#define VIRTIO_RTC_FLAG_SYNCHRONIZED (1 << 0)
+#define VIRTIO_RTC_FLAG_FREQ_MAX_VALID (1 << 1)
+#define VIRTIO_RTC_FLAG_FREQ_EST_VALID (1 << 2)
+#define VIRTIO_RTC_FLAG_PHASE_MAX_VALID (1 << 3)
+#define VIRTIO_RTC_FLAG_PHASE_EST_VALID (1 << 4)

Hm, the VMCLOCK structure doesn't have estimated error, only max error. Should we add them? Julien? Ryan?

device-types/rtc/description.tex \subsubsection{Control Requests}\label{sec:Device Types / RTC Device / Device Op · line 595

Quoted 12 lines

+       u8 flags;
+       u8 reserved[7];

device-types/rtc/description.tex +10 -0
+};
+\end{lstlisting}
+
+Flag VIRTIO_RTC_FLAG_SYNCHRONIZED in field \field{flags} indicates that
+the device considers the clock synchronized as per the clock type and
+clock subtype requirements. In case of VIRTIO_RTC_CLOCK_UTC, flag
+VIRTIO_RTC_FLAG_SYNCHRONIZED also indicates that the clock is
+synchronized w.r.t.\ the information in \field{struct
+virtio_rtc_data_utc}, as per the clock subtype requirements.
+

I ended up with status values as follows:

#define VMCLOCK_STATUS_UNKNOWN 0
#define VMCLOCK_STATUS_INITIALIZING 1
#define VMCLOCK_STATUS_SYNCHRONIZED 2
#define VMCLOCK_STATUS_FREERUNNING 3
#define VMCLOCK_STATUS_UNRELIABLE 4

I don't know if they came from an existing precedent or were just put in as placeholders. Julien? Ryan?

#12 lore raw

Re: [RFC PATCH v4 5/5] virtio-rtc: Indicate leap seconds and clock performance

Quoted 44 lines · David Woodhouse
Quoted 1 line · Peter Hilber

+This section describes reusable data structures.

I would like to reuse them! Or at least the VIRTIO_RTC_LEAP_xxx values.

Quoted 37 lines
device-types/rtc/description.tex +37 -0
+
+\paragraph{UTC Specific Data}\label{sec:Device Types / RTC Device / Device Operation / Data Structures / UTC Specific Data}
+
+For clocks of type VIRTIO_RTC_CLOCK_UTC, the device reports information
+about impending and ongoing UTC leap seconds, and about the current UTC
+offset from TAI, through \field{struct virtio_rtc_data_utc}. This
+information applies to the clock reading to which the struct is
+associated to.
+
+\begin{lstlisting}
+struct virtio_rtc_data_utc {
+       le64 tai_offset;
+#define VIRTIO_RTC_LEAP_NONE 0
+#define VIRTIO_RTC_LEAP_PRE_POS 1
+#define VIRTIO_RTC_LEAP_PRE_NEG 2
+#define VIRTIO_RTC_LEAP_POS 3
+#define VIRTIO_RTC_LEAP_NEG 4
+       u8 leap;
+#define VIRTIO_RTC_FLAG_SMEAR (1 << 0)
+#define VIRTIO_RTC_FLAG_TAI_OFFSET (1 << 1)
+       u8 flags;
+       u8 reserved[6];
+};
+\end{lstlisting}
+
+\subparagraph{Leap Second Indication}
+
+For subtype VIRTIO_RTC_SUBTYPE_STRICT, the \field{struct
+virtio_rtc_data_utc.leap} field indicates whether a positive or negative
+leap second will be introduced at the end of the month resp.\ whether a
+leap second is currently in progress.
+
+For a leap smearing clock, the \field{leap} field indicates whether a
+leap smear will start around the next turn of the month resp.\ whether
+the leap second is currently being smeared into the clock.
+
+VIRTIO_RTC_LEAP_NONE indicates that the clock is currently not
Quoted 9 lines

device-types/rtc/description.tex \subsubsection{Control Requests}\label{sec:Device Types / RTC Device / Device Op · line 523

Quoted 6 lines
device-types/rtc/description.tex +6 -0
+performing leap second related processing, and also not pre-announcing
+an impending leap second.
+
+VIRTIO_RTC_LEAP_PRE_POS resp.\ VIRTIO_RTC_LEAP_PRE_NEG pre-announce a
+positive resp.\ negative leap second. Pre-announcing starts at the
+earliest at the 17th day of the month including the leap second.

Where does 17th come from? Is there an existing precedent for that?

It doesn't come from anywhere. I set it to the second half of the month to disambiguate pre-announcing, in case a particular smearing algorithm would only start smearing on the day after the leap second (at the start of the month).

Quoted 6 lines

device-types/rtc/description.tex \subsubsection{Control Requests}\label{sec:Device Types / RTC Device / Device Op · line 526

Quoted 2 lines
device-types/rtc/description.tex +2 -0
+For VIRTIO_RTC_SUBTYPE_STRICT, VIRTIO_RTC_LEAP_POS indicates that a
+positive leap second is in progress.

The term "in progress" confused me for a while, as a leap second is an instantaneous jump. Do I understand this correctly... a UTC clock might progress as follows (100ms intervals):

VIRTIO_RTC_LEAP_POS is intended to describe the state described by TIME_OOP in adjtimex(2): "Insertion of a leap second is in progress."

(VIRTIO_RTC_LEAP_NEG would only make sense in the case of smearing. But maybe smearing should get its own values instead of special semantics in conjunction with VIRTIO_RTC_FLAG_SMEAR. There is already some confusion.

I did not use insertion/deletion names here because this would be inconsistent with the TIME_INS/TIME_DEL names, which are actually pre-announcing a leap second.)

Maybe a "second in progress" is not good English, but my understanding is that a positive leap second is not a leap (and a positive leap second has an associated timespan). AFAIU the backwards leap is a mere technological kludge and actual definitions talk about a 61st second [1]:

Quoted 25 lines

A positive leap second will be introduced at the end of December 2016. The sequence of dates of the UTC second markers will be:

                          2016 December 31, 23h 59m 59s
                          2016 December 31, 23h 59m 60s
                          2017 January   1,  0h  0m  0s

1483228798.8 LEAP_PRE_POS
1483228798.9 LEAP_PRE_POS
1483228799.0 LEAP_POS
1483228799.1 LEAP_POS
1483228799.2 LEAP_POS
1483228799.3 LEAP_POS
1483228799.4 LEAP_POS
1483228799.5 LEAP_POS
1483228799.6 LEAP_POS
1483228799.7 LEAP_POS
1483228799.8 LEAP_POS
1483228799.9 LEAP_POS
1483228799.0 ← jumps back by 1s
1483228799.1

Quoted 3 lines

So if the second 1483228799 repeats itself due to a positive leap second, your VIRTIO_RTC_LEAP_POS "in progress" flag is set during the 1st occurrence of that second, and not the 2nd occurrence?

No. LEAP_POS would start only on the jump back by 1 s.

Quoted 10 lines

device-types/rtc/description.tex \subsubsection{Control Requests}\label{sec:Device Types / RTC Device / Device Op · line 530

Quoted 5 lines
device-types/rtc/description.tex +3 -0
+For a leap smearing clock, VIRTIO_RTC_LEAP_PRE_POS resp.\
+VIRTIO_RTC_LEAP_PRE_NEG indicate that the clock is currently slowed down
+resp.\ sped up in order to smear the leap second into the clock.

Hm, is this consistent with your earlier statement that PRE_POS/PRE_NEG can be set from the 17th day of the month? Because it isn't true that the clock "is currently slowed down" for all of that time, right?

This is an embarrassing mistake, I should have written "VIRTIO_RTC_LEAP_POS resp. VIRTIO_RTC_LEAP_NEG".

Quoted 2 lines

I think we might want a separate flag to indicate that smearing *is* currently in progress, and that the time reported is not UTC.

With the correction as per my above response, leap can already indicate this together with VIRTIO_RTC_FLAG_SMEAR. But as I discussed above, it might be better to use dedicated leap values for smearing.

Quoted 5 lines

(I guess maybe a non-integer value of the tai_offset field might be used to infer that, but I have concerns about that too, because surely that can't be atomically read *with* a given clock pairing, and will be constantly changing during the smearing period?)

With a message-based clock read, the device should be able to calculate the offset. For SHM, the vmclock approach appears more suitable.

Quoted 9 lines

device-types/rtc/description.tex \subsubsection{Control Requests}\label{sec:Device Types / RTC Device / Device Op · line 534

Quoted 5 lines
device-types/rtc/description.tex +3 -0
+In field \field{flags}, VIRTIO_RTC_FLAG_SMEAR indicates whether a leap
+second would be, or is being, smeared into the clock, rather than being
+inserted according to the UTC standard.

"would be"... didn't we already indicate that with the clock type and subtype? Perhaps we use this for "is being" and it resolves my above concern?

As discussed above, whether smearing is being done would be signaled by the leap member.

In the case of VIRTIO_RTC_CLOCK_MAYBE_SMEARED, VIRTIO_RTC_FLAG_SMEAR would still add extra information to distinguish smearing from not smearing (but as discussed above, the leap values might be extended to distinguish not smearing and smearing).

Quoted 6 lines

I think I'd also like to have a 'LEAP_POST_POS' and 'LEAP_POST_NEG' flag which are set for a period of time *after* the occurrence of a leap second. That's helpful for a client to be able to produce a smeared clock when the device is exposing true UTC.

Ack.

Quoted 9 lines
Quoted 9 lines
device-types/rtc/description.tex +9 -0
+A clock of subtype VIRTIO_RTC_SUBTYPE_LEAP_UNSPECIFIED can set
+\field{leap} to VIRTIO_RTC_LEAP_NONE regardless of the clock's actual
+leap second state. For clocks of subtype
+VIRTIO_RTC_SUBTYPE_LEAP_UNSPECIFIED, the VIRTIO_RTC_FLAG_SMEAR flag is
+only guaranteed to be correct while \field{leap} is not
+VIRTIO_RTC_LEAP_NONE.
+
+\subparagraph{TAI Offset}
+
Quoted 9 lines

device-types/rtc/description.tex \subsubsection{Control Requests}\label{sec:Device Types / RTC Device / Device Op · line 549

Quoted 5 lines
device-types/rtc/description.tex +5 -0
+The \field{struct virtio_rtc_data_utc.tai_offset} field indicates the
+offset of the clock from the TAI standard, in the form
+$\mbox{tai_offset} = \mbox{TAI} - \mbox{UTC}$. The offset unit is ns.
+The offset is an integer multiple of a billion ns, i.e.\ corresponds to
+whole seconds, except while the clock is being smeared.

There isn't any fundamental reason why this value can't be signed, is there?

No, it is only that all current Virtio types are unsigned. Introducing a signed value might require extending the generic specification.

Quoted 5 lines

device-types/rtc/description.tex \subsubsection{Control Requests}\label{sec:Device Types / RTC Device / Device Op · line 555

Quoted 5 lines
device-types/rtc/description.tex +5 -0
+If flag VIRTIO_RTC_FLAG_SMEAR is set, and field \field{leap} equals
+VIRTIO_RTC_LEAP_POS, or VIRTIO_RTC_LEAP_NEG, the offset from TAI does
+not correspond to whole seconds.\footnote{This keeps the impact of the
+       leap second insertion on the UTC offset from TAI unambiguous for
+       every sample of \field{struct virtio_rtc_data_utc}.}

I think the above stipulation should be removed, it causes unnecessary limitations.

Quoted 5 lines

See question above about the atomicity of this w.r.t any given clock reading. Do we have to return this whole struct virtio_rtc_data_utc as part of every clock reading?

The idea was to return struct virtio_rtc_data_utc with every VIRTIO_RTC_REQ_READ_CROSS message response (for UTC or smearing clocks), or to clear VIRTIO_RTC_FLAG_TAI_OFFSET. Supporting that message is not mandatory.

The simple VIRTIO_RTC_REQ_READ message response does not include this information.

Quoted 4 lines

I wonder if we'd do better to keep the UTC←→TAI offset as an integer, and also expose a fractional offset of a given clock reading from UTC, if that's the intent?

OK.

[1] https://datacenter.iers.org/data/16/bulletinc-052.txt

maintainer
#13 lore raw

Re: [RFC PATCH v4 5/5] virtio-rtc: Indicate leap seconds and clock performance

Quoted 26 lines · Peter Hilber
Quoted 26 lines

  A positive leap second will be introduced at the end of December 2016. The sequence of dates of the UTC second markers will be:

                           2016 December 31, 23h 59m 59s 2016 December 31, 23h 59m 60s 2017 January   1,  0h  0m  0s

  1483228798.8 LEAP_PRE_POS
  1483228798.9 LEAP_PRE_POS
  1483228799.0 LEAP_POS
  1483228799.1 LEAP_POS
  1483228799.2 LEAP_POS
  1483228799.3 LEAP_POS
  1483228799.4 LEAP_POS
  1483228799.5 LEAP_POS
  1483228799.6 LEAP_POS
  1483228799.7 LEAP_POS
  1483228799.8 LEAP_POS
  1483228799.9 LEAP_POS
  1483228799.0             ← jumps back by 1s
  1483228799.1

Quoted 5 lines
Quoted 3 lines

So if the second 1483228799 repeats itself due to a positive leap second, your VIRTIO_RTC_LEAP_POS "in progress" flag is set during the 1st occurrence of that second, and not the 2nd occurrence?

No. LEAP_POS would start only on the jump back by 1 s.

Gotcha, so it would be set for the duration of the 23:59:60 second, not the 23:59:59 second as I showed above?

I added these to the structure and started trying to *use* them in the Linux PTP driver, and got a little confused. How is this supposed to work?

I don't see how Linux PTP devices (/dev/ptpX) even inform userspace of which time scale they're using. Is it TAI? Is it UTC? If it's UTC, how are we supposed to cope with the TAI/UTC offset *changing*, as it does at the moment we're discussing? All I can find is explicit configuration of a hard-coded offset. I now realise I've been testing it with 'phc2sys -s /dev/ptp0 -O0 -m' in the guest... -O0.

So a PTP_SYS_OFFSET_EXTENDED2 ioctl returns 3-tuples of { system pre, reference, system post } timestamps. If those are just UTC without any leap indicator, the 'post' timestamp could appear to be *before* the pre timestamp.

Or if the leap second doesn't happen *during* a reading like that, and I'm getting paired readings of the TSC and reference clock every ten seconds, one reading is suddenly going to tell me that my TSC is going 10% faster!

Is the onus on the consumer to spot the whole-second discrepancy and *infer* that a leap second occurred, and/or to have known it through other methods? Is the lack of explicitly support for this in Linux PTP intentional? Or am I missing something?

#14 lore raw

Re: [RFC PATCH v4 5/5] virtio-rtc: Indicate leap seconds and clock performance

Quoted 27 lines · David Woodhouse
Quoted 26 lines · Peter Hilber
Quoted 26 lines

  A positive leap second will be introduced at the end of December 2016. The sequence of dates of the UTC second markers will be:

                           2016 December 31, 23h 59m 59s 2016 December 31, 23h 59m 60s 2017 January   1,  0h  0m  0s

  1483228798.8 LEAP_PRE_POS
  1483228798.9 LEAP_PRE_POS
  1483228799.0 LEAP_POS
  1483228799.1 LEAP_POS
  1483228799.2 LEAP_POS
  1483228799.3 LEAP_POS
  1483228799.4 LEAP_POS
  1483228799.5 LEAP_POS
  1483228799.6 LEAP_POS
  1483228799.7 LEAP_POS
  1483228799.8 LEAP_POS
  1483228799.9 LEAP_POS
  1483228799.0             ← jumps back by 1s
  1483228799.1

Quoted 8 lines
Quoted 5 lines
Quoted 3 lines

So if the second 1483228799 repeats itself due to a positive leap second, your VIRTIO_RTC_LEAP_POS "in progress" flag is set during the 1st occurrence of that second, and not the 2nd occurrence?

No. LEAP_POS would start only on the jump back by 1 s.

Gotcha, so it would be set for the duration of the 23:59:60 second, not the 23:59:59 second as I showed above?

Yes.

Quoted 4 lines

I added these to the structure and started trying to *use* them in the Linux PTP driver, and got a little confused. How is this supposed to work?

To use this information the UAPI needs to be extended (I suggest with a new PTP_SYS_ ioctl).

Quoted 7 lines

I don't see how Linux PTP devices (/dev/ptpX) even inform userspace of which time scale they're using. Is it TAI? Is it UTC? If it's UTC, how are we supposed to cope with the TAI/UTC offset *changing*, as it does at the moment we're discussing? All I can find is explicit configuration of a hard-coded offset. I now realise I've been testing it with 'phc2sys -s /dev/ptp0 -O0 -m' in the guest... -O0.

AFAIU this indeed needs to be configured manually if the PTP Hardware Clock is the only interface.

Quoted 5 lines

So a PTP_SYS_OFFSET_EXTENDED2 ioctl returns 3-tuples of { system pre, reference, system post } timestamps. If those are just UTC without any leap indicator, the 'post' timestamp could appear to be *before* the pre timestamp.

If the clock synchronization daemon knows through other means about the leap second, it will probably choose to ignore such a timestamp. Otherwise, using non-precise timestamps appears to be problematic.

Quoted 5 lines

Or if the leap second doesn't happen *during* a reading like that, and I'm getting paired readings of the TSC and reference clock every ten seconds, one reading is suddenly going to tell me that my TSC is going 10% faster!

AFAIU there are two ways to address this:

1) Extend the UAPI to convey the leap second information through the PHC.

2) The guest has another source of leap second information, such as up-to-date tzdata files, or NTP.

In both cases, a clock synchronization daemon should pick up this information and initiate the leap second step. 2) should already work, supporting 1) in clock synchronization daemons should *hopefully* be manageable.

Quoted 7 lines

Is the onus on the consumer to spot the whole-second discrepancy and *infer* that a leap second occurred, and/or to have known it through other methods? Is the lack of explicitly support for this in Linux PTP intentional? Or am I missing something?

AFAIU for Linux kernel PTP Hardware Clocks there is indeed no generic way to indicate leap seconds, yet. The ptp4l program can get leap second pre-announcements through the PTP messages and AFAIU phc2sys can get the leap second indication from ptp4l (which does not help our use cases).

maintainer
#15 lore raw

Re: [RFC PATCH v4 5/5] virtio-rtc: Indicate leap seconds and clock performance

In reply to Peter Hilber
Quoted 9 lines · Peter Hilber
Quoted 7 lines · David Woodhouse

device-types/rtc/description.tex \subsubsection{Control Requests}\label{sec:Device Types / RTC Device / Device Op · line 523

Quoted 3 lines · Peter Hilber
device-types/rtc/description.tex +3 -0
+VIRTIO_RTC_LEAP_PRE_POS resp.\ VIRTIO_RTC_LEAP_PRE_NEG pre-announce a
+positive resp.\ negative leap second. Pre-announcing starts at the
+earliest at the 17th day of the month including the leap second.

Where does 17th come from? Is there an existing precedent for that?

Quoted 4 lines

It doesn't come from anywhere. I set it to the second half of the month to disambiguate pre-announcing, in case a particular smearing algorithm would only start smearing on the day after the leap second (at the start of the month).

The day *after* the leap second shouldn't be considered "pre- announcement", should it? Wouldn't that be another case for the VIRTIO_RTC_LEAP_POST_{POS,NEG} that I requested? It is notification of a leap second which occurred in the recent past, for which smearing activity may still be ongoing.

Quoted 4 lines

With the correction as per my above response, leap can already indicate this together with VIRTIO_RTC_FLAG_SMEAR. But as I discussed above, it might be better to use dedicated leap values for smearing.

Makes sense. At this point I think as long as we have the POST indications I can align the shared structure with your method of indicating leap seconds.

The pre-announcement of a leap second at the end of the month is hard to consume within the PTP driver. At the end of the *day* is easy enough as it's just a case of dividing by 86400. Months are a lot harder, and involve knowledge of leap years and other complexity.

But if the complexity all falls in userspace, and we only expose that "leap at end of month" pre-announcement to userspace and expect userspace to work out *which* second that is and tell the kernel, perhaps that's OK? I'm still a bit lost about how this will all work as a leap second passes.

(The lazy part of me says that it's increasingly less likely that we'll even *see* any more leap second before they're supposed to be abolished within the next decade, so should we even bother? But that's probably not a great approach).

Quoted 8 lines
Quoted 5 lines

(I guess maybe a non-integer value of the tai_offset field might be used to infer that, but I have concerns about that too, because surely that can't be atomically read *with* a given clock pairing, and will be constantly changing during the smearing period?)

With a message-based clock read, the device should be able to calculate the offset.

That's true. Makes me think that perhaps we should insist on only true UTC being advertised as the "primary" clock, with that delta-to-smeared value being exposed too, so that a consumer who wants that can add it.

It harmonises the message-based with the shared-memory approaches while still allowing smeared time, which seems attractive?

Quoted 1 line

For SHM, the vmclock approach appears more suitable.

We do have atomicity of reads with the vmclock approach, by virtue of the seq_count field. That's needed to ensure that a given TSC read is *within* the time period where the absence of disruption is guaranteed.

What's hard is that the rate of change of TAI/UTC offset would have to be indicated *separately*. And it might not be linear.

Quoted 10 lines
Quoted 9 lines

device-types/rtc/description.tex \subsubsection{Control Requests}\label{sec:Device Types / RTC Device / Device Op · line 534

Quoted 5 lines
device-types/rtc/description.tex +3 -0
+In field \field{flags}, VIRTIO_RTC_FLAG_SMEAR indicates whether a leap
+second would be, or is being, smeared into the clock, rather than being
+inserted according to the UTC standard.

"would be"... didn't we already indicate that with the clock type and subtype? Perhaps we use this for "is being" and it resolves my above concern?

Quoted 7 lines

As discussed above, whether smearing is being done would be signaled by the leap member.

In the case of VIRTIO_RTC_CLOCK_MAYBE_SMEARED, VIRTIO_RTC_FLAG_SMEAR would still add extra information to distinguish smearing from not smearing (but as discussed above, the leap values might be extended to distinguish not smearing and smearing).

I'm not entirely clear on what the 'MAYBE' is for. It seems like a "I found a clock lying on the floor and I'm advertising it to you but I have no real idea if you can trust it when leap seconds happen; I don't know if it smears or not. Maybe just don't trust it at all for a day or so around a leap second, eh?"

If the producer doesn't *know* if it's smearing, how would it set the SMEAR flag? And if the producer *does* know that it'll smear, why say MAYBE?

The more I think about it, the more I hate that MAYBE case. I think anyone advertising a precision clock probably ought to *know* how it's going to behave!

Quoted 46 lines
Quoted 6 lines

I think I'd also like to have a 'LEAP_POST_POS' and 'LEAP_POST_NEG' flag which are set for a period of time *after* the occurrence of a leap second. That's helpful for a client to be able to produce a smeared clock when the device is exposing true UTC.

Ack.

Quoted 9 lines
Quoted 9 lines
device-types/rtc/description.tex +9 -0
+A clock of subtype VIRTIO_RTC_SUBTYPE_LEAP_UNSPECIFIED can set
+\field{leap} to VIRTIO_RTC_LEAP_NONE regardless of the clock's actual
+leap second state. For clocks of subtype
+VIRTIO_RTC_SUBTYPE_LEAP_UNSPECIFIED, the VIRTIO_RTC_FLAG_SMEAR flag is
+only guaranteed to be correct while \field{leap} is not
+VIRTIO_RTC_LEAP_NONE.
+
+\subparagraph{TAI Offset}
+
Quoted 9 lines

device-types/rtc/description.tex \subsubsection{Control Requests}\label{sec:Device Types / RTC Device / Device Op · line 549

Quoted 5 lines
device-types/rtc/description.tex +5 -0
+The \field{struct virtio_rtc_data_utc.tai_offset} field indicates the
+offset of the clock from the TAI standard, in the form
+$\mbox{tai_offset} = \mbox{TAI} - \mbox{UTC}$. The offset unit is ns.
+The offset is an integer multiple of a billion ns, i.e.\ corresponds to
+whole seconds, except while the clock is being smeared.

There isn't any fundamental reason why this value can't be signed, is there?

No, it is only that all current Virtio types are unsigned. Introducing a signed value might require extending the generic specification.

Quoted 5 lines

device-types/rtc/description.tex \subsubsection{Control Requests}\label{sec:Device Types / RTC Device / Device Op · line 555

Quoted 5 lines
device-types/rtc/description.tex +5 -0
+If flag VIRTIO_RTC_FLAG_SMEAR is set, and field \field{leap} equals
+VIRTIO_RTC_LEAP_POS, or VIRTIO_RTC_LEAP_NEG, the offset from TAI does
+not correspond to whole seconds.\footnote{This keeps the impact of the
+       leap second insertion on the UTC offset from TAI unambiguous for
+       every sample of \field{struct virtio_rtc_data_utc}.}

I think the above stipulation should be removed, it causes unnecessary limitations.

Quoted 5 lines

See question above about the atomicity of this w.r.t any given clock reading. Do we have to return this whole struct virtio_rtc_data_utc as part of every clock reading?

Quoted 4 lines

The idea was to return struct virtio_rtc_data_utc with every VIRTIO_RTC_REQ_READ_CROSS message response (for UTC or smearing clocks), or to clear VIRTIO_RTC_FLAG_TAI_OFFSET. Supporting that message is not mandatory.

Aha, OK. That makes sense.

Do you have a public git tree with your latest versions of the virtio- rtc specification as it evolves, and/or the Linux support?

#16 lore raw

Re: [RFC PATCH v4 5/5] virtio-rtc: Indicate leap seconds and clock performance

Quoted 15 lines · David Woodhouse
Quoted 9 lines · Peter Hilber
Quoted 7 lines · David Woodhouse

device-types/rtc/description.tex \subsubsection{Control Requests}\label{sec:Device Types / RTC Device / Device Op · line 523

Quoted 3 lines · Peter Hilber
device-types/rtc/description.tex +3 -0
+VIRTIO_RTC_LEAP_PRE_POS resp.\ VIRTIO_RTC_LEAP_PRE_NEG pre-announce a
+positive resp.\ negative leap second. Pre-announcing starts at the
+earliest at the 17th day of the month including the leap second.

Where does 17th come from? Is there an existing precedent for that?

Quoted 4 lines

It doesn't come from anywhere. I set it to the second half of the month to disambiguate pre-announcing, in case a particular smearing algorithm would only start smearing on the day after the leap second (at the start of the month).

Quoted 5 lines

The day *after* the leap second shouldn't be considered "pre- announcement", should it? Wouldn't that be another case for the VIRTIO_RTC_LEAP_POST_{POS,NEG} that I requested? It is notification of a leap second which occurred in the recent past, for which smearing activity may still be ongoing.

The SHM would always indicate true UTC time so the leap state there would be LEAP_PRE / LEAP / LEAP_POST according to the leap second.

Would you want to indicate the occurrence of the actual leap second also when doing the smearing for the VIRTIO_RTC_REQ_READ_CROSS message? I thought to just indicate the time when smearing is being done.

Quoted 34 lines
Quoted 4 lines

With the correction as per my above response, leap can already indicate this together with VIRTIO_RTC_FLAG_SMEAR. But as I discussed above, it might be better to use dedicated leap values for smearing.

Makes sense. At this point I think as long as we have the POST indications I can align the shared structure with your method of indicating leap seconds.

The pre-announcement of a leap second at the end of the month is hard to consume within the PTP driver. At the end of the *day* is easy enough as it's just a case of dividing by 86400. Months are a lot harder, and involve knowledge of leap years and other complexity.

But if the complexity all falls in userspace, and we only expose that "leap at end of month" pre-announcement to userspace and expect userspace to work out *which* second that is and tell the kernel, perhaps that's OK? I'm still a bit lost about how this will all work as a leap second passes.

(The lazy part of me says that it's increasingly less likely that we'll even *see* any more leap second before they're supposed to be abolished within the next decade, so should we even bother? But that's probably not a great approach).

Quoted 8 lines
Quoted 5 lines

(I guess maybe a non-integer value of the tai_offset field might be used to infer that, but I have concerns about that too, because surely that can't be atomically read *with* a given clock pairing, and will be constantly changing during the smearing period?)

With a message-based clock read, the device should be able to calculate the offset.

Quoted 7 lines

That's true. Makes me think that perhaps we should insist on only true UTC being advertised as the "primary" clock, with that delta-to-smeared value being exposed too, so that a consumer who wants that can add it.

It harmonises the message-based with the shared-memory approaches while still allowing smeared time, which seems attractive?

Advertising UTC as the primary clock would mean that the simple VIRTIO_RTC_REQ_READ message could not tell smeared time any more (or at least not so simply). I would prefer to retain the possibility to have simple implementations.

Quoted 33 lines
Quoted 1 line

For SHM, the vmclock approach appears more suitable.

We do have atomicity of reads with the vmclock approach, by virtue of the seq_count field. That's needed to ensure that a given TSC read is *within* the time period where the absence of disruption is guaranteed.

What's hard is that the rate of change of TAI/UTC offset would have to be indicated *separately*. And it might not be linear.

Quoted 10 lines
Quoted 9 lines

device-types/rtc/description.tex \subsubsection{Control Requests}\label{sec:Device Types / RTC Device / Device Op · line 534

Quoted 5 lines
device-types/rtc/description.tex +3 -0
+In field \field{flags}, VIRTIO_RTC_FLAG_SMEAR indicates whether a leap
+second would be, or is being, smeared into the clock, rather than being
+inserted according to the UTC standard.

"would be"... didn't we already indicate that with the clock type and subtype? Perhaps we use this for "is being" and it resolves my above concern?

Quoted 7 lines

As discussed above, whether smearing is being done would be signaled by the leap member.

In the case of VIRTIO_RTC_CLOCK_MAYBE_SMEARED, VIRTIO_RTC_FLAG_SMEAR would still add extra information to distinguish smearing from not smearing (but as discussed above, the leap values might be extended to distinguish not smearing and smearing).

I'm not entirely clear on what the 'MAYBE' is for. It seems like a "I found a clock lying on the floor and I'm advertising it to you but I have no real idea if you can trust it when leap seconds happen; I don't know if it smears or not. Maybe just don't trust it at all for a day or so around a leap second, eh?"

Quoted 3 lines

If the producer doesn't *know* if it's smearing, how would it set the SMEAR flag? And if the producer *does* know that it'll smear, why say MAYBE?

That is the point: The producer may smear but not know that, by getting the time from an external entity, and therefore not set the SMEAR flag. For the driver which only cares about tight synchronization to the producer this might be acceptable.

Quoted 6 lines

The more I think about it, the more I hate that MAYBE case. I think anyone advertising a precision clock probably ought to *know* how it's going to behave!

[...]

maintainer
#17 lore raw

Re: [RFC PATCH v4 5/5] virtio-rtc: Indicate leap seconds and clock performance

Quoted 22 lines · Peter Hilber
Quoted 15 lines · David Woodhouse
Quoted 9 lines · Peter Hilber
Quoted 7 lines · David Woodhouse

device-types/rtc/description.tex \subsubsection{Control Requests}\label{sec:Device Types / RTC Device / Device Op · line 523

Quoted 3 lines · Peter Hilber
device-types/rtc/description.tex +3 -0
+VIRTIO_RTC_LEAP_PRE_POS resp.\ VIRTIO_RTC_LEAP_PRE_NEG pre-announce a
+positive resp.\ negative leap second. Pre-announcing starts at the
+earliest at the 17th day of the month including the leap second.

Where does 17th come from? Is there an existing precedent for that?

Quoted 4 lines

It doesn't come from anywhere. I set it to the second half of the month to disambiguate pre-announcing, in case a particular smearing algorithm would only start smearing on the day after the leap second (at the start of the month).

Quoted 5 lines

The day *after* the leap second shouldn't be considered "pre- announcement", should it? Wouldn't that be another case for the VIRTIO_RTC_LEAP_POST_{POS,NEG} that I requested? It is notification of a leap second which occurred in the recent past, for which smearing activity may still be ongoing.

Quoted 6 lines

The SHM would always indicate true UTC time so the leap state there would be LEAP_PRE / LEAP / LEAP_POST according to the leap second.

Would you want to indicate the occurrence of the actual leap second also when doing the smearing for the VIRTIO_RTC_REQ_READ_CROSS message? I thought to just indicate the time when smearing is being done.

I think that just indicating the time when smearing is being done is sufficient.

That tells the consumer when the returned time is not accurate UTC and any calibration of a counter is going to experience some deliberately induced frequency 'error', and that's what's important.

If we're putting the onus on userspace to cope, we might reasonably expect userspace to know exactly *how* its apparent counter frequency is going to jump, e.g. by ~12PPM at the start of smearing, and back again in the opposite direction at the end.

The main thing I want to ensure we think about is a guest which is powered up in the moments after midnight, when smearing is still being done (in the case of virtio-rtc exposing a smeared clock) or still *needs* to be done (in the case of the guest doing the smearing for itself).

In that case, the guest may not have seen the pre-announcements of the leap second which is now supposed to be historical. But still needs to consume the clock information accordingly, until the smearing period ends.

So exposing a SMEAR flag whenever the clock is actually being smeared is fine, and also a POST_POS and POST_NEG flag to allow the guest to do so when the clock it's being given is true UTC and has already stepped.

maintainer
#18 lore raw

Re: [RFC PATCH v4 5/5] virtio-rtc: Indicate leap seconds and clock performance

In reply to Peter Hilber

Thanks for the continuing feedback, Peter. Since it's only changes to comments, I won't post a whole new version; I've pushed the following changes to the git tree.

I believe I understood correctly that you're amenable to adding the VIRTIO_RTC_POST_ values? And I think the other part of the discussion about exposing ongoing smearing via this field does not affect its usage in SHM?

With this, I think we're at a point where I can seriously propose this be adopted into your virtio-rtc specification? Do you have that in a public git tree that I can work from to provide an actual patch?

We need it to be explicitly little-endian, of course, but I consider that an implementation detail. Likewise the signedness of the tai_offset field, which *can* be expressed (albeit creatively) within the constraints of the existing virtio definitions.

It's versioned anyway, so as long as it looks *reasonable* I'd like to go ahead and submit the ACPI version of it to QEMU and the kernel (and obviously also ship it in the hypervisor that pays my bills), in the expectation that *if* it did need further revision before the final publication of the virtio-rtc specification, that should be feasible. But the *intent* is that it doesn't need to change, of course.

Are you happy with that in concept?

include/uapi/linux/vmclock-abi.h +27 -26
index 84f0e37a8a06..d7ca44313bf8 100644
@@ -106,19 +106,17 @@ struct vmclock_abi {
 #define VMCLOCK_FLAG_TIME_ESTERROR_VALID	(1 << 5)
 #define VMCLOCK_FLAG_TIME_MAXERROR_VALID	(1 << 6)
 	/*
-	 * Even regardless of leap seconds, the time presented through this
-	 * mechanism may not be strictly monotonic. If the counter slows down
-	 * and the host adapts to this discovery, the time calculated from
-	 * the value of the counter immediately after an update to this
-	 * structure, may appear to be *earlier* than a calculation just
-	 * before the update (while the counter was believed to be running
-	 * faster than it now is). A guest operating system will typically
-	 * *skew* its own system clock back towards the reference clock
-	 * exposed here, rather than following this clock directly. If,
-	 * however, this structure is being populated from such a system
-	 * clock which is already handled in such a fashion and the results
-	 * *are* guaranteed to be monotonic, such monotonicity can be
-	 * advertised by setting this bit.
+	 * If the MONOTONIC flag is set then (other than leap seconds) it is
+	 * guaranteed that the time calculated according this structure at
+	 * any given moment shall never appear to be later than the time
+	 * calculated via the structure at any *later* moment.
+	 *
+	 * In particular, a timestamp based on a counter reading taken
+	 * immediately after setting the low bit of seq_count (and the
+	 * associated memory barrier), using the previously-valid time and
+	 * period fields, shall never be later than a timestamp based on
+	 * a counter reading taken immediately before *clearing* the low
+	 * bit again after the update, using the about-to-be-valid fields.
 	 */
 #define VMCLOCK_FLAG_TIME_MONOTONIC		(1 << 7)
 
@@ -136,28 +134,31 @@ struct vmclock_abi {
 	 * the smearing method. However in this case it provides a *hint* to
 	 * the guest operating system, such that *if* the guest OS wants to
 	 * provide its users with an alternative clock which does not follow
-	 * the POSIX CLOCK_REALTIME standard, it may do so in a fashion
-	 * consistent with the other systems in the nearby environment.
+	 * UTC, it may do so in a fashion consistent with the other systems
+	 * in the nearby environment.
 	 */
 	uint8_t leap_second_smearing_hint; /* Matches VIRTIO_RTC_SUBTYPE_xxx */
 #define VMCLOCK_SMEARING_STRICT		0
 #define VMCLOCK_SMEARING_NOON_LINEAR	1
 #define VMCLOCK_SMEARING_UTC_SLS	2
 	int16_t tai_offset_sec;
-	uint8_t leap_indicator; /* Based on VIRTIO_RTC_LEAP_xxx */
+	uint8_t leap_indicator;
+	/*
+	 * This field is based on the the VIRTIO_RTC_LEAP_xxx values as
+	 * defined in the current draft of virtio-rtc, but since smearing
+	 * cannot be used with the shared memory device, some values (_NEG)
+	 * are not used.
+	 *
+	 * The _POST_POS and _POST_NEG values are added in order to allow the
+	 * guest to perform its own smearing during the day or so after a
+	 * leap second when such smearing may need to continue being applied.
+	 * It is hoped that these will be incorporated into virtio-rtc too.
+	 */
 #define VMCLOCK_LEAP_NONE	0	/* No known nearby leap second */
-#define VMCLOCK_LEAP_PRE_POS	1	/* Leap second + at end of month */
-#define VMCLOCK_LEAP_PRE_NEG	2	/* Leap second - at end of month */
+#define VMCLOCK_LEAP_PRE_POS	1	/* Positive leap second at EOM */
+#define VMCLOCK_LEAP_PRE_NEG	2	/* Negative leap second at EOM */
 #define VMCLOCK_LEAP_POS	3	/* Set during 23:59:60 second */
 #define VMCLOCK_LEAP_NEG	4	/* Not used in VMCLOCK */
-	/*
-	 * These values are not (yet) in virtio-rtc. They indicate that a
-	 * leap second *has* occurred at the start of the month. This allows
-	 * a guest to generate a smeared clock from the accurate clock which
-	 * this device provides, as smearing may need to continue for up to a
-	 * period of time *after* the point of the leap second itself. Must
-	 * be cleared by the 15th day of the month.
-	 */
 #define VMCLOCK_LEAP_POST_POS	5
 #define VMCLOCK_LEAP_POST_NEG	6
 
#19 lore raw

Re: [RFC PATCH v4 5/5] virtio-rtc: Indicate leap seconds and clock performance

Quoted 8 lines · David Woodhouse

Thanks for the continuing feedback, Peter. Since it's only changes to comments, I won't post a whole new version; I've pushed the following changes to the git tree.

I believe I understood correctly that you're amenable to adding the VIRTIO_RTC_POST_ values? And I think the other part of the discussion about exposing ongoing smearing via this field does not affect its usage in SHM?

I will add the VIRTIO_RTC_POST_ values. But I think for the leap second smearing case I would also add more values, like

#define VIRTIO_RTC_LEAP_NONE            0x00
#define VIRTIO_RTC_LEAP_PRE_POS         0x01
#define VIRTIO_RTC_LEAP_PRE_NEG         0x02
#define VIRTIO_RTC_LEAP_POS             0x03
#define VIRTIO_RTC_LEAP_POST_POS        0x04
#define VIRTIO_RTC_LEAP_POST_NEG        0x05
#define VIRTIO_RTC_LEAP_SMEAR_PRE_POS   0x06
#define VIRTIO_RTC_LEAP_SMEAR_PRE_NEG   0x07
#define VIRTIO_RTC_LEAP_SMEAR_POS       0x08
#define VIRTIO_RTC_LEAP_SMEAR_NEG       0x09
#define VIRTIO_RTC_LEAP_SMEAR_POST_POS  0x0A
#define VIRTIO_RTC_LEAP_SMEAR_POST_NEG  0x0B

So maybe the VIRTIO_RTC_LEAP_NEG definition could be removed from vmclock. The other changes would not be relevant to vmclock.

Quoted 5 lines

With this, I think we're at a point where I can seriously propose this be adopted into your virtio-rtc specification? Do you have that in a public git tree that I can work from to provide an actual patch?

I am sorry, but I think I will not be able to publish a specification update until I go on vacation. I will be back in the week of August 5th.

Quoted 5 lines

We need it to be explicitly little-endian, of course, but I consider that an implementation detail. Likewise the signedness of the tai_offset field, which *can* be expressed (albeit creatively) within the constraints of the existing virtio definitions.

Quoted 8 lines

It's versioned anyway, so as long as it looks *reasonable* I'd like to go ahead and submit the ACPI version of it to QEMU and the kernel (and obviously also ship it in the hypervisor that pays my bills), in the expectation that *if* it did need further revision before the final publication of the virtio-rtc specification, that should be feasible. But the *intent* is that it doesn't need to change, of course.

Are you happy with that in concept?

Some of the bit widths and defines do not match at the moment. I think it might be worth to align those (from vmclock-abi.h):

- counter_id vs u16
- VMCLOCK_COUNTER_INVALID
- time_type vs u16

maintainer
#20 lore raw

Re: [RFC PATCH v4 5/5] virtio-rtc: Indicate leap seconds and clock performance

Quoted 26 lines · Peter Hilber
Quoted 8 lines · David Woodhouse

Thanks for the continuing feedback, Peter. Since it's only changes to comments, I won't post a whole new version; I've pushed the following changes to the git tree.

I believe I understood correctly that you're amenable to adding the VIRTIO_RTC_POST_ values? And I think the other part of the discussion about exposing ongoing smearing via this field does not affect its usage in SHM?

I will add the VIRTIO_RTC_POST_ values. But I think for the leap second smearing case I would also add more values, like

#define VIRTIO_RTC_LEAP_NONE            0x00
#define VIRTIO_RTC_LEAP_PRE_POS         0x01
#define VIRTIO_RTC_LEAP_PRE_NEG         0x02
#define VIRTIO_RTC_LEAP_POS             0x03
#define VIRTIO_RTC_LEAP_POST_POS        0x04
#define VIRTIO_RTC_LEAP_POST_NEG        0x05
#define VIRTIO_RTC_LEAP_SMEAR_PRE_POS   0x06
#define VIRTIO_RTC_LEAP_SMEAR_PRE_NEG   0x07
#define VIRTIO_RTC_LEAP_SMEAR_POS       0x08
#define VIRTIO_RTC_LEAP_SMEAR_NEG       0x09
#define VIRTIO_RTC_LEAP_SMEAR_POST_POS  0x0A
#define VIRTIO_RTC_LEAP_SMEAR_POST_NEG  0x0B

Quoted 2 lines

So maybe the VIRTIO_RTC_LEAP_NEG definition could be removed from vmclock. The other changes would not be relevant to vmclock.

Almost makes me want to suggest that the _SMEAR_ values should have constant offset of 0x8 from the corresponding values without the SMEAR, as if we're treating SMEAR as a *flag* bit.

That could be useful as it would indicate that the time returned by this mechanism is not actually UTC.

Quoted 8 lines
Quoted 5 lines

With this, I think we're at a point where I can seriously propose this be adopted into your virtio-rtc specification? Do you have that in a public git tree that I can work from to provide an actual patch?

I am sorry, but I think I will not be able to publish a specification update until I go on vacation. I will be back in the week of August 5th.

Have fun! I'm already on vacation this week, but I haven't yet seen any of my colleagues engage with this thread, so I'm having to do it myself.

Quoted 12 lines
Quoted 12 lines

We need it to be explicitly little-endian, of course, but I consider that an implementation detail. Likewise the signedness of the tai_offset field, which *can* be expressed (albeit creatively) within the constraints of the existing virtio definitions.

It's versioned anyway, so as long as it looks *reasonable* I'd like to go ahead and submit the ACPI version of it to QEMU and the kernel (and obviously also ship it in the hypervisor that pays my bills), in the expectation that *if* it did need further revision before the final publication of the virtio-rtc specification, that should be feasible. But the *intent* is that it doesn't need to change, of course.

Quoted 8 lines
Quoted 1 line

Are you happy with that in concept?

Some of the bit widths and defines do not match at the moment. I think it might be worth to align those (from vmclock-abi.h):

- counter_id vs u16
- VMCLOCK_COUNTER_INVALID
- time_type vs u16

Deployment timelines aside (I may or may not have used the current proposed version in an internal-only release for widespread full-stack testing...), I suppose I have no fundamental aversion to expanding those to 16-bit. Although we have about *three* possible values for each of them right now. I can't see how we'll ever get past about a dozen counters, and with smearing in a separate subtype I can't see how we get any more values of time_type either. A single byte really ought to suffice, surely? Can we stick with u8?

But we do have a couple of bytes of pad[] so if you feel strongly, we could use the two bytes after version for one of them, and the two bytes of pad[] for the other.

I quite liked keeping those as constant fields above the seq_count though.

I'd like to have VMCLOCK_COUNTER_INVALID added please; I meant to point that out explicitly. We need a way to indicate that there is *no* valid time being exposed through this structure and that it is *only* for indicating disruption (which is the most critical thing for now). And even if there's a separate flag for that, putting an explicit counter ID into the field would still seem wrong.

I'll be happiest if any changes we make do remain compatible, for "disruption only" mode, with an implementation which gives 0xFF and 0x00 in the current counter_id and time_type bytes. Maybe we make that counter_id and use 0x00FF as VMCLOCK_COUNTER_INVALID?

#21 lore raw

Re: [RFC PATCH v4 5/5] virtio-rtc: Indicate leap seconds and clock performance

Quoted 30 lines · David Woodhouse
Quoted 26 lines · Peter Hilber
Quoted 8 lines · David Woodhouse

Thanks for the continuing feedback, Peter. Since it's only changes to comments, I won't post a whole new version; I've pushed the following changes to the git tree.

I believe I understood correctly that you're amenable to adding the VIRTIO_RTC_POST_ values? And I think the other part of the discussion about exposing ongoing smearing via this field does not affect its usage in SHM?

I will add the VIRTIO_RTC_POST_ values. But I think for the leap second smearing case I would also add more values, like

#define VIRTIO_RTC_LEAP_NONE            0x00
#define VIRTIO_RTC_LEAP_PRE_POS         0x01
#define VIRTIO_RTC_LEAP_PRE_NEG         0x02
#define VIRTIO_RTC_LEAP_POS             0x03
#define VIRTIO_RTC_LEAP_POST_POS        0x04
#define VIRTIO_RTC_LEAP_POST_NEG        0x05
#define VIRTIO_RTC_LEAP_SMEAR_PRE_POS   0x06
#define VIRTIO_RTC_LEAP_SMEAR_PRE_NEG   0x07
#define VIRTIO_RTC_LEAP_SMEAR_POS       0x08
#define VIRTIO_RTC_LEAP_SMEAR_NEG       0x09
#define VIRTIO_RTC_LEAP_SMEAR_POST_POS  0x0A
#define VIRTIO_RTC_LEAP_SMEAR_POST_NEG  0x0B

Quoted 2 lines

So maybe the VIRTIO_RTC_LEAP_NEG definition could be removed from vmclock. The other changes would not be relevant to vmclock.

Quoted 7 lines

Almost makes me want to suggest that the _SMEAR_ values should have constant offset of 0x8 from the corresponding values without the SMEAR, as if we're treating SMEAR as a *flag* bit.

That could be useful as it would indicate that the time returned by this mechanism is not actually UTC.

Only VIRTIO_RTC_LEAP_SMEAR_POS and VIRTIO_RTC_LEAP_SMEAR_NEG would indicate that the time is actually smeared, the rest is just pre-/post-announcement.

But if you think it's useful, I could still have all the VIRTIO_RTC_LEAP_SMEAR_ indications have the 0x08 bit and offset.

Quoted 34 lines
Quoted 8 lines
Quoted 5 lines

With this, I think we're at a point where I can seriously propose this be adopted into your virtio-rtc specification? Do you have that in a public git tree that I can work from to provide an actual patch?

I am sorry, but I think I will not be able to publish a specification update until I go on vacation. I will be back in the week of August 5th.

Have fun! I'm already on vacation this week, but I haven't yet seen any of my colleagues engage with this thread, so I'm having to do it myself.

Quoted 12 lines
Quoted 12 lines

We need it to be explicitly little-endian, of course, but I consider that an implementation detail. Likewise the signedness of the tai_offset field, which *can* be expressed (albeit creatively) within the constraints of the existing virtio definitions.

It's versioned anyway, so as long as it looks *reasonable* I'd like to go ahead and submit the ACPI version of it to QEMU and the kernel (and obviously also ship it in the hypervisor that pays my bills), in the expectation that *if* it did need further revision before the final publication of the virtio-rtc specification, that should be feasible. But the *intent* is that it doesn't need to change, of course.

Quoted 8 lines
Quoted 1 line

Are you happy with that in concept?

Some of the bit widths and defines do not match at the moment. I think it might be worth to align those (from vmclock-abi.h):

- counter_id vs u16
- VMCLOCK_COUNTER_INVALID
- time_type vs u16

Quoted 8 lines

Deployment timelines aside (I may or may not have used the current proposed version in an internal-only release for widespread full-stack testing...), I suppose I have no fundamental aversion to expanding those to 16-bit. Although we have about *three* possible values for each of them right now. I can't see how we'll ever get past about a dozen counters, and with smearing in a separate subtype I can't see how we get any more values of time_type either. A single byte really ought to suffice, surely? Can we stick with u8?

OK.

Quoted 15 lines

But we do have a couple of bytes of pad[] so if you feel strongly, we could use the two bytes after version for one of them, and the two bytes of pad[] for the other.

I quite liked keeping those as constant fields above the seq_count though.

I'd like to have VMCLOCK_COUNTER_INVALID added please; I meant to point that out explicitly. We need a way to indicate that there is *no* valid time being exposed through this structure and that it is *only* for indicating disruption (which is the most critical thing for now). And even if there's a separate flag for that, putting an explicit counter ID into the field would still seem wrong.

Quoted 6 lines

I'll be happiest if any changes we make do remain compatible, for "disruption only" mode, with an implementation which gives 0xFF and 0x00 in the current counter_id and time_type bytes. Maybe we make that counter_id and use 0x00FF as VMCLOCK_COUNTER_INVALID?

OK.

maintainer
#22 lore raw

Re: [RFC PATCH v4 5/5] virtio-rtc: Indicate leap seconds and clock performance

Quoted 39 lines · Peter Hilber
Quoted 30 lines · David Woodhouse
Quoted 26 lines · Peter Hilber
Quoted 8 lines · David Woodhouse

Thanks for the continuing feedback, Peter. Since it's only changes to comments, I won't post a whole new version; I've pushed the following changes to the git tree.

I believe I understood correctly that you're amenable to adding the VIRTIO_RTC_POST_ values? And I think the other part of the discussion about exposing ongoing smearing via this field does not affect its usage in SHM?

I will add the VIRTIO_RTC_POST_ values. But I think for the leap second smearing case I would also add more values, like

#define VIRTIO_RTC_LEAP_NONE            0x00
#define VIRTIO_RTC_LEAP_PRE_POS         0x01
#define VIRTIO_RTC_LEAP_PRE_NEG         0x02
#define VIRTIO_RTC_LEAP_POS             0x03
#define VIRTIO_RTC_LEAP_POST_POS        0x04
#define VIRTIO_RTC_LEAP_POST_NEG        0x05
#define VIRTIO_RTC_LEAP_SMEAR_PRE_POS   0x06
#define VIRTIO_RTC_LEAP_SMEAR_PRE_NEG   0x07
#define VIRTIO_RTC_LEAP_SMEAR_POS       0x08
#define VIRTIO_RTC_LEAP_SMEAR_NEG       0x09
#define VIRTIO_RTC_LEAP_SMEAR_POST_POS  0x0A
#define VIRTIO_RTC_LEAP_SMEAR_POST_NEG  0x0B

Quoted 2 lines

So maybe the VIRTIO_RTC_LEAP_NEG definition could be removed from vmclock. The other changes would not be relevant to vmclock.

Quoted 7 lines

Almost makes me want to suggest that the _SMEAR_ values should have constant offset of 0x8 from the corresponding values without the SMEAR, as if we're treating SMEAR as a *flag* bit.

That could be useful as it would indicate that the time returned by this mechanism is not actually UTC.

Quoted 5 lines

Only VIRTIO_RTC_LEAP_SMEAR_POS and VIRTIO_RTC_LEAP_SMEAR_NEG would indicate that the time is actually smeared, the rest is just pre-/post-announcement.

But if you think it's useful, I could still have all the VIRTIO_RTC_LEAP_SMEAR_ indications have the 0x08 bit and offset.

My thought was that the 0x8 bit would be the simplest indication that the time is not UTC, so including the pre/post announcements *outside* the smearing period would be less useful for that? But that's just a thought; do with it what you feel best.

Quoted 60 lines
Quoted 34 lines
Quoted 8 lines
Quoted 5 lines

With this, I think we're at a point where I can seriously propose this be adopted into your virtio-rtc specification? Do you have that in a public git tree that I can work from to provide an actual patch?

I am sorry, but I think I will not be able to publish a specification update until I go on vacation. I will be back in the week of August 5th.

Have fun! I'm already on vacation this week, but I haven't yet seen any of my colleagues engage with this thread, so I'm having to do it myself.

Quoted 12 lines
Quoted 12 lines

We need it to be explicitly little-endian, of course, but I consider that an implementation detail. Likewise the signedness of the tai_offset field, which *can* be expressed (albeit creatively) within the constraints of the existing virtio definitions.

It's versioned anyway, so as long as it looks *reasonable* I'd like to go ahead and submit the ACPI version of it to QEMU and the kernel (and obviously also ship it in the hypervisor that pays my bills), in the expectation that *if* it did need further revision before the final publication of the virtio-rtc specification, that should be feasible. But the *intent* is that it doesn't need to change, of course.

Quoted 8 lines
Quoted 1 line

Are you happy with that in concept?

Some of the bit widths and defines do not match at the moment. I think it might be worth to align those (from vmclock-abi.h):

- counter_id vs u16
- VMCLOCK_COUNTER_INVALID
- time_type vs u16

Quoted 8 lines

Deployment timelines aside (I may or may not have used the current proposed version in an internal-only release for widespread full-stack testing...), I suppose I have no fundamental aversion to expanding those to 16-bit. Although we have about *three* possible values for each of them right now. I can't see how we'll ever get past about a dozen counters, and with smearing in a separate subtype I can't see how we get any more values of time_type either. A single byte really ought to suffice, surely? Can we stick with u8?

OK.

Quoted 15 lines

But we do have a couple of bytes of pad[] so if you feel strongly, we could use the two bytes after version for one of them, and the two bytes of pad[] for the other.

I quite liked keeping those as constant fields above the seq_count though.

I'd like to have VMCLOCK_COUNTER_INVALID added please; I meant to point that out explicitly. We need a way to indicate that there is *no* valid time being exposed through this structure and that it is *only* for indicating disruption (which is the most critical thing for now). And even if there's a separate flag for that, putting an explicit counter ID into the field would still seem wrong.

Quoted 9 lines
Quoted 6 lines

I'll be happiest if any changes we make do remain compatible, for "disruption only" mode, with an implementation which gives 0xFF and 0x00 in the current counter_id and time_type bytes. Maybe we make that counter_id and use 0x00FF as VMCLOCK_COUNTER_INVALID?

OK.

Did you just say OK to two different alternatives? Can we take the first; just stick with u8 for both fields as we'll never need any more?

#23 lore raw

Re: [RFC PATCH v4 5/5] virtio-rtc: Indicate leap seconds and clock performance

Quoted 4 lines · David Woodhouse
Quoted 3 lines · Peter Hilber
Quoted 2 lines · David Woodhouse
Quoted 1 line · Peter Hilber

On 11.07.24 12:18, David Woodhouse wrote:

[...]

Quoted 57 lines
Quoted 57 lines
Quoted 21 lines
Quoted 12 lines
Quoted 12 lines

We need it to be explicitly little-endian, of course, but I consider that an implementation detail. Likewise the signedness of the tai_offset field, which *can* be expressed (albeit creatively) within the constraints of the existing virtio definitions.

It's versioned anyway, so as long as it looks *reasonable* I'd like to go ahead and submit the ACPI version of it to QEMU and the kernel (and obviously also ship it in the hypervisor that pays my bills), in the expectation that *if* it did need further revision before the final publication of the virtio-rtc specification, that should be feasible. But the *intent* is that it doesn't need to change, of course.

Quoted 8 lines
Quoted 1 line

Are you happy with that in concept?

Some of the bit widths and defines do not match at the moment. I think it might be worth to align those (from vmclock-abi.h):

- counter_id vs u16
- VMCLOCK_COUNTER_INVALID
- time_type vs u16

Quoted 8 lines

Deployment timelines aside (I may or may not have used the current proposed version in an internal-only release for widespread full-stack testing...), I suppose I have no fundamental aversion to expanding those to 16-bit. Although we have about *three* possible values for each of them right now. I can't see how we'll ever get past about a dozen counters, and with smearing in a separate subtype I can't see how we get any more values of time_type either. A single byte really ought to suffice, surely? Can we stick with u8?

OK.

Quoted 24 lines

But we do have a couple of bytes of pad[] so if you feel strongly, we could use the two bytes after version for one of them, and the two bytes of pad[] for the other.

I quite liked keeping those as constant fields above the seq_count though.

I'd like to have VMCLOCK_COUNTER_INVALID added please; I meant to point that out explicitly. We need a way to indicate that there is *no* valid time being exposed through this structure and that it is *only* for indicating disruption (which is the most critical thing for now). And even if there's a separate flag for that, putting an explicit counter ID into the field would still seem wrong.

I'll be happiest if any changes we make do remain compatible, for "disruption only" mode, with an implementation which gives 0xFF and 0x00 in the current counter_id and time_type bytes. Maybe we make that counter_id and use 0x00FF as VMCLOCK_COUNTER_INVALID?

Quoted 5 lines
Quoted 2 lines

OK.

Did you just say OK to two different alternatives? Can we take the first; just stick with u8 for both fields as we'll never need any more?

I intended to say OK to the first alternative, and to define the counter value 0xFF as VMCLOCK_COUNTER_INVALID resp. VIRTIO_RTC_COUNTER_INVALID.

maintainer
#24 lore raw

Re: [RFC PATCH v4 5/5] virtio-rtc: Indicate leap seconds and clock performance

Quoted 6 lines · Peter Hilber
Quoted 2 lines · David Woodhouse

Did you just say OK to two different alternatives? Can we take the first; just stick with u8 for both fields as we'll never need any more?

I intended to say OK to the first alternative, and to define the counter value 0xFF as VMCLOCK_COUNTER_INVALID resp. VIRTIO_RTC_COUNTER_INVALID.

Great, I think I had come to that conclusion myself, and that's what I've put into the "final" Linux¹ and QEMU² submissions, as well as shipping to production for my internal early adopters to test with.

Obviously it's all versioned so if we *do* end up having to change something for the final virtio-rtc spec, then we can cope with that. But I'm aspiring not to have to.

Thanks!

¹ https://lore.kernel.org/lkml/[email protected]/
² https://lore.kernel.org/qemu-devel/[email protected]/

maintainer
#25 lore raw
In reply to Peter Hilber
Quoted 2 lines · Peter Hilber

- Drop distinction of Arm Generic Timer virtual and physical counter.

Hm, why so? If you're giving out paired readings of the counter and wallclock time, surely it matters *which* counter?

If a guest has access to both, how can it know which is being used?

#26 lore raw
Quoted 8 lines · David Woodhouse
Quoted 2 lines · Peter Hilber

- Drop distinction of Arm Generic Timer virtual and physical counter.

Hm, why so? If you're giving out paired readings of the counter and wallclock time, surely it matters *which* counter?

If a guest has access to both, how can it know which is being used?

I think it should then use the virtual counter. But maybe there are some corner cases where this will not happen, so I could revert this.

Thanks for the comment,

Peter

maintainer
#27 lore raw
Quoted 5 lines · Peter Hilber
Quoted 4 lines · David Woodhouse
Quoted 2 lines · Peter Hilber

- Drop distinction of Arm Generic Timer virtual and physical counter.

Quoted 7 lines
Quoted 4 lines

Hm, why so? If you're giving out paired readings of the counter and wallclock time, surely it matters *which* counter?

If a guest has access to both, how can it know which is being used?

I think it should then use the virtual counter. But maybe there are some corner cases where this will not happen, so I could revert this.

As long as you explicitly *state* that it shall always use the virtual counter, that's probably OK. As long as there is no ambiguity.

#28 lore raw
Quoted 9 lines · David Woodhouse
Quoted 8 lines · Peter Hilber
Quoted 7 lines · David Woodhouse
Quoted 2 lines · Peter Hilber

- Drop distinction of Arm Generic Timer virtual and physical counter.

Hm, why so? If you're giving out paired readings of the counter and wallclock time, surely it matters *which* counter?

Quoted 7 lines
Quoted 4 lines
Quoted 1 line

If a guest has access to both, how can it know which is being used?

I think it should then use the virtual counter. But maybe there are some corner cases where this will not happen, so I could revert this.

As long as you explicitly *state* that it shall always use the virtual counter, that's probably OK. As long as there is no ambiguity.

I failed to come up with an elegant implementation-independent rule of when to use physical counter and when to use virtual counter. So maybe the spec should indeed just keep both counters separated, and it would be up to the driver implementation to select the proper counter.

maintainer
#29 lore raw
Quoted 15 lines · Peter Hilber
Quoted 14 lines · David Woodhouse
Quoted 12 lines · Peter Hilber
Quoted 8 lines · David Woodhouse
Quoted 2 lines · Peter Hilber

- Drop distinction of Arm Generic Timer virtual and physical counter.

Hm, why so? If you're giving out paired readings of the counter and wallclock time, surely it matters *which* counter?

If a guest has access to both, how can it know which is being used?

I think it should then use the virtual counter. But maybe there are some corner cases where this will not happen, so I could revert this.

Quoted 7 lines
Quoted 2 lines

As long as you explicitly *state* that it shall always use the virtual counter, that's probably OK. As long as there is no ambiguity.

I failed to come up with an elegant implementation-independent rule of when to use physical counter and when to use virtual counter. So maybe the spec should indeed just keep both counters separated, and it would be up to the driver implementation to select the proper counter.

Is there ever a reason to use the physical counter? I think we can just specify that the readings are given in terms of the *virtual* counter, and ignore the physical one.

#30 lore raw
Quoted 19 lines · David Woodhouse
Quoted 18 lines · Peter Hilber
Quoted 16 lines · David Woodhouse
Quoted 5 lines · Peter Hilber
Quoted 4 lines · David Woodhouse
Quoted 2 lines · Peter Hilber

- Drop distinction of Arm Generic Timer virtual and physical counter.

Quoted 7 lines
Quoted 4 lines

Hm, why so? If you're giving out paired readings of the counter and wallclock time, surely it matters *which* counter?

If a guest has access to both, how can it know which is being used?

I think it should then use the virtual counter. But maybe there are some corner cases where this will not happen, so I could revert this.

As long as you explicitly *state* that it shall always use the virtual counter, that's probably OK. As long as there is no ambiguity.

Quoted 9 lines
Quoted 4 lines

I failed to come up with an elegant implementation-independent rule of when to use physical counter and when to use virtual counter. So maybe the spec should indeed just keep both counters separated, and it would be up to the driver implementation to select the proper counter.

Is there ever a reason to use the physical counter? I think we can just specify that the readings are given in terms of the *virtual* counter, and ignore the physical one.

AFAIU such a case could arise in principle when the driver OS is not virtualized by conventional means, and is able to control the virtual counter offset by itself. There is no concrete use case. The physical counter could indeed be omitted for now.

Thanks for the comment,

Peter

maintainer
#31 lore raw
Quoted 30 lines · Peter Hilber
Quoted 19 lines · David Woodhouse
Quoted 18 lines · Peter Hilber
Quoted 16 lines · David Woodhouse
Quoted 5 lines · Peter Hilber
Quoted 4 lines · David Woodhouse
Quoted 2 lines · Peter Hilber

- Drop distinction of Arm Generic Timer virtual and physical counter.

Quoted 7 lines
Quoted 4 lines

Hm, why so? If you're giving out paired readings of the counter and wallclock time, surely it matters *which* counter?

If a guest has access to both, how can it know which is being used?

I think it should then use the virtual counter. But maybe there are some corner cases where this will not happen, so I could revert this.

As long as you explicitly *state* that it shall always use the virtual counter, that's probably OK. As long as there is no ambiguity.

Quoted 9 lines
Quoted 4 lines

I failed to come up with an elegant implementation-independent rule of when to use physical counter and when to use virtual counter. So maybe the spec should indeed just keep both counters separated, and it would be up to the driver implementation to select the proper counter.

Is there ever a reason to use the physical counter? I think we can just specify that the readings are given in terms of the *virtual* counter, and ignore the physical one.

Quoted 4 lines

AFAIU such a case could arise in principle when the driver OS is not virtualized by conventional means, and is able to control the virtual counter offset by itself. There is no concrete use case. The physical counter could indeed be omitted for now.

Agreed. Let's specify that VIRTIO_RTC_COUNTER_ARM means the virtual counter (and perhaps add a _VCT to its name). A physical one can always be added later, if it becomes necessary.

You could imagine physical implementations of the device spec being related to the *physical* counter, much like Intel's Always Running Timer which is visible on the PCI bus and has a mathematical relationship to the TSC. (We might end up adding VIRTIO_RTC_COUNTER_ART for that too, but again I think it can be omitted for now).

maintainer
#32 lore raw
In reply to Peter Hilber
Quoted 13 lines · Peter Hilber

This iteration of the virtio-rtc RFC spec adds leap second indication and performance indication. It also incorporates the results of previous discussions.

While the virtio-comment mailing list was unavailable, a discussion about leap second indication and performance indication took place on the Linux kernel mailing list [1]. As an outcome of this discussion [1], the RFC spec v4 now adds leap second indication and performance indication. The respective changes are for now gathered in patch 5.

Summary
-------

Quoted 6 lines

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 also indicates when and how leap seconds are handled. The driver can read the clocks with simple or more accurate methods. Optionally, the driver can set an alarm.

For the benefit of the virtio-comment@ list, my other observation about this virtio-rtc proposal as it stands was that it doesn't solve the problem of live migration.

Using virtio-rtc as a PHC to calibrate the underlying oscillator (the TSC or arch counter) is all very well... but then you get transparently migrated to a new host and there is a step change in the frequency of that counter (and perhaps a literal step in the value too, depending on the synchronization of the clock between the two hosts).

And then your guest clock is wildly inaccurate for a period of time without you even knowing, until its calibration recovers.

We also end up in a model where potentially hundreds of guests are all duplicating this same work in order to calibrate the *same* underlying oscillator which is exposed to them all.

I proposed a model where we expose a shared memory region to the guest, with a seqlock data structure reporting the actual relationship between the counter and real time ( reference point, frequency, error bounds / synchronization stratum, disruption (LM) indicator ). Cleverer people than me refer to this as a "feed-forward" clock model, if I understand correctly. I think of it more like the vDSO that an OS kernel offers to userspace to allow quick conversions from a counter read to real time.

Peter's response, if I may paraphrase, was that this wasn't the problem he was trying to solve but I was welcome to come up with a more concrete proposal, and he was not fundamentally averse to including that as an optional part of the virtio-rtc proposal.

maintainer
#33 lore raw
Quoted 21 lines · David Woodhouse
Quoted 13 lines · Peter Hilber

This iteration of the virtio-rtc RFC spec adds leap second indication and performance indication. It also incorporates the results of previous discussions.

While the virtio-comment mailing list was unavailable, a discussion about leap second indication and performance indication took place on the Linux kernel mailing list [1]. As an outcome of this discussion [1], the RFC spec v4 now adds leap second indication and performance indication. The respective changes are for now gathered in patch 5.

Summary
-------

Quoted 6 lines

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 also indicates when and how leap seconds are handled. The driver can read the clocks with simple or more accurate methods. Optionally, the driver can set an alarm.

Quoted 3 lines

For the benefit of the virtio-comment@ list, my other observation about this virtio-rtc proposal as it stands was that it doesn't solve the problem of live migration.

I strongly believe that providing yet another precision clock to guests *without* solving the live migration problem is pointless. Here's an attempt at solving it with a shared memory structure.

At
https://git.infradead.org/?p=users/dwmw2/linux.git;a=commitdiff;h=88031b60b1a2341fdbdb0b1e55ad2f9ad47c0c95
I attempt to provide both a PTP clock driver, and a misc device that allows userspace to map the structure directly. The latter means that userspace applications can use fast vDSO-style clocks *and* have the safety they need from disruption on live migration (which could otherwise cause database corruption, etc.)

It is *entirely* untested as I'm still working on the host side of something to expose it. For now I'm building it as an ACPI device, might like the VMGENID device. But I think it would be ideal for it to be part of the virtio-rtc specification.

I'm also not averse to making it a KVM hypervisor enlightenment, like the existing LM-unsafe KVM PHC. It's slightly easier to add it retrospectively to existing "products" that way as it's less of a visible change.

But the structure itself is agnostic to all that.

/*
* This structure provides a vDSO-style clock to VM guests, exposing the
* relationship (or lack thereof) between the CPU clock (TSC, timebase, arch
* counter, etc.) and real time. It is designed to address the problem of
* live migration, which other clock enlightenments do not.
*
* When a guest is live migrated, this affects the clock in two ways. *
* First, even between identical hosts the actual frequency of the underlying
* counter will change within the tolerances of its specification (typically
* ±50PPM, or 4 seconds a day). The frequency also varies over time on the
* same host, but can be tracked by NTP as it generally varies slowly. With
* live migration there is a step change in the frequency, with no warning. *
* Second, there may be a step change in the value of the counter itself, as
* its accuracy is limited by the precision of the NTP synchronization on the
* source and destination hosts.
*
* So any calibration (NTP, PTP, etc.) which the guest has done on the source
* host before migration is invalid, and needs to be redone on the new host. *
* In its most basic mode, this structure provides only an indication to the
* guest that live migration has occurred. This allows the guest to know that
* its clock is invalid and take remedial action. For applications that need
* reliable accurate timestamps (e.g. distributed databases), the structure
* can be mapped all the way to userspace. This allows the application to see
* directly for itself that the clock is disrupted and take appropriate
* action, even when using a vDSO-style method to get the time instead of a
* system call.
*
* In its more advanced mode. this structure can also be used to expose the
* precise relationship of the CPU counter to real time, as calibrated by the
* host. This means that userspace applications can have accurate time
* immediately after live migration, rather than having to pause operations
* and wait for NTP to recover. This mode does, of course, rely on the
* counter being reliable and consistent across CPUs.
*/

#ifdef __KERNEL__
#include <linux/types.h>
#else
#include <stdint.h>
#endif

struct vmclock_abi {
	uint32_t magic;
#define VMCLOCK_MAGIC	0x56434c4b /* "VCLK" */
	uint16_t size;		/* Size of page containing this structure */
	uint16_t version;	/* 1 */

	/* Sequence lock. Low bit means an update is in progress. */
	uint64_t seq_count;

	/*
	 * This field changes to another non-repeating value when the CPU
	 * counter is disrupted, for example on live migration.
	 */
	uint64_t disruption_marker;

	uint8_t clock_status;

#define VMCLOCK_STATUS_UNKNOWN 0
#define VMCLOCK_STATUS_INITIALIZING 1
#define VMCLOCK_STATUS_SYNCHRONIZED 2
#define VMCLOCK_STATUS_FREERUNNING 3
#define VMCLOCK_STATUS_UNRELIABLE 4

	uint8_t counter_id;

#define VMCLOCK_COUNTER_INVALID 0
#define VMCLOCK_COUNTER_X86_TSC 1
#define VMCLOCK_COUNTER_ARM_VCNT 2

	uint8_t pad[3];

	/*
	 * UTC on its own is non-monotonic and ambiguous.
	 *
	 * Inform the guest about the TAI offset, so that it can have an
	 * actual monotonic and reliable time reference if it needs it.
	 *
	 * Also indicate a nearby leap second, if one exists. Unlike in
	 * NTP, this may indicate a leap second in the past in order to
	 * indicate that it *has* been taken into account.
	 */
	int8_t leapsecond_direction;
	int16_t tai_offset_sec;
	uint64_t leapsecond_counter_value;
	uint64_t leapsecond_tai_time;

	/* Paired values of counter and UTC at a given point in time. */
	uint64_t counter_value;
	uint64_t utc_time_sec;
	uint64_t utc_time_frac_sec;

	/* Counter frequency, and error margin. Units of (second >> 64) */
	uint64_t counter_period_frac_sec;
	uint64_t counter_period_error_rate_frac_sec;

	/* Error margin of UTC reading above (± picoseconds) */
	uint64_t utc_time_maxerror_picosec;
};