1/* SPDX-License-Identifier: ((GPL-2.0 WITH Linux-syscall-note) OR BSD-2-Clause) */
2
3/*
4 * This structure provides a vDSO-style clock to VM guests, exposing the
5 * relationship (or lack thereof) between the CPU clock (TSC, timebase, arch
6 * counter, etc.) and real time. It is designed to address the problem of
7 * live migration, which other clock enlightenments do not.
8 *
9 * When a guest is live migrated, this affects the clock in two ways.
10 *
11 * First, even between identical hosts the actual frequency of the underlying
12 * counter will change within the tolerances of its specification (typically
13 * ±50PPM, or 4 seconds a day). This frequency also varies over time on the
14 * same host, but can be tracked by NTP as it generally varies slowly. With
15 * live migration there is a step change in the frequency, with no warning.
16 *
17 * Second, there may be a step change in the value of the counter itself, as
18 * its accuracy is limited by the precision of the NTP synchronization on the
19 * source and destination hosts.
20 *
21 * So any calibration (NTP, PTP, etc.) which the guest has done on the source
22 * host before migration is invalid, and needs to be redone on the new host.
23 *
24 * In its most basic mode, this structure provides only an indication to the
25 * guest that live migration has occurred. This allows the guest to know that
26 * its clock is invalid and take remedial action. For applications that need
27 * reliable accurate timestamps (e.g. distributed databases), the structure
28 * can be mapped all the way to userspace. This allows the application to see
29 * directly for itself that the clock is disrupted and take appropriate
30 * action, even when using a vDSO-style method to get the time instead of a
31 * system call.
32 *
33 * In its more advanced mode. this structure can also be used to expose the
34 * precise relationship of the CPU counter to real time, as calibrated by the
35 * host. This means that userspace applications can have accurate time
36 * immediately after live migration, rather than having to pause operations
37 * and wait for NTP to recover. This mode does, of course, rely on the
38 * counter being reliable and consistent across CPUs.
39 *
40 * Note that this must be true UTC, never with smeared leap seconds. If a
41 * guest wishes to construct a smeared clock, it can do so. Presenting a
42 * smeared clock through this interface would be problematic because it
43 * actually messes with the apparent counter *period*. A linear smearing
44 * of 1 ms per second would effectively tweak the counter period by 1000PPM
45 * at the start/end of the smearing period, while a sinusoidal smear would
46 * basically be impossible to represent.
47 *
48 * This structure is offered with the intent that it be adopted into the
49 * nascent virtio-rtc standard, as a virtio-rtc that does not address the live
50 * migration problem seems a little less than fit for purpose. For that
51 * reason, certain fields use precisely the same numeric definitions as in
52 * the virtio-rtc proposal. The structure can also be exposed through an ACPI
53 * device with the CID "VMCLOCK", modelled on the "VMGENID" device except for
54 * the fact that it uses a real _CRS to convey the address of the structure
55 * (which should be a full page, to allow for mapping directly to userspace).
56 */
57
58#ifndef __VMCLOCK_ABI_H__
59#define __VMCLOCK_ABI_H__
60
61#include <linux/types.h>
62
63struct vmclock_abi {
64 /* CONSTANT FIELDS */
65 __le32 magic;
66#define VMCLOCK_MAGIC 0x4b4c4356 /* "VCLK" */
67 __le32 size; /* Size of region containing this structure */
68 __le16 version; /* 1 */
69 __u8 counter_id; /* Matches VIRTIO_RTC_COUNTER_xxx except INVALID */
70#define VMCLOCK_COUNTER_ARM_VCNT 0
71#define VMCLOCK_COUNTER_X86_TSC 1
72#define VMCLOCK_COUNTER_INVALID 0xff
73 __u8 time_type; /* Matches VIRTIO_RTC_TYPE_xxx */
74#define VMCLOCK_TIME_UTC 0 /* Since 1970-01-01 00:00:00z */
75#define VMCLOCK_TIME_TAI 1 /* Since 1970-01-01 00:00:00z */
76#define VMCLOCK_TIME_MONOTONIC 2 /* Since undefined epoch */
77#define VMCLOCK_TIME_INVALID_SMEARED 3 /* Not supported */
78#define VMCLOCK_TIME_INVALID_MAYBE_SMEARED 4 /* Not supported */
79
80 /* NON-CONSTANT FIELDS PROTECTED BY SEQCOUNT LOCK */
81 __le32 seq_count; /* Low bit means an update is in progress */
82 /*
83 * This field changes to another non-repeating value when the CPU
84 * counter is disrupted, for example on live migration. This lets
85 * the guest know that it should discard any calibration it has
86 * performed of the counter against external sources (NTP/PTP/etc.).
87 */
88 __le64 disruption_marker;
89 __le64 flags;
90 /* Indicates that the tai_offset_sec field is valid */
91#define VMCLOCK_FLAG_TAI_OFFSET_VALID (1 << 0)
92 /*
93 * Optionally used to notify guests of pending maintenance events.
94 * A guest which provides latency-sensitive services may wish to
95 * remove itself from service if an event is coming up. Two flags
96 * indicate the approximate imminence of the event.
97 */
98#define VMCLOCK_FLAG_DISRUPTION_SOON (1 << 1) /* About a day */
99#define VMCLOCK_FLAG_DISRUPTION_IMMINENT (1 << 2) /* About an hour */
100#define VMCLOCK_FLAG_PERIOD_ESTERROR_VALID (1 << 3)
101#define VMCLOCK_FLAG_PERIOD_MAXERROR_VALID (1 << 4)
102#define VMCLOCK_FLAG_TIME_ESTERROR_VALID (1 << 5)
103#define VMCLOCK_FLAG_TIME_MAXERROR_VALID (1 << 6)
104 /*
105 * If the MONOTONIC flag is set then (other than leap seconds) it is
106 * guaranteed that the time calculated according this structure at
107 * any given moment shall never appear to be later than the time
108 * calculated via the structure at any *later* moment.
109 *
110 * In particular, a timestamp based on a counter reading taken
111 * immediately after setting the low bit of seq_count (and the
112 * associated memory barrier), using the previously-valid time and
113 * period fields, shall never be later than a timestamp based on
114 * a counter reading taken immediately before *clearing* the low
115 * bit again after the update, using the about-to-be-valid fields.
116 */
117#define VMCLOCK_FLAG_TIME_MONOTONIC (1 << 7)
118 /*
119 * If the VM_GEN_COUNTER_PRESENT flag is set, the hypervisor will
120 * bump the vm_generation_counter field every time the guest is
121 * loaded from some save state (restored from a snapshot).
122 */
123#define VMCLOCK_FLAG_VM_GEN_COUNTER_PRESENT (1 << 8)
124 /*
125 * If the NOTIFICATION_PRESENT flag is set, the hypervisor will send
126 * a notification every time it updates seq_count to a new even number.
127 */
128#define VMCLOCK_FLAG_NOTIFICATION_PRESENT (1 << 9)
129
130 __u8 pad[2];
131 __u8 clock_status;
132#define VMCLOCK_STATUS_UNKNOWN 0
133#define VMCLOCK_STATUS_INITIALIZING 1
134#define VMCLOCK_STATUS_SYNCHRONIZED 2
135#define VMCLOCK_STATUS_FREERUNNING 3
136#define VMCLOCK_STATUS_UNRELIABLE 4
137
138 /*
139 * The time exposed through this device is never smeared. This field
140 * corresponds to the 'subtype' field in virtio-rtc, which indicates
141 * the smearing method. However in this case it provides a *hint* to
142 * the guest operating system, such that *if* the guest OS wants to
143 * provide its users with an alternative clock which does not follow
144 * UTC, it may do so in a fashion consistent with the other systems
145 * in the nearby environment.
146 */
147 __u8 leap_second_smearing_hint; /* Matches VIRTIO_RTC_SUBTYPE_xxx */
148#define VMCLOCK_SMEARING_STRICT 0
149#define VMCLOCK_SMEARING_NOON_LINEAR 1
150#define VMCLOCK_SMEARING_UTC_SLS 2
151 __le16 tai_offset_sec; /* Actually two's complement signed */
152 __u8 leap_indicator;
153 /*
154 * This field is based on the VIRTIO_RTC_LEAP_xxx values as defined
155 * in the current draft of virtio-rtc, but since smearing cannot be
156 * used with the shared memory device, some values are not used.
157 *
158 * The _POST_POS and _POST_NEG values allow the guest to perform
159 * its own smearing during the day or so after a leap second when
160 * such smearing may need to continue being applied for a leap
161 * second which is now theoretically "historical".
162 */
163#define VMCLOCK_LEAP_NONE 0x00 /* No known nearby leap second */
164#define VMCLOCK_LEAP_PRE_POS 0x01 /* Positive leap second at EOM */
165#define VMCLOCK_LEAP_PRE_NEG 0x02 /* Negative leap second at EOM */
166#define VMCLOCK_LEAP_POS 0x03 /* Set during 23:59:60 second */
167#define VMCLOCK_LEAP_POST_POS 0x04
168#define VMCLOCK_LEAP_POST_NEG 0x05
169
170 /* Bit shift for counter_period_frac_sec and its error rate */
171 __u8 counter_period_shift;
172 /*
173 * Paired values of counter and UTC at a given point in time.
174 */
175 __le64 counter_value;
176 /*
177 * Counter period, and error margin of same. The unit of these
178 * fields is 1/2^(64 + counter_period_shift) of a second.
179 */
180 __le64 counter_period_frac_sec;
181 __le64 counter_period_esterror_rate_frac_sec;
182 __le64 counter_period_maxerror_rate_frac_sec;
183
184 /*
185 * Time according to time_type field above.
186 */
187 __le64 time_sec; /* Seconds since time_type epoch */
188 __le64 time_frac_sec; /* Units of 1/2^64 of a second */
189 __le64 time_esterror_nanosec;
190 __le64 time_maxerror_nanosec;
191
192 /*
193 * This field changes to another non-repeating value when the guest
194 * has been loaded from a snapshot. In addition to handling a
195 * disruption in time (which will also be signalled through the
196 * disruption_marker field), a guest may wish to discard UUIDs,
197 * reset network connections, reseed entropy, etc.
198 */
199 __le64 vm_generation_counter;
200};
201
202#endif /* __VMCLOCK_ABI_H__ */