All of lore.kernel.org
 help / color / mirror / Atom feed
From: Pavel Dovgalyuk <pavel.dovgalyuk@ispras.ru>
To: qemu-devel@nongnu.org
Cc: pavel.dovgalyuk@ispras.ru, pbonzini@redhat.com,
	alex.bennee@linaro.org, crosa@redhat.com, f4bug@amsat.org
Subject: [PATCH v3 5/9] docs: convert docs/devel/replay page to rst
Date: Thu, 26 May 2022 11:45:29 +0300	[thread overview]
Message-ID: <165355472918.533615.4953699104859977763.stgit@pasha-ThinkPad-X280> (raw)
In-Reply-To: <165355470196.533615.1219754093587154582.stgit@pasha-ThinkPad-X280>

This patch converts prior .txt replay devel documentation to .rst.

Signed-off-by: Pavel Dovgalyuk <Pavel.Dovgalyuk@ispras.ru>
Reviewed-by: Richard Henderson <richard.henderson@linaro.org>
---
 docs/devel/index-tcg.rst |    1 +
 docs/devel/replay.rst    |   54 ++++++++++++++++++++++++++++++++++++++++++++++
 docs/devel/replay.txt    |   46 ---------------------------------------
 3 files changed, 55 insertions(+), 46 deletions(-)
 create mode 100644 docs/devel/replay.rst
 delete mode 100644 docs/devel/replay.txt

diff --git a/docs/devel/index-tcg.rst b/docs/devel/index-tcg.rst
index 0b0ad12c22..7b9760b26f 100644
--- a/docs/devel/index-tcg.rst
+++ b/docs/devel/index-tcg.rst
@@ -13,3 +13,4 @@ are only implementing things for HW accelerated hypervisors.
    multi-thread-tcg
    tcg-icount
    tcg-plugins
+   replay
diff --git a/docs/devel/replay.rst b/docs/devel/replay.rst
new file mode 100644
index 0000000000..dd8bf3b195
--- /dev/null
+++ b/docs/devel/replay.rst
@@ -0,0 +1,54 @@
+..
+   Copyright (c) 2022, ISP RAS
+   Written by Pavel Dovgalyuk
+
+=======================
+Execution Record/Replay
+=======================
+
+Record/replay mechanism, that could be enabled through icount mode, expects
+the virtual devices to satisfy the following requirements.
+
+The main idea behind this document is that everything that affects
+the guest state during execution in icount mode should be deterministic.
+
+Timers
+------
+
+All virtual devices should use virtual clock for timers that change the guest
+state. Virtual clock is deterministic, therefore such timers are deterministic
+too.
+
+Virtual devices can also use realtime clock for the events that do not change
+the guest state directly. When the clock ticking should depend on VM execution
+speed, use virtual clock with EXTERNAL attribute. It is not deterministic,
+but its speed depends on the guest execution. This clock is used by
+the virtual devices (e.g., slirp routing device) that lie outside the
+replayed guest.
+
+Bottom halves
+-------------
+
+Bottom half callbacks, that affect the guest state, should be invoked through
+replay_bh_schedule_event or replay_bh_schedule_oneshot_event functions.
+Their invocations are saved in record mode and synchronized with the existing
+log in replay mode.
+
+Saving/restoring the VM state
+-----------------------------
+
+All fields in the device state structure (including virtual timers)
+should be restored by loadvm to the same values they had before savevm.
+
+Avoid accessing other devices' state, because the order of saving/restoring
+is not defined. It means that you should not call functions like
+'update_irq' in post_load callback. Save everything explicitly to avoid
+the dependencies that may make restoring the VM state non-deterministic.
+
+Stopping the VM
+---------------
+
+Stopping the guest should not interfere with its state (with the exception
+of the network connections, that could be broken by the remote timeouts).
+VM can be stopped at any moment of replay by the user. Restarting the VM
+after that stop should not break the replay by the unneeded guest state change.
diff --git a/docs/devel/replay.txt b/docs/devel/replay.txt
deleted file mode 100644
index e641c35add..0000000000
--- a/docs/devel/replay.txt
+++ /dev/null
@@ -1,46 +0,0 @@
-Record/replay mechanism, that could be enabled through icount mode, expects
-the virtual devices to satisfy the following requirements.
-
-The main idea behind this document is that everything that affects
-the guest state during execution in icount mode should be deterministic.
-
-Timers
-======
-
-All virtual devices should use virtual clock for timers that change the guest
-state. Virtual clock is deterministic, therefore such timers are deterministic
-too.
-
-Virtual devices can also use realtime clock for the events that do not change
-the guest state directly. When the clock ticking should depend on VM execution
-speed, use virtual clock with EXTERNAL attribute. It is not deterministic,
-but its speed depends on the guest execution. This clock is used by
-the virtual devices (e.g., slirp routing device) that lie outside the
-replayed guest.
-
-Bottom halves
-=============
-
-Bottom half callbacks, that affect the guest state, should be invoked through
-replay_bh_schedule_event or replay_bh_schedule_oneshot_event functions.
-Their invocations are saved in record mode and synchronized with the existing
-log in replay mode.
-
-Saving/restoring the VM state
-=============================
-
-All fields in the device state structure (including virtual timers)
-should be restored by loadvm to the same values they had before savevm.
-
-Avoid accessing other devices' state, because the order of saving/restoring
-is not defined. It means that you should not call functions like
-'update_irq' in post_load callback. Save everything explicitly to avoid
-the dependencies that may make restoring the VM state non-deterministic.
-
-Stopping the VM
-===============
-
-Stopping the guest should not interfere with its state (with the exception
-of the network connections, that could be broken by the remote timeouts).
-VM can be stopped at any moment of replay by the user. Restarting the VM
-after that stop should not break the replay by the unneeded guest state change.



  parent reply	other threads:[~2022-05-26  8:57 UTC|newest]

