[mirror_qemu.git] / docs / devel / replay.txt

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.
Commit	Line	Data
978ae0e9 PD	1	Record/replay mechanism, that could be enabled through icount mode, expects
	2	the virtual devices to satisfy the following requirements.
	3
	4	The main idea behind this document is that everything that affects
	5	the guest state during execution in icount mode should be deterministic.
	6
	7	Timers
	8	======
	9
	10	All virtual devices should use virtual clock for timers that change the guest
	11	state. Virtual clock is deterministic, therefore such timers are deterministic
	12	too.
	13
	14	Virtual devices can also use realtime clock for the events that do not change
	15	the guest state directly. When the clock ticking should depend on VM execution
	16	speed, use virtual clock with EXTERNAL attribute. It is not deterministic,
	17	but its speed depends on the guest execution. This clock is used by
	18	the virtual devices (e.g., slirp routing device) that lie outside the
	19	replayed guest.
	20
	21	Bottom halves
	22	=============
	23
	24	Bottom half callbacks, that affect the guest state, should be invoked through
	25	replay_bh_schedule_event or replay_bh_schedule_oneshot_event functions.
	26	Their invocations are saved in record mode and synchronized with the existing
	27	log in replay mode.
	28
	29	Saving/restoring the VM state
	30	=============================
	31
	32	All fields in the device state structure (including virtual timers)
	33	should be restored by loadvm to the same values they had before savevm.
	34
	35	Avoid accessing other devices' state, because the order of saving/restoring
	36	is not defined. It means that you should not call functions like
	37	'update_irq' in post_load callback. Save everything explicitly to avoid
	38	the dependencies that may make restoring the VM state non-deterministic.
	39
	40	Stopping the VM
	41	===============
	42
	43	Stopping the guest should not interfere with its state (with the exception
	44	of the network connections, that could be broken by the remote timeouts).
	45	VM can be stopped at any moment of replay by the user. Restarting the VM
	46	after that stop should not break the replay by the unneeded guest state change.