]>
Commit | Line | Data |
---|---|---|
43185f7b PD |
1 | .. _replay: |
2 | ||
3 | .. | |
4 | Copyright (c) 2010-2022 Institute for System Programming | |
5 | of the Russian Academy of Sciences. | |
6 | ||
7 | This work is licensed under the terms of the GNU GPL, version 2 or later. | |
8 | See the COPYING file in the top-level directory. | |
9 | ||
10 | Record/replay | |
11 | ============= | |
12 | ||
13 | Record/replay functions are used for the deterministic replay of qemu execution. | |
14 | Execution recording writes a non-deterministic events log, which can be later | |
15 | used for replaying the execution anywhere and for unlimited number of times. | |
16 | It also supports checkpointing for faster rewind to the specific replay moment. | |
17 | Execution replaying reads the log and replays all non-deterministic events | |
18 | including external input, hardware clocks, and interrupts. | |
19 | ||
20 | Deterministic replay has the following features: | |
21 | ||
22 | * Deterministically replays whole system execution and all contents of | |
23 | the memory, state of the hardware devices, clocks, and screen of the VM. | |
24 | * Writes execution log into the file for later replaying for multiple times | |
25 | on different machines. | |
26 | * Supports i386, x86_64, ARM, AArch64, Risc-V, MIPS, MIPS64, S390X, Alpha, | |
27 | PowerPC, PowerPC64, M68000, Microblaze, OpenRISC, Nios II, SPARC, | |
28 | and Xtensa hardware platforms. | |
29 | * Performs deterministic replay of all operations with keyboard and mouse | |
30 | input devices, serial ports, and network. | |
31 | ||
32 | Usage of the record/replay: | |
33 | ||
34 | * First, record the execution with the following command line: | |
35 | ||
36 | .. parsed-literal:: | |
37 | |qemu_system| \\ | |
38 | -icount shift=auto,rr=record,rrfile=replay.bin \\ | |
39 | -drive file=disk.qcow2,if=none,snapshot,id=img-direct \\ | |
40 | -drive driver=blkreplay,if=none,image=img-direct,id=img-blkreplay \\ | |
41 | -device ide-hd,drive=img-blkreplay \\ | |
42 | -netdev user,id=net1 -device rtl8139,netdev=net1 \\ | |
43 | -object filter-replay,id=replay,netdev=net1 | |
44 | ||
45 | * After recording, you can replay it by using another command line: | |
46 | ||
47 | .. parsed-literal:: | |
48 | |qemu_system| \\ | |
49 | -icount shift=auto,rr=replay,rrfile=replay.bin \\ | |
50 | -drive file=disk.qcow2,if=none,snapshot,id=img-direct \\ | |
51 | -drive driver=blkreplay,if=none,image=img-direct,id=img-blkreplay \\ | |
52 | -device ide-hd,drive=img-blkreplay \\ | |
53 | -netdev user,id=net1 -device rtl8139,netdev=net1 \\ | |
54 | -object filter-replay,id=replay,netdev=net1 | |
55 | ||
56 | The only difference with recording is changing the rr option | |
57 | from record to replay. | |
58 | * Block device images are not actually changed in the recording mode, | |
59 | because all of the changes are written to the temporary overlay file. | |
60 | This behavior is enabled by using blkreplay driver. It should be used | |
61 | for every enabled block device, as described in :ref:`block-label` section. | |
62 | * ``-net none`` option should be specified when network is not used, | |
63 | because QEMU adds network card by default. When network is needed, | |
64 | it should be configured explicitly with replay filter, as described | |
65 | in :ref:`network-label` section. | |
66 | * Interaction with audio devices and serial ports are recorded and replayed | |
67 | automatically when such devices are enabled. | |
68 | ||
69 | Core idea | |
70 | --------- | |
71 | ||
72 | Record/replay system is based on saving and replaying non-deterministic | |
73 | events (e.g. keyboard input) and simulating deterministic ones (e.g. reading | |
74 | from HDD or memory of the VM). Saving only non-deterministic events makes | |
75 | log file smaller and simulation faster. | |
76 | ||
77 | The following non-deterministic data from peripheral devices is saved into | |
78 | the log: mouse and keyboard input, network packets, audio controller input, | |
79 | serial port input, and hardware clocks (they are non-deterministic | |
80 | too, because their values are taken from the host machine). Inputs from | |
81 | simulated hardware, memory of VM, software interrupts, and execution of | |
82 | instructions are not saved into the log, because they are deterministic and | |
83 | can be replayed by simulating the behavior of virtual machine starting from | |
84 | initial state. | |
85 | ||
86 | Instruction counting | |
87 | -------------------- | |
88 | ||
89 | QEMU should work in icount mode to use record/replay feature. icount was | |
90 | designed to allow deterministic execution in absence of external inputs | |
91 | of the virtual machine. Record/replay feature is enabled through ``-icount`` | |
92 | command-line option, making possible deterministic execution of the machine, | |
93 | interacting with user or network. | |
94 | ||
95 | .. _block-label: | |
96 | ||
97 | Block devices | |
98 | ------------- | |
99 | ||
100 | Block devices record/replay module intercepts calls of | |
101 | bdrv coroutine functions at the top of block drivers stack. | |
102 | To record and replay block operations the drive must be configured | |
103 | as following: | |
104 | ||
105 | .. parsed-literal:: | |
106 | -drive file=disk.qcow2,if=none,snapshot,id=img-direct | |
107 | -drive driver=blkreplay,if=none,image=img-direct,id=img-blkreplay | |
108 | -device ide-hd,drive=img-blkreplay | |
109 | ||
110 | blkreplay driver should be inserted between disk image and virtual driver | |
111 | controller. Therefore all disk requests may be recorded and replayed. | |
112 | ||
113 | .. _snapshotting-label: | |
114 | ||
115 | Snapshotting | |
116 | ------------ | |
117 | ||
118 | New VM snapshots may be created in replay mode. They can be used later | |
119 | to recover the desired VM state. All VM states created in replay mode | |
120 | are associated with the moment of time in the replay scenario. | |
121 | After recovering the VM state replay will start from that position. | |
122 | ||
123 | Default starting snapshot name may be specified with icount field | |
124 | rrsnapshot as follows: | |
125 | ||
126 | .. parsed-literal:: | |
127 | -icount shift=auto,rr=record,rrfile=replay.bin,rrsnapshot=snapshot_name | |
128 | ||
129 | This snapshot is created at start of recording and restored at start | |
130 | of replaying. It also can be loaded while replaying to roll back | |
131 | the execution. | |
132 | ||
133 | ``snapshot`` flag of the disk image must be removed to save the snapshots | |
134 | in the overlay (or original image) instead of using the temporary overlay. | |
135 | ||
136 | .. parsed-literal:: | |
137 | -drive file=disk.ovl,if=none,id=img-direct | |
138 | -drive driver=blkreplay,if=none,image=img-direct,id=img-blkreplay | |
139 | -device ide-hd,drive=img-blkreplay | |
140 | ||
141 | Use QEMU monitor to create additional snapshots. ``savevm <name>`` command | |
142 | created the snapshot and ``loadvm <name>`` restores it. To prevent corruption | |
143 | of the original disk image, use overlay files linked to the original images. | |
144 | Therefore all new snapshots (including the starting one) will be saved in | |
145 | overlays and the original image remains unchanged. | |
146 | ||
147 | When you need to use snapshots with diskless virtual machine, | |
148 | it must be started with "orphan" qcow2 image. This image will be used | |
149 | for storing VM snapshots. Here is the example of the command line for this: | |
150 | ||
151 | .. parsed-literal:: | |
152 | |qemu_system| \\ | |
153 | -icount shift=auto,rr=replay,rrfile=record.bin,rrsnapshot=init \\ | |
154 | -net none -drive file=empty.qcow2,if=none,id=rr | |
155 | ||
156 | ``empty.qcow2`` drive does not connected to any virtual block device and used | |
157 | for VM snapshots only. | |
158 | ||
159 | .. _network-label: | |
160 | ||
161 | Network devices | |
162 | --------------- | |
163 | ||
164 | Record and replay for network interactions is performed with the network filter. | |
165 | Each backend must have its own instance of the replay filter as follows: | |
166 | ||
167 | .. parsed-literal:: | |
168 | -netdev user,id=net1 -device rtl8139,netdev=net1 | |
169 | -object filter-replay,id=replay,netdev=net1 | |
170 | ||
171 | Replay network filter is used to record and replay network packets. While | |
172 | recording the virtual machine this filter puts all packets coming from | |
173 | the outer world into the log. In replay mode packets from the log are | |
174 | injected into the network device. All interactions with network backend | |
175 | in replay mode are disabled. | |
176 | ||
177 | Audio devices | |
178 | ------------- | |
179 | ||
180 | Audio data is recorded and replay automatically. The command line for recording | |
181 | and replaying must contain identical specifications of audio hardware, e.g.: | |
182 | ||
183 | .. parsed-literal:: | |
34e81820 | 184 | -audio pa,model=ac97 |
43185f7b PD |
185 | |
186 | Serial ports | |
187 | ------------ | |
188 | ||
189 | Serial ports input is recorded and replay automatically. The command lines | |
190 | for recording and replaying must contain identical number of ports in record | |
191 | and replay modes, but their backends may differ. | |
192 | E.g., ``-serial stdio`` in record mode, and ``-serial null`` in replay mode. | |
193 | ||
194 | Reverse debugging | |
195 | ----------------- | |
196 | ||
197 | Reverse debugging allows "executing" the program in reverse direction. | |
198 | GDB remote protocol supports "reverse step" and "reverse continue" | |
199 | commands. The first one steps single instruction backwards in time, | |
200 | and the second one finds the last breakpoint in the past. | |
201 | ||
202 | Recorded executions may be used to enable reverse debugging. QEMU can't | |
203 | execute the code in backwards direction, but can load a snapshot and | |
204 | replay forward to find the desired position or breakpoint. | |
205 | ||
206 | The following GDB commands are supported: | |
207 | ||
208 | - ``reverse-stepi`` (or ``rsi``) - step one instruction backwards | |
209 | - ``reverse-continue`` (or ``rc``) - find last breakpoint in the past | |
210 | ||
211 | Reverse step loads the nearest snapshot and replays the execution until | |
212 | the required instruction is met. | |
213 | ||
214 | Reverse continue may include several passes of examining the execution | |
215 | between the snapshots. Each of the passes include the following steps: | |
216 | ||
217 | #. loading the snapshot | |
218 | #. replaying to examine the breakpoints | |
219 | #. if breakpoint or watchpoint was met | |
220 | ||
221 | * loading the snapshot again | |
222 | * replaying to the required breakpoint | |
223 | ||
224 | #. else | |
225 | ||
226 | * proceeding to the p.1 with the earlier snapshot | |
227 | ||
228 | Therefore usage of the reverse debugging requires at least one snapshot | |
229 | created. This can be done by omitting ``snapshot`` option | |
230 | for the block drives and adding ``rrsnapshot`` for both record and replay | |
231 | command lines. | |
232 | See the :ref:`snapshotting-label` section to learn more about running record/replay | |
233 | and creating the snapshot in these modes. | |
234 | ||
235 | When ``rrsnapshot`` is not used, then snapshot named ``start_debugging`` | |
236 | created in temporary overlay. This allows using reverse debugging, but with | |
237 | temporary snapshots (existing within the session). |