Thread overview: 17+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2022-05-26  8:45 [PATCH v3 0/9] Record/replay refactoring and stuff Pavel Dovgalyuk
2022-05-26  8:45 ` [PATCH v3 1/9] replay: fix event queue flush for qemu shutdown Pavel Dovgalyuk
2022-05-26  8:45 ` [PATCH v3 2/9] replay: notify vCPU when BH is scheduled Pavel Dovgalyuk
2022-05-26  9:37   ` Paolo Bonzini
2022-05-26  9:51     ` Pavel Dovgalyuk
2022-05-26 12:10       ` Paolo Bonzini
2022-05-27  8:45         ` Pavel Dovgalyuk
2022-05-26  8:45 ` [PATCH v3 3/9] replay: rewrite async event handling Pavel Dovgalyuk
2022-05-26  8:45 ` [PATCH v3 4/9] replay: simplify async event processing Pavel Dovgalyuk
2022-05-26  9:40   ` Paolo Bonzini
2022-05-26  9:53     ` Pavel Dovgalyuk
2022-05-26  8:45 ` Pavel Dovgalyuk [this message]
2022-05-26  8:45 ` [PATCH v3 6/9] docs: move replay docs to docs/system/replay.rst Pavel Dovgalyuk
2022-05-26  8:45 ` [PATCH v3 7/9] tests/avocado: update replay_linux test Pavel Dovgalyuk
2022-05-26  8:45 ` [PATCH v3 8/9] tests/avocado: add replay Linux tests for virtio machine Pavel Dovgalyuk
2022-05-26  8:45 ` [PATCH v3 9/9] tests/avocado: add replay Linux test for Aarch64 machines Pavel Dovgalyuk
2022-05-26  9:42 ` [PATCH v3 0/9] Record/replay refactoring and stuff Paolo Bonzini

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=165355472918.533615.4953699104859977763.stgit@pasha-ThinkPad-X280 \
    --to=pavel.dovgalyuk@ispras.ru \
    --cc=alex.bennee@linaro.org \
    --cc=crosa@redhat.com \
    --cc=f4bug@amsat.org \
    --cc=pbonzini@redhat.com \
    --cc=qemu-devel@nongnu.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.