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

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!

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>

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