public/xen.h: update the comment explaining 'Wallclock time'
diff mbox series

Message ID 20190912140504.40853-1-paul.durrant@citrix.com
State New
Headers show
Series
  • public/xen.h: update the comment explaining 'Wallclock time'
Related show

Commit Message

Paul Durrant Sept. 12, 2019, 2:05 p.m. UTC
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@citrix.com>
---
Cc: Andrew Cooper <andrew.cooper3@citrix.com>
Cc: George Dunlap <George.Dunlap@eu.citrix.com>
Cc: Ian Jackson <ian.jackson@eu.citrix.com>
Cc: Jan Beulich <jbeulich@suse.com>
Cc: Julien Grall <julien.grall@arm.com>
Cc: Konrad Rzeszutek Wilk <konrad.wilk@oracle.com>
Cc: Stefano Stabellini <sstabellini@kernel.org>
Cc: Tim Deegan <tim@xen.org>
Cc: Wei Liu <wl@xen.org>
---
 xen/include/public/xen.h | 13 +++++++++----
 1 file changed, 9 insertions(+), 4 deletions(-)

Comments

Juergen Gross Sept. 12, 2019, 2:13 p.m. UTC | #1
On 12.09.19 16:05, Paul Durrant wrote:
> 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@citrix.com>
> ---
> Cc: Andrew Cooper <andrew.cooper3@citrix.com>
> Cc: George Dunlap <George.Dunlap@eu.citrix.com>
> Cc: Ian Jackson <ian.jackson@eu.citrix.com>
> Cc: Jan Beulich <jbeulich@suse.com>
> Cc: Julien Grall <julien.grall@arm.com>
> Cc: Konrad Rzeszutek Wilk <konrad.wilk@oracle.com>
> Cc: Stefano Stabellini <sstabellini@kernel.org>
> Cc: Tim Deegan <tim@xen.org>
> Cc: Wei Liu <wl@xen.org>
> ---
>   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..2755c5ad54 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 valus of wc_sec and wc_nsec are offsets from the Unix epoch

s/valus/values/


Juergen
Jan Beulich Sept. 12, 2019, 4:02 p.m. UTC | #2
On 12.09.2019 16:05, Paul Durrant wrote:
> 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@citrix.com>

Acked-by: Jan Beulich <jbeulich@suse.com>
(preferably with the typo fixed that Jürgen pointed out; easily
done while committing)
Paul Durrant Sept. 12, 2019, 4:07 p.m. UTC | #3
> -----Original Message-----
> From: Jan Beulich <jbeulich@suse.com>
> Sent: 12 September 2019 17:03
> To: Paul Durrant <Paul.Durrant@citrix.com>
> Cc: xen-devel@lists.xenproject.org; Julien Grall <julien.grall@arm.com>; Andrew Cooper
> <Andrew.Cooper3@citrix.com>; George Dunlap <George.Dunlap@citrix.com>; Ian Jackson
> <Ian.Jackson@citrix.com>; Stefano Stabellini <sstabellini@kernel.org>; Konrad Rzeszutek Wilk
> <konrad.wilk@oracle.com>; Tim (Xen.org) <tim@xen.org>; Wei Liu <wl@xen.org>
> Subject: Re: [PATCH] public/xen.h: update the comment explaining 'Wallclock time'
> 
> On 12.09.2019 16:05, Paul Durrant wrote:
> > 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@citrix.com>
> 
> Acked-by: Jan Beulich <jbeulich@suse.com>
> (preferably with the typo fixed that Jürgen pointed out; easily
> done while committing)

OK. Thanks,

  Paul

Patch
diff mbox series

diff --git a/xen/include/public/xen.h b/xen/include/public/xen.h
index cef65c38e7..2755c5ad54 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 valus 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