QEMU-Devel Archive on lore.kernel.org
 help / color / Atom feed
* [PATCH] qapi: Expand documentation for LostTickPolicy
@ 2020-02-11 18:37 Andrea Bolognani
  2020-02-12 13:02 ` Ján Tomko
                   ` (2 more replies)
  0 siblings, 3 replies; 4+ messages in thread
From: Andrea Bolognani @ 2020-02-11 18:37 UTC (permalink / raw)
  To: qemu-devel; +Cc: Andrew Jones, Markus Armbruster

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



^ permalink raw reply	[flat|nested] 4+ messages in thread

* Re: [PATCH] qapi: Expand documentation for LostTickPolicy
  2020-02-11 18:37 [PATCH] qapi: Expand documentation for LostTickPolicy Andrea Bolognani
@ 2020-02-12 13:02 ` Ján Tomko
  2020-02-13 16:51 ` Andrew Jones
  2020-02-14 15:23 ` Markus Armbruster
  2 siblings, 0 replies; 4+ messages in thread
From: Ján Tomko @ 2020-02-12 13:02 UTC (permalink / raw)
  To: Andrea Bolognani; +Cc: Andrew Jones, qemu-devel, Markus Armbruster

[-- Attachment #1: Type: text/plain, Size: 908 bytes --]

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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

^ permalink raw reply	[flat|nested] 4+ messages in thread

* Re: [PATCH] qapi: Expand documentation for LostTickPolicy
  2020-02-11 18:37 [PATCH] qapi: Expand documentation for LostTickPolicy Andrea Bolognani
  2020-02-12 13:02 ` Ján Tomko
@ 2020-02-13 16:51 ` Andrew Jones
  2020-02-14 15:23 ` Markus Armbruster
  2 siblings, 0 replies; 4+ messages in thread
From: Andrew Jones @ 2020-02-13 16:51 UTC (permalink / raw)
  To: Andrea Bolognani; +Cc: qemu-devel, Markus Armbruster

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>



^ permalink raw reply	[flat|nested] 4+ messages in thread

* Re: [PATCH] qapi: Expand documentation for LostTickPolicy
  2020-02-11 18:37 [PATCH] qapi: Expand documentation for LostTickPolicy Andrea Bolognani
  2020-02-12 13:02 ` Ján Tomko
  2020-02-13 16:51 ` Andrew Jones
@ 2020-02-14 15:23 ` Markus Armbruster
  2 siblings, 0 replies; 4+ messages in thread
From: Markus Armbruster @ 2020-02-14 15:23 UTC (permalink / raw)
  To: Andrea Bolognani; +Cc: Andrew Jones, qemu-devel

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!



^ permalink raw reply	[flat|nested] 4+ messages in thread

end of thread, back to index

Thread overview: 4+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2020-02-11 18:37 [PATCH] qapi: Expand documentation for LostTickPolicy Andrea Bolognani
2020-02-12 13:02 ` Ján Tomko
2020-02-13 16:51 ` Andrew Jones
2020-02-14 15:23 ` Markus Armbruster

QEMU-Devel Archive on lore.kernel.org

Archives are clonable:
	git clone --mirror https://lore.kernel.org/qemu-devel/0 qemu-devel/git/0.git
	git clone --mirror https://lore.kernel.org/qemu-devel/1 qemu-devel/git/1.git

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V2 qemu-devel qemu-devel/ https://lore.kernel.org/qemu-devel \
		qemu-devel@nongnu.org
	public-inbox-index qemu-devel

Example config snippet for mirrors

Newsgroup available over NNTP:
	nntp://nntp.lore.kernel.org/org.nongnu.qemu-devel


AGPL code for this site: git clone https://public-inbox.org/public-inbox.git