[libvirt] [PATCH] docs: mention domain <clock> improvements

[Chris Lalancette]

On 05/13/2010 06:03 PM, Eric Blake wrote:
> diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in
> index a23663a..be0446d 100644
> --- a/docs/formatdomain.html.in
> +++ b/docs/formatdomain.html.in
...
> @@ -428,14 +434,74 @@
>  	    The guest is free to adjust the RTC over time an expect
>  	    that it will be honoured at next reboot. This is in
>  	    contrast to 'utc' mode, where the RTC adjustments are
> -	    lost at each reboot.
> +	    lost at each reboot. <span class="since">Since 0.7.7</span>
>  	  </dd>
>  	</dl>
>  	<p>
> -	  NB, at time of writing, only QEMU supports the variable
> -	  clock mode, or custom timezones.
> +	  A <code>clock</code> may have zero or more
> +	  <code>timer</code>sub-elements. <span class="since">Since
> +	  0.8.0</span>
>  	</p>
>        </dd>
> +      <dt><code>timer</code></dt>
> +      <dd>
> +	<p>
> +	  Each timer element requires a <code>name</code> attribute,
> +	  and has other optional attributes that depend on
> +	  the <code>name</code> specified.  Various hypervisors
> +	  support different combinations of attributes.
> +	</p>
> +	<dl>
> +	  <dt><code>name</code></dt>
> +	  <dd>
> +	    The <code>name</code> attribute selects which timer is
> +	    being modified, and can be one of "platform", "pit",
> +	    "rtc", "hpet", or "tsc".
> +	  </dd>
> +	  <dt><code>track</code></dt>
> +	  <dd>
> +	    The <code>track</code> attribute specifies what the timer
> +	    tracks, and can be "boot", "guest", or "wall".
> +	    Only valid for <code>name="rtc"</code>
> +	    or <code>name="platform"</code>.

Tough one.  This doesn't tell people much about what they should be
choosing for "track", and hence isn't that useful.  You may want to
add more about what this means.  From what I can tell, it's actually
keeping track of how the RTC is getting updated.  If it's set to "guest",
then it is always set relative to the number of guest cycles that have
passed.  If it's set to "wall", it's relative to the actual time that
has passed from the host's POV.  I'm not sure about "boot".

> +	  </dd>
> +	  <dt><code>tickpolicy</code></dt>
> +	  <dd>
> +	    The <code>tickpolicy</code> attribute determines how
> +	    missed ticks in the guest are handled, and can be "delay",
> +	    "catchup", "merge", or "discard".  If the policy is
> +	    "catchup", there can be further details in
> +	    the <code>catchup</code> sub-element.
> +	    <dl>
> +	      <dt><code>catchup</code></dt>
> +	      <dd>
> +		The <code>catchup</code> element has three optional
> +		attributes, each a positive integer.  The attributes
> +		are <code>threshold</code>, <code>slew</code>,
> +		and <code>limit</code>.
> +	      </dd>
> +	    </dl>
> +	  </dd>

Same here.  From what I can tell, it specifies what happens to ticks
when a virtual CPU is scheduled off of physical CPU.  The possible
values are:

      delay: deliver at normal rate (ie ticks are delayed)
    catchup: deliver at higher rate to catchup
      merge: ticks merged into 1 single tick
    discard: all missed ticks are discarded

The meaning for the catchup flags could also be explained, though I'm
not entirely sure what they mean.

> +	  <dt><code>frequency</code></dt>
> +	  <dd>
> +	    The <code>frequency</code> attribute is an unsigned
> +	    integer specifying the frequency at
> +	    which <code>name="tsc"</code> runs.
> +	  </dd>
> +	  <dt><code>mode</code></dt>
> +	  <dd>
> +	    The <code>mode</code> attribute controls how
> +	    the <code>name="tsc"</code> timer is managed, and can be
> +	    "auto", "native", "emulate", "paravirt", or "smpsafe".
> +	    Other timers are always emulated.
> +	  </dd>

It's not really how the tsc is managed; it's more how the tsc is
presented to the guest.  The attributes are:

      auto: native if safe, otherwise emulate
    native: always native (i.e. rdtsc reads the real TSC from the CPU)
   emulate: always emulate
  paravirt: native + paravirtualize
   smpsafe: ???

> +	  <dt><code>present</code></dt>
> +	  <dd>
> +	    The <code>present</code> attribute can be "yes" or "no" to
> +	    specify whether a particular timer is available to the guest.
> +	  </dd>
> +	</dl>
> +      </dd>
>      </dl>
> 
>      <h3><a name="elementsDevices">Devices</a></h3>

My comments are not meant as a discouragement, just improvement; more
documentation is always helpful!

-- 
Chris Lalancette