[Xen-changelog] [xen staging] public/xen.h: update the comment explaining 'Wallclock time'

[patchbot@xxxxxxx]

commit 78481f525876a6f753866715abaf834f9a4cbc1a
Author:     Paul Durrant <paul.durrant@xxxxxxxxxx>
AuthorDate: Fri Sep 13 12:21:47 2019 +0200
Commit:     Jan Beulich <jbeulich@xxxxxxxx>
CommitDate: Fri Sep 13 12:21:47 2019 +0200

    public/xen.h: update the comment explaining 'Wallclock time'
    
    Since commit 0629adfd80e "Actually set a HVM domain's time offset when it
    sets the RTC", the comment in the public header has been misleading, since
    it claims that wallclock time is only updated by control software.
    Moreover, the comments stating that wc_sec and wc_nsec are seconds and
    nanoseconds (respectively) in UTC since the Unix epoch are bogus. Their
    values are adjusted by the domain's time_offset_seconds value, which is
    updated by a guest write to the emulated RTC and hence the wallclock
    timezone is under guest control.
    
    This patch attempts to bring the comment in line with reality whilst
    keeping it reasonably short.
    
    Signed-off-by: Paul Durrant <paul.durrant@xxxxxxxxxx>
    Acked-by: Jan Beulich <jbeulich@xxxxxxxx>
---
 xen/include/public/xen.h | 13 +++++++++----
 1 file changed, 9 insertions(+), 4 deletions(-)

diff --git a/xen/include/public/xen.h b/xen/include/public/xen.h
index cef65c38e7..d2198dffad 100644
--- a/xen/include/public/xen.h
+++ b/xen/include/public/xen.h
@@ -775,12 +775,17 @@ struct shared_info {
     xen_ulong_t evtchn_mask[sizeof(xen_ulong_t) * 8];
 
     /*
-     * Wallclock time: updated only by control software. Guests should base
-     * their gettimeofday() syscall on this wallclock-base value.
+     * Wallclock time: updated by control software or RTC emulation.
+     * Guests should base their gettimeofday() syscall on this
+     * wallclock-base value.
+     * The values of wc_sec and wc_nsec are offsets from the Unix epoch
+     * adjusted by the domain's 'time offset' (in seconds) as set either
+     * by XEN_DOMCTL_settimeoffset, or adjusted via a guest write to the
+     * emulated RTC.
      */
     uint32_t wc_version;      /* Version counter: see vcpu_time_info_t. */
-    uint32_t wc_sec;          /* Secs  00:00:00 UTC, Jan 1, 1970.  */
-    uint32_t wc_nsec;         /* Nsecs 00:00:00 UTC, Jan 1, 1970.  */
+    uint32_t wc_sec;
+    uint32_t wc_nsec;
 #if !defined(__i386__)
     uint32_t wc_sec_hi;
 # define xen_wc_sec_hi wc_sec_hi
--
generated by git-patchbot for /home/xen/git/xen.git#staging

_______________________________________________
Xen-changelog mailing list
Xen-changelog@xxxxxxxxxxxxxxxxxxxx
https://lists.xenproject.org/xen-changelog