qapi: Expand documentation for LostTickPolicy

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>
Message-Id: <20200211183744.210298-1-abologna@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
Reviewed-by: Andrew Jones <drjones@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>

diff --git a/qapi/misc.json b/qapi/misc.json
index 33b94e3..cd7445d 100644 (file)
--- 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
 ##