[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[PULL 02/19] qemu-options.hx: Fix minor issues in icount documentation
From: |
Laurent Vivier |
Subject: |
[PULL 02/19] qemu-options.hx: Fix minor issues in icount documentation |
Date: |
Mon, 14 Dec 2020 16:57:16 +0100 |
From: Peter Maydell <peter.maydell@linaro.org>
The documentation for the icount documentation has some minor issues:
* in a couple of places it says "sleep=on|off" when in the context of the
sentence it means specifically "sleep=on"
* the synopsis line for the documentation has drifted out of sync
with the synopsis line in the DEF() macro (used for "-help" output)
* the synopsis line in the DEF() macro is missing a "][" between
the sleep= part and the rr= part
* the synopsis line doesn't indicate that rrsnapshot is an optional
part of the rr=mode,rrfile=filename subgrouping
* we don't document that sleep=on can't be used with shift=auto
or align=on
* the rr option description had some minor grammar and formatting
errors and was a bit terse
* in commit f1f4b57e88ff in 2015 the documentation of the sleep=
suboption got added between the two paragraphs defining general
behaviour of the icount option. This meant that the second
paragraph talking about the behaviour of "this option" reads as
if it's talking about sleep=on, when it's really describing -icount
as a whole. The paragraph is better moved back up to above the
sleep= section.
* the summary text displayed in "-help" output didn't mention
the record-and-replay part
Fix these errors.
Fixes: https://bugs.launchpad.net/qemu/+bug/1774412
Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Reviewed-by: Richard Henderson <richard.henderson@linaro.org>
Message-Id: <20201121213506.15599-1-peter.maydell@linaro.org>
Signed-off-by: Laurent Vivier <laurent@vivier.eu>
---
qemu-options.hx | 44 +++++++++++++++++++++++++-------------------
1 file changed, 25 insertions(+), 19 deletions(-)
diff --git a/qemu-options.hx b/qemu-options.hx
index e60ad42976d0..ae8872d1d664 100644
--- a/qemu-options.hx
+++ b/qemu-options.hx
@@ -3958,30 +3958,34 @@ SRST
ERST
DEF("icount", HAS_ARG, QEMU_OPTION_icount, \
- "-icount
[shift=N|auto][,align=on|off][,sleep=on|off,rr=record|replay,rrfile=<filename>,rrsnapshot=<snapshot>]\n"
\
+ "-icount
[shift=N|auto][,align=on|off][,sleep=on|off][,rr=record|replay,rrfile=<filename>[,rrsnapshot=<snapshot>]]\n"
\
" enable virtual instruction counter with 2^N clock ticks
per\n" \
" instruction, enable aligning the host and virtual
clocks\n" \
- " or disable real time cpu sleeping\n", QEMU_ARCH_ALL)
+ " or disable real time cpu sleeping, and optionally
enable\n" \
+ " record-and-replay mode\n", QEMU_ARCH_ALL)
SRST
-``-icount
[shift=N|auto][,rr=record|replay,rrfile=filename,rrsnapshot=snapshot]``
+``-icount
[shift=N|auto][,align=on|off][,sleep=on|off][,rr=record|replay,rrfile=filename[,rrsnapshot=snapshot]]``
Enable virtual instruction counter. The virtual cpu will execute one
instruction every 2^N ns of virtual time. If ``auto`` is specified
then the virtual cpu speed will be automatically adjusted to keep
virtual time within a few seconds of real time.
- When the virtual cpu is sleeping, the virtual time will advance at
- default speed unless ``sleep=on|off`` is specified. With
- ``sleep=on|off``, the virtual time will jump to the next timer
- deadline instantly whenever the virtual cpu goes to sleep mode and
- will not advance if no timer is enabled. This behavior give
- deterministic execution times from the guest point of view.
-
Note that while this option can give deterministic behavior, it does
not provide cycle accurate emulation. Modern CPUs contain
superscalar out of order cores with complex cache hierarchies. The
number of instructions executed often has little or no correlation
with actual performance.
+ When the virtual cpu is sleeping, the virtual time will advance at
+ default speed unless ``sleep=on`` is specified. With
+ ``sleep=on``, the virtual time will jump to the next timer
+ deadline instantly whenever the virtual cpu goes to sleep mode and
+ will not advance if no timer is enabled. This behavior gives
+ deterministic execution times from the guest point of view.
+ The default if icount is enabled is ``sleep=off``.
+ ``sleep=on`` cannot be used together with either ``shift=auto``
+ or ``align=on``.
+
``align=on`` will activate the delay algorithm which will try to
synchronise the host clock and the virtual clock. The goal is to
have a guest running at the real frequency imposed by the shift
@@ -3991,15 +3995,17 @@ SRST
``shift`` is ``auto``. Note: The sync algorithm will work for those
shift values for which the guest clock runs ahead of the host clock.
Typically this happens when the shift value is high (how high
- depends on the host machine).
-
- When ``rr`` option is specified deterministic record/replay is
- enabled. Replay log is written into filename file in record mode and
- read from this file in replay mode.
-
- Option rrsnapshot is used to create new vm snapshot named snapshot
- at the start of execution recording. In replay mode this option is
- used to load the initial VM state.
+ depends on the host machine). The default if icount is enabled
+ is ``align=off``.
+
+ When the ``rr`` option is specified deterministic record/replay is
+ enabled. The ``rrfile=`` option must also be provided to
+ specify the path to the replay log. In record mode data is written
+ to this file, and in replay mode it is read back.
+ If the ``rrsnapshot`` option is given then it specifies a VM snapshot
+ name. In record mode, a new VM snapshot with the given name is created
+ at the start of execution recording. In replay mode this option
+ specifies the snapshot name used to load the initial VM state.
ERST
DEF("watchdog", HAS_ARG, QEMU_OPTION_watchdog, \
--
2.29.2
- [PULL 00/19] Trivial branch for 6.0 patches, Laurent Vivier, 2020/12/14
- [PULL 02/19] qemu-options.hx: Fix minor issues in icount documentation,
Laurent Vivier <=
- [PULL 01/19] target/i386: tracing: format length values as hex, Laurent Vivier, 2020/12/14
- [PULL 15/19] configure / meson: Move check for pty.h to meson.build, Laurent Vivier, 2020/12/14
- [PULL 16/19] configure / meson: Move check for drm.h to meson.build, Laurent Vivier, 2020/12/14
- [PULL 03/19] MAINTAINERS: update my email address, Laurent Vivier, 2020/12/14
- [PULL 05/19] hw/pci-host/pam: Replace magic number by PAM_REGIONS_COUNT definition, Laurent Vivier, 2020/12/14
- [PULL 10/19] elf2dmp/qemu_elf: Plug memleak in QEMU_Elf_init, Laurent Vivier, 2020/12/14
- [PULL 08/19] ads7846: moves from the hw/display folder to the hw/input folder., Laurent Vivier, 2020/12/14
- [PULL 07/19] CODING_STYLE.rst: Be less strict about 80 character limit, Laurent Vivier, 2020/12/14
- [PULL 04/19] hw/xen: Don't use '#' flag of printf format, Laurent Vivier, 2020/12/14
- [PULL 14/19] configure: Remove the obsolete check for ifaddrs.h, Laurent Vivier, 2020/12/14