include/uapi/linux/vmclock-abi.h

   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
  63 struct 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         __u8 pad[2];
 120         __u8 clock_status;
 121 #define VMCLOCK_STATUS_UNKNOWN          0
 122 #define VMCLOCK_STATUS_INITIALIZING     1
 123 #define VMCLOCK_STATUS_SYNCHRONIZED     2
 124 #define VMCLOCK_STATUS_FREERUNNING      3
 125 #define VMCLOCK_STATUS_UNRELIABLE       4
 126
 127         /*
 128          * The time exposed through this device is never smeared. This field
 129          * corresponds to the 'subtype' field in virtio-rtc, which indicates
 130          * the smearing method. However in this case it provides a *hint* to
 131          * the guest operating system, such that *if* the guest OS wants to
 132          * provide its users with an alternative clock which does not follow
 133          * UTC, it may do so in a fashion consistent with the other systems
 134          * in the nearby environment.
 135          */
 136         __u8 leap_second_smearing_hint; /* Matches VIRTIO_RTC_SUBTYPE_xxx */
 137 #define VMCLOCK_SMEARING_STRICT         0
 138 #define VMCLOCK_SMEARING_NOON_LINEAR    1
 139 #define VMCLOCK_SMEARING_UTC_SLS        2
 140         __le16 tai_offset_sec; /* Actually two's complement signed */
 141         __u8 leap_indicator;
 142         /*
 143          * This field is based on the VIRTIO_RTC_LEAP_xxx values as defined
 144          * in the current draft of virtio-rtc, but since smearing cannot be
 145          * used with the shared memory device, some values are not used.
 146          *
 147          * The _POST_POS and _POST_NEG values allow the guest to perform
 148          * its own smearing during the day or so after a leap second when
 149          * such smearing may need to continue being applied for a leap
 150          * second which is now theoretically "historical".
 151          */
 152 #define VMCLOCK_LEAP_NONE       0x00    /* No known nearby leap second */
 153 #define VMCLOCK_LEAP_PRE_POS    0x01    /* Positive leap second at EOM */
 154 #define VMCLOCK_LEAP_PRE_NEG    0x02    /* Negative leap second at EOM */
 155 #define VMCLOCK_LEAP_POS        0x03    /* Set during 23:59:60 second */
 156 #define VMCLOCK_LEAP_POST_POS   0x04
 157 #define VMCLOCK_LEAP_POST_NEG   0x05
 158
 159         /* Bit shift for counter_period_frac_sec and its error rate */
 160         __u8 counter_period_shift;
 161         /*
 162          * Paired values of counter and UTC at a given point in time.
 163          */
 164         __le64 counter_value;
 165         /*
 166          * Counter period, and error margin of same. The unit of these
 167          * fields is 1/2^(64 + counter_period_shift) of a second.
 168          */
 169         __le64 counter_period_frac_sec;
 170         __le64 counter_period_esterror_rate_frac_sec;
 171         __le64 counter_period_maxerror_rate_frac_sec;
 172
 173         /*
 174          * Time according to time_type field above.
 175          */
 176         __le64 time_sec;                /* Seconds since time_type epoch */
 177         __le64 time_frac_sec;           /* Units of 1/2^64 of a second */
 178         __le64 time_esterror_nanosec;
 179         __le64 time_maxerror_nanosec;
 180 };
 181
 182 #endif /*  __VMCLOCK_ABI_H__ */