On Tue, Feb 11, 2020 at 07:37:44PM +0100, Andrea Bolognani wrote: > 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. > > Signed-off-by: Andrea Bolognani <abolo...@redhat.com> > --- > This information is reported pretty much word by word in > > https://libvirt.org/formatdomain.html#elementsTime > > so I'm hoping I can get the QEMU documentation updated and then just > merge back the changes. > > qapi/misc.json | 34 +++++++++++++++++++++++----------- > 1 file changed, 23 insertions(+), 11 deletions(-) > > diff --git a/qapi/misc.json b/qapi/misc.json > index 33b94e3589..cd7445d29f 100644 > --- a/qapi/misc.json > +++ b/qapi/misc.json > @@ -163,17 +163,29 @@ > ## > # @LostTickPolicy: > # > -# Policy for handling lost ticks in timer devices. > -# > -# @discard: throw away the missed tick(s) and continue with future injection > -# normally. Guest time may be delayed, unless the OS has explicit > -# handling of lost ticks > -# > -# @delay: continue to deliver ticks at the normal rate. Guest time will be > -# delayed due to the late tick > -# > -# @slew: deliver ticks at a higher rate to catch up with the missed tick. The > -# guest time should not be delayed once catchup is complete. > +# Policy for handling lost ticks in timer devices. Ticks end up getting > +# lost when, for example, the guest is paused. > +# > +# @discard: throw away the missed ticks and continue with future injection > +# normally. The guest OS will see the timer jump ahead by a > +# potentially quite significant amount all at once, 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. > +# > +# @delay: continue to deliver ticks at the normal rate. The guest OS will > +# not notice anything is amiss, as from its point of view 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. > +# > +# @slew: deliver ticks at a higher rate to catch up with the missed ticks. > +# The guest OS will not notice anything is amiss, as 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. > # > # Since: 2.0 > ## > -- > 2.24.1 > >
Reviewed-by: Andrew Jones <drjo...@redhat.com>