[libvirt] [PATCH] docs: mention domain <clock> improvements
Add documentation for features added a while ago. * docs/formatdomain.html.in (Time keeping): Update documentation of <clock> element to match 0.8.0 addition. --- Please double-check me. The conversion from schemas/domain.rng to text, coupled with list traffic about the patches, was pretty overwhelming. I hope I haven't over-trivialized the various options, but am pretty sure I didn't omit any. docs/formatdomain.html.in | 76 ++++++++++++++++++++++++++++++++++++++++++--- 1 files changed, 71 insertions(+), 5 deletions(-) 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 @@ -395,13 +395,18 @@ <pre> ... - <clock offset="localtime"/> + <clock offset="localtime"> + <timer name="rtc" tickpolicy="catchup" track="guest"> + <catchup threshold=123 slew=120 limit=10000/> + </timer> + <timer name="pit" tickpolicy="none"/> + </clock> ...</pre> <dl> <dt><code>clock</code></dt> <dd> - <p>The <code>offset</code> attribute takes three possible + <p>The <code>offset</code> attribute takes four possible values, allowing fine grained control over how the guest clock is synchronized to the host. NB, not all hypervisors support all modes.</p> @@ -419,6 +424,7 @@ <dd> The guest clock will be synchronized to the requested timezone using the <code>timezone</code> attribute. + <span class="since">Since 0.7.7</span> </dd> <dt><code>variable</code></dt> <dd> @@ -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>. + </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> + <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> + <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> -- 1.7.0.1
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
On 05/17/2010 03:27 PM, Chris Lalancette wrote:
+ <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".
Now you see my quandary of why I asked for feedback! I'm documenting someone else's work, and getting lost in all the options. Laine, since you own the commit that added <timer>, would you care to lend a hand, so we can make this documentation useful? :-)
<h3><a name="elementsDevices">Devices</a></h3>
My comments are not meant as a discouragement, just improvement; more documentation is always helpful!
No discouragement on my side! I consider my afternoon spent on the patch as-is to be time well-spent, even if it's not complete yet. -- Eric Blake eblake@redhat.com +1-801-349-2682 Libvirt virtualization library http://libvirt.org
On 05/17/2010 05:39 PM, Eric Blake wrote:
On 05/17/2010 03:27 PM, Chris Lalancette wrote:
+ <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".
Now you see my quandary of why I asked for feedback! I'm documenting someone else's work, and getting lost in all the options. Laine, since you own the commit that added<timer>, would you care to lend a hand, so we can make this documentation useful? :-)
Actually, documenting that had bee on my to-do list, but constantly slipped due to the fact that I wrote the code based on specs provided by others, so I don't consider myself to be all that knowledgeable about the "why" of things either! :-) I'll gladly help with shaping it up further, but first need a few days to get my dev environment back into shape and check on a pretty ugly bug that still bothers me. Thanks for tackling this, btw. I agree that your time so far was well spent.
participants (3)
-
Chris Lalancette -
Eric Blake -
Laine Stump