[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [PATCH] qapi: Expand documentation for LostTickPolicy
From: |
Andrew Jones |
Subject: |
Re: [PATCH] qapi: Expand documentation for LostTickPolicy |
Date: |
Thu, 13 Feb 2020 17:51:50 +0100 |
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 <address@hidden>
> ---
> 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 <address@hidden>