Update from master tree

diff --git a/vmclock-abi.h b/vmclock-abi.h
index 84f0e37a8a060fceba512267e0811de5f7c93e7f..d7ca44313bf819360e6704b70ee549648ceb07cb 100644 (file)
--- a/vmclock-abi.h
+++ b/vmclock-abi.h
@@ -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