replay.rst (9591B)
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:: 184 -soundhw ac97 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).