[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[PULL 01/18] qapi: Expand documentation for LostTickPolicy
From: |
Markus Armbruster |
Subject: |
[PULL 01/18] qapi: Expand documentation for LostTickPolicy |
Date: |
Sat, 15 Feb 2020 12:41:16 +0100 |
From: Andrea Bolognani <address@hidden>
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>
Message-Id: <address@hidden>
Reviewed-by: Ján Tomko <address@hidden>
Reviewed-by: Andrew Jones <address@hidden>
Signed-off-by: Markus Armbruster <address@hidden>
---
qapi/misc.json | 28 ++++++++++++++++++++--------
1 file changed, 20 insertions(+), 8 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.
+# 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 tick(s) and continue with future injection
-# normally. Guest time may be delayed, unless the OS has explicit
-# handling of lost ticks
+# @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. Guest time will be
-# delayed due to the late tick
+# @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 tick. The
-# guest time should not be delayed once catchup is complete.
+# @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.21.1
- [PULL 00/18] QAPI patches for 2020-02-15, Markus Armbruster, 2020/02/15
- [PULL 01/18] qapi: Expand documentation for LostTickPolicy,
Markus Armbruster <=
- [PULL 06/18] qga/qapi-schema.json: Fix missing '-' in GuestDiskBusType doc comment, Markus Armbruster, 2020/02/15
- [PULL 07/18] qga/qapi-schema.json: Fix indent level on doc comments, Markus Armbruster, 2020/02/15
- [PULL 05/18] Makefile: Fix typo in dependency list for interop manpages, Markus Armbruster, 2020/02/15
- [PULL 13/18] qapi/ui.json: Put input-send-event body text in the right place, Markus Armbruster, 2020/02/15
- [PULL 03/18] configure: Pick sphinx-build-3 when available, Markus Armbruster, 2020/02/15
- [PULL 18/18] qapi: Delete all the "foo: dropped in n.n" notes, Markus Armbruster, 2020/02/15
- [PULL 10/18] qapi: Fix incorrect "Not documented" claims in QMP documentation, Markus Armbruster, 2020/02/15
- [PULL 14/18] qapi/ui.json: Avoid `...' Texinfo style quoting, Markus Armbruster, 2020/02/15
- [PULL 02/18] configure: Allow user to specify sphinx-build binary, Markus Armbruster, 2020/02/15
- [PULL 16/18] qapi: Add blank lines before bulleted lists, Markus Armbruster, 2020/02/15