| Message ID | 20200211183744.210298-1-abologna@redhat.com |
|---|---|
| State | New |
| Headers | show |
| Series | qapi: Expand documentation for LostTickPolicy | expand |
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 Perchance exorbitantly circumlocutory, but definitely an improvement. >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 <abologna@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(-) Reviewed-by: Ján Tomko <jtomko@redhat.com> Jano
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 <abologna@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 <drjones@redhat.com>
Andrea Bolognani <abologna@redhat.com> writes: > 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 <abologna@redhat.com> Queued, thanks!
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 ##
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 <abologna@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(-)