Re: [PATCH] qapi: Expand documentation for LostTickPolicy

[Andrew Jones <drjones@redhat.com>]

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>