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 10Record/replay 11============= 12 13Record/replay functions are used for the deterministic replay of qemu execution. 14Execution recording writes a non-deterministic events log, which can be later 15used for replaying the execution anywhere and for unlimited number of times. 16It also supports checkpointing for faster rewind to the specific replay moment. 17Execution replaying reads the log and replays all non-deterministic events 18including external input, hardware clocks, and interrupts. 19 20Deterministic 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 32Usage 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 69Core idea 70--------- 71 72Record/replay system is based on saving and replaying non-deterministic 73events (e.g. keyboard input) and simulating deterministic ones (e.g. reading 74from HDD or memory of the VM). Saving only non-deterministic events makes 75log file smaller and simulation faster. 76 77The following non-deterministic data from peripheral devices is saved into 78the log: mouse and keyboard input, network packets, audio controller input, 79serial port input, and hardware clocks (they are non-deterministic 80too, because their values are taken from the host machine). Inputs from 81simulated hardware, memory of VM, software interrupts, and execution of 82instructions are not saved into the log, because they are deterministic and 83can be replayed by simulating the behavior of virtual machine starting from 84initial state. 85 86Instruction counting 87-------------------- 88 89QEMU should work in icount mode to use record/replay feature. icount was 90designed to allow deterministic execution in absence of external inputs 91of the virtual machine. Record/replay feature is enabled through ``-icount`` 92command-line option, making possible deterministic execution of the machine, 93interacting with user or network. 94 95.. _block-label: 96 97Block devices 98------------- 99 100Block devices record/replay module intercepts calls of 101bdrv coroutine functions at the top of block drivers stack. 102To record and replay block operations the drive must be configured 103as 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 110blkreplay driver should be inserted between disk image and virtual driver 111controller. Therefore all disk requests may be recorded and replayed. 112 113.. _snapshotting-label: 114 115Snapshotting 116------------ 117 118New VM snapshots may be created in replay mode. They can be used later 119to recover the desired VM state. All VM states created in replay mode 120are associated with the moment of time in the replay scenario. 121After recovering the VM state replay will start from that position. 122 123Default starting snapshot name may be specified with icount field 124rrsnapshot as follows: 125 126.. parsed-literal:: 127 -icount shift=auto,rr=record,rrfile=replay.bin,rrsnapshot=snapshot_name 128 129This snapshot is created at start of recording and restored at start 130of replaying. It also can be loaded while replaying to roll back 131the execution. 132 133``snapshot`` flag of the disk image must be removed to save the snapshots 134in 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 141Use QEMU monitor to create additional snapshots. ``savevm <name>`` command 142created the snapshot and ``loadvm <name>`` restores it. To prevent corruption 143of the original disk image, use overlay files linked to the original images. 144Therefore all new snapshots (including the starting one) will be saved in 145overlays and the original image remains unchanged. 146 147When you need to use snapshots with diskless virtual machine, 148it must be started with "orphan" qcow2 image. This image will be used 149for 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 157for VM snapshots only. 158 159.. _network-label: 160 161Network devices 162--------------- 163 164Record and replay for network interactions is performed with the network filter. 165Each 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 171Replay network filter is used to record and replay network packets. While 172recording the virtual machine this filter puts all packets coming from 173the outer world into the log. In replay mode packets from the log are 174injected into the network device. All interactions with network backend 175in replay mode are disabled. 176 177Audio devices 178------------- 179 180Audio data is recorded and replay automatically. The command line for recording 181and replaying must contain identical specifications of audio hardware, e.g.: 182 183.. parsed-literal:: 184 -soundhw ac97 185 186Serial ports 187------------ 188 189Serial ports input is recorded and replay automatically. The command lines 190for recording and replaying must contain identical number of ports in record 191and replay modes, but their backends may differ. 192E.g., ``-serial stdio`` in record mode, and ``-serial null`` in replay mode. 193 194Reverse debugging 195----------------- 196 197Reverse debugging allows "executing" the program in reverse direction. 198GDB remote protocol supports "reverse step" and "reverse continue" 199commands. The first one steps single instruction backwards in time, 200and the second one finds the last breakpoint in the past. 201 202Recorded executions may be used to enable reverse debugging. QEMU can't 203execute the code in backwards direction, but can load a snapshot and 204replay forward to find the desired position or breakpoint. 205 206The 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 211Reverse step loads the nearest snapshot and replays the execution until 212the required instruction is met. 213 214Reverse continue may include several passes of examining the execution 215between 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 228Therefore usage of the reverse debugging requires at least one snapshot 229created. This can be done by omitting ``snapshot`` option 230for the block drives and adding ``rrsnapshot`` for both record and replay 231command lines. 232See the :ref:`snapshotting-label` section to learn more about running record/replay 233and creating the snapshot in these modes. 234 235When ``rrsnapshot`` is not used, then snapshot named ``start_debugging`` 236created in temporary overlay. This allows using reverse debugging, but with 237temporary snapshots (existing within the session). 238