[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[PATCH] qapi: Expand documentation for LostTickPolicy
From: |
Andrea Bolognani |
Subject: |
[PATCH] qapi: Expand documentation for LostTickPolicy |
Date: |
Tue, 11 Feb 2020 19:37:44 +0100 |
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
- [PATCH] qapi: Expand documentation for LostTickPolicy,
Andrea Bolognani <=