From: Andrea Bolognani <abolo...@redhat.com> 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> Message-Id: <20200211183744.210298-1-abolo...@redhat.com> Reviewed-by: Ján Tomko <jto...@redhat.com> Reviewed-by: Andrew Jones <drjo...@redhat.com> Signed-off-by: Markus Armbruster <arm...@redhat.com> --- qapi/misc.json | 28 ++++++++++++++++++++-------- 1 file changed, 20 insertions(+), 8 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. +# 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 tick(s) and continue with future injection -# normally. Guest time may be delayed, unless the OS has explicit -# handling of lost ticks +# @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. Guest time will be -# delayed due to the late tick +# @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 tick. The -# guest time should not be delayed once catchup is complete. +# @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.21.1
