External/libvirt
1
0
Fork 0
mirror of https://gitlab.com/libvirt/libvirt.git synced 2025-03-07 17:28:15 +00:00
Code

docs: Expand documentation for the tickpolicy timer attribute

Browse Source 
The current documentation is fairly terse and not easy to decode
for someone who's not intimately familiar with the inner workings
of timer devices. Expand on it by providing a somewhat verbose
description of what behavior each policy will result in, as seen
from both the guest OS and host point of view.

This is lifted directly from QEMU commit

  commit 2a7d957596786404c4ed16b089273de95a9580ad
  Author: Andrea Bolognani <abologna@redhat.com>
  Date:   Tue Feb 11 19:37:44 2020 +0100

    qapi: Expand documentation for LostTickPolicy

  v4.2.0-1442-g2a7d957596

The original text also matched word for word the documentation
found in QEMU.

Signed-off-by: Andrea Bolognani <abologna@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
This commit is contained in:
Andrea Bolognani 2020-02-18 21:43:08 +01:00
parent 6d371d92f8
commit 2f06757048
1 changed files with 21 additions and 11 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

32
docs/formatdomain.html.in
View File

@ -2487,26 +2487,36 @@
<p> <p>
The <code>tickpolicy</code> attribute determines what The <code>tickpolicy</code> attribute determines what
happens when QEMU misses a deadline for injecting a happens when QEMU misses a deadline for injecting a
tick to the guest: tick to the guest. This can happen, for example, because the
guest was paused.
</p> </p>
<dl> <dl>
<dt><code>delay</code></dt> <dt><code>delay</code></dt>
<dd>Continue to deliver ticks at the normal rate. <dd>Continue to deliver ticks at the normal rate. The guest OS
The guest time will be delayed due to the late will not notice anything is amiss, as from its point of view
tick</dd> time will have continued to flow normally. The time in the
guest should now be behind the time in the host by exactly
the amount of time during which ticks have been missed.</dd>
<dt><code>catchup</code></dt> <dt><code>catchup</code></dt>
<dd>Deliver ticks at a higher rate to catch up <dd>Deliver ticks at a higher rate to catch up with the missed
with the missed tick. The guest time should ticks. The guest OS will not notice anything is amiss, as
not be delayed once catchup is complete.</dd> from its point of view time will have continued to flow
normally. Once the timer has managed to catch up with all
the missing ticks, the time in the guest and in the host
should match.</dd>
<dt><code>merge</code></dt> <dt><code>merge</code></dt>
<dd>Merge the missed tick(s) into one tick and <dd>Merge the missed tick(s) into one tick and
inject. The guest time may be delayed, depending inject. The guest time may be delayed, depending
on how the OS reacts to the merging of ticks</dd> on how the OS reacts to the merging of ticks</dd>
<dt><code>discard</code></dt> <dt><code>discard</code></dt>
<dd>Throw away the missed tick(s) and continue <dd>Throw away the missed ticks and continue with future
with future injection normally. The guest time injection normally. The guest OS will see the timer jump
may be delayed, unless the OS has explicit ahead by a potentially quite significant amount all at once,
handling of lost ticks</dd> as if the intervening chunk of time had simply not existed;
needless to say, such a sudden jump can easily confuse a
guest OS which is not specifically prepared to deal with it.
Assuming the guest OS can deal correctly with the time jump,
the time in the guest and in the host should now match.</dd>
</dl> </dl>
<p>If the policy is "catchup", there can be further details in <p>If the policy is "catchup", there can be further details in
the <code>catchup</code> sub-element.</p> the <code>catchup</code> sub-element.</p>