docs/devel/replay.rst

13 execution. Execution recording writes a non-deterministic events log, which
16 non-deterministic events including external input, hardware clocks,
21 Devices' models that have non-deterministic input from external devices were
26 All non-deterministic events are coming from these devices. But to
33 …th Multi-target QEMU Simulator for Dynamic Analysis and Reverse Debugging <https://www.computer.or…
42  * recording/replaying user input (mouse, keyboard, and microphone)
46  * serial port input record and replay
50 --------------------
52 QEMU should work in icount mode to use record/replay feature. icount was
55 non-deterministic events. The number of instructions elapsed from the last event
56 is written to the log while recording the execution. In replay mode we
60 ----------------------------------
68 another lock to keep things in lock-step. This role is now handled by
71 in a deterministic ping-pong between the two main threads.
82 -----------
85 non-determinism. These are inputs from clock and peripheral devices,
87 from timers, asynchronous input-output, and bottom halves.
90 of the virtual machine. Reads produce non-deterministic data taken from
92 order in replay mode must replicate the order of callbacks in record mode.
94 in record mode we save to the log special "checkpoint" event.
98 QEMU in replay mode will try to invoke timers processing in random moment
121 Record/replay mechanism, that could be enabled through icount mode, expects
124 the guest state during execution in icount mode should be deterministic.
127 ------
136    mode virtual clock value is calculated using executed instructions counter.
140    of non-determinism. Host clock read operations should be logged to
144    sleeping. Due to its nature it is also non-deterministic as the host clock
159 -------------
171 -------------
175 Their invocations are saved in record mode and synchronized with the existing
176 log in replay mode.
194 log when its callbacks are executed. In replay mode callbacks are not processed
203 -----------------------------
214 the dependencies that may make restoring the VM state non-deterministic.
217 ---------------
228 events. The header includes 4-byte replay version id and 8-byte reserved
233 It includes all non-deterministic inputs of VM, synchronization marks and
241 Every event in the log includes 1-byte event id and optional arguments.
242 When argument is an array, it is stored as 4-byte array length
246  - EVENT_INSTRUCTION. Instructions executed since last event. Followed by:
248    - 4-byte number of executed instructions.
250  - EVENT_INTERRUPT. Used to synchronize interrupt processing.
251  - EVENT_EXCEPTION. Used to synchronize exception handling.
252  - EVENT_ASYNC. This is a group of events. When such an event is generated,
256      - REPLAY_ASYNC_EVENT_BH. Bottom-half callback. This event synchronizes
260         - 8-byte operation id.
262      - REPLAY_ASYNC_EVENT_INPUT. Input device event. Contains
263        parameters of keyboard and mouse input operations
266         - 9-16 bytes depending of input event.
268      - REPLAY_ASYNC_EVENT_INPUT_SYNC. Internal input synchronization event.
269      - REPLAY_ASYNC_EVENT_CHAR_READ. Character (e.g., serial port) device input
272         - 1-byte character device id.
273         - Array with bytes were read.
275      - REPLAY_ASYNC_EVENT_BLOCK. Block device operation. Used to synchronize
278         - 8-byte operation id.
280      - REPLAY_ASYNC_EVENT_NET. Incoming network packet. Followed by:
282         - 1-byte network adapter id.
283         - 4-byte packet flags.
284         - Array with packet bytes.
286  - EVENT_SHUTDOWN. Occurs when user sends shutdown event to qemu,
288  - EVENT_CHAR_WRITE. Used to synchronize character output operations. Followed by:
290     - 4-byte output function return value.
291     - 4-byte offset in the output array.
293  - EVENT_CHAR_READ_ALL. Used to synchronize character input operations,
296     - Array with bytes that were read.
298  - EVENT_CHAR_READ_ALL_ERROR. Unsuccessful character input operation,
301     - 4-byte error code.
303  - EVENT_CLOCK + clock_id. Group of events for host clock read operations. Followed by:
305     - 8-byte clock value.
307  - EVENT_CHECKPOINT + checkpoint_id. Checkpoint for synchronization of
308    CPU, internal threads, and asynchronous input events.
309  - EVENT_END. Last event in the log.