From e300f4c11dae9be4cc2f44837fe6e560576cc27f Mon Sep 17 00:00:00 2001 From: Peter Maydell Date: Thu, 3 Oct 2024 15:34:01 +0100 Subject: [PATCH] docs/devel: Mention post_load hook restrictions where we document the hook MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit Accessing another device in a post_load hook is a bad idea, because the order of device save/restore is not fixed, and so this cross-device access makes the save/restore non-deterministic. We previously only flagged up this requirement in the record-and-replay developer docs; repeat it in the main migration documentation, where a developer trying to implement a post_load hook is more likely to see it. Signed-off-by: Peter Maydell Reviewed-by: Philippe Mathieu-Daudé Reviewed-by: Michael Tokarev Signed-off-by: Michael Tokarev --- docs/devel/migration/main.rst | 6 ++++++ docs/devel/replay.rst | 3 +++ 2 files changed, 9 insertions(+) diff --git a/docs/devel/migration/main.rst b/docs/devel/migration/main.rst index 784c899dca..c2857fc244 100644 --- a/docs/devel/migration/main.rst +++ b/docs/devel/migration/main.rst @@ -465,6 +465,12 @@ Examples of such API functions are: - portio_list_set_address() - portio_list_set_enabled() +Since the order of device save/restore is not defined, you must +avoid accessing or changing any other device's state in one of these +callbacks. (For instance, don't do anything that calls ``update_irq()`` +in a ``post_load`` hook.) Otherwise, restore will not be deterministic, +and this will break execution record/replay. + Iterative device migration -------------------------- diff --git a/docs/devel/replay.rst b/docs/devel/replay.rst index effd856f0c..40f58d9d4f 100644 --- a/docs/devel/replay.rst +++ b/docs/devel/replay.rst @@ -202,6 +202,9 @@ into the log. Saving/restoring the VM state ----------------------------- +Record/replay relies on VM state save and restore being complete and +deterministic. + All fields in the device state structure (including virtual timers) should be restored by loadvm to the same values they had before savevm. -- 2.49.0