[libvirt] [PATCHv5 1/3] Support clock=variable relative to localtime

[Eric Blake]

On 02/06/2012 06:59 AM, Philipp Hahn wrote:
> Since Xen 3.1 the clock=variable semantic is supported. In addition to
> qemu/kvm Xen also knows about a variant where the offset is relative to
> 'localtime' instead of 'utc'.
> 
> Extends the libvirt structure with a flag 'basis' to specify, if the
> offset is relative to 'localtime' or 'utc'.
> 
> Extends the libvirt structure with a flag 'reset' to force the reset
> behaviour of 'localtime' and 'utc'; this is needed for backward
> compatibility with previous versions of libvirt, since they report
> incorrect XML.
> 
> Adapt the only user 'qemu' to the new name.
> Extend the RelaxNG schema accordingly.
> Document the new 'basis' attribute in the HTML documentation.
> Adapt test for the new attribute.
> 

> +++ b/docs/formatdomain.html.in
> @@ -985,11 +985,20 @@
>            <dt><code>utc</code></dt>
>            <dd>
>              The guest clock will always be synchronized to UTC when
> -            booted</dd>
> +            booted.
> +            <span class="since">Since 0.9.11</span> 'utc' mode can be converted
> +            to 'variable' mode, which can be controlled by using the
> +            <code>adjustment</code> attribute. If the value is 'reset', the
> +            conversion is never done and an error is returned. A numeric value
> +            forces the conversion to 'variable' mode using the value as the
> +            initial adjustment. The default is hypervisor specific.

An error is not mandatory on 'reset' unless the hypervisor doesn't
support resetting the time back to utc on each reboot.


> @@ -1000,12 +1009,15 @@
>            <dt><code>variable</code></dt>
>            <dd>
>              The guest clock will have an arbitrary offset applied
> -            relative to UTC. The delta relative to UTC is specified
> +            relative to UTC or localtime, depending on the <code>basis</code>
> +            attribute. The delta relative to UTC (or localtime) is specified
>              in seconds, using the <code>adjustment</code> attribute.
>              The guest is free to adjust the RTC over time and expect
>              that it will be honoured at next reboot. This is in

As long as we're touching this, we can favor US spelling.

> -            contrast to 'utc' mode, where the RTC adjustments are
> +            contrast to 'utc' and 'localtime' mode, where the RTC adjustments are
>              lost at each reboot. <span class="since">Since 0.7.7</span>
> +            <span class="since">Since 0.9.11</span> the <code>basis</code>
> +            attribute can be either 'utc' (default) or 'localtime'.

ACK, and I'm squashing the following tweak in:


diff --git i/docs/formatdomain.html.in w/docs/formatdomain.html.in
index 3ff9c28..a382d30 100644
--- i/docs/formatdomain.html.in
+++ w/docs/formatdomain.html.in
@@ -989,16 +989,19 @@
             <span class="since">Since 0.9.11</span> 'utc' mode can be
converted
             to 'variable' mode, which can be controlled by using the
             <code>adjustment</code> attribute. If the value is 'reset', the
-            conversion is never done and an error is returned. A
numeric value
+            conversion is never done (not all hypervisors can
+            synchronize to UTC on each boot; use of 'reset' will cause
+            an error on those hypervisors). A numeric value
             forces the conversion to 'variable' mode using the value as the
-            initial adjustment. The default is hypervisor specific.
+            initial adjustment. The default <code>adjustment</code> is
+            hypervisor specific.
           </dd>
           <dt><code>localtime</code></dt>
           <dd>
             The guest clock will be synchronized to the host's configured
             timezone when booted, if any.
-            <span class="since">Since 0.9.11</span> <code>adjustment</code>
-            attribute (see 'utc' mode).
+            <span class="since">Since 0.9.11,</span> the
<code>adjustment</code>
+            attribute behaves the same as in 'utc' mode.
           </dd>
           <dt><code>timezone</code></dt>
           <dd>
@@ -1013,8 +1016,9 @@
             attribute. The delta relative to UTC (or localtime) is
specified
             in seconds, using the <code>adjustment</code> attribute.
             The guest is free to adjust the RTC over time and expect
-            that it will be honoured at next reboot. This is in
-            contrast to 'utc' and 'localtime' mode, where the RTC
adjustments are
+            that it will be honored at next reboot. This is in
+            contrast to 'utc' and 'localtime' mode (with the optional
+            attribute adjustment='reset'), where the RTC adjustments are
             lost at each reboot. <span class="since">Since 0.7.7</span>
             <span class="since">Since 0.9.11</span> the <code>basis</code>
             attribute can be either 'utc' (default) or 'localtime'.

-- 
Eric Blake   eblake at redhat.com    +1-919-301-3266
Libvirt virtualization library http://libvirt.org

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 620 bytes
Desc: OpenPGP digital signature
URL: <http://listman.redhat.com/archives/libvir-list/attachments/20120402/1e8348d4/attachment-0001.sig>