1Block driver correctness testing with ``blkverify`` 2=================================================== 3 4Introduction 5------------ 6 7This document describes how to use the ``blkverify`` protocol to test that a block 8driver is operating correctly. 9 10It is difficult to test and debug block drivers against real guests. Often 11processes inside the guest will crash because corrupt sectors were read as part 12of the executable. Other times obscure errors are raised by a program inside 13the guest. These issues are extremely hard to trace back to bugs in the block 14driver. 15 16``blkverify`` solves this problem by catching data corruption inside QEMU the first 17time bad data is read and reporting the disk sector that is corrupted. 18 19How it works 20------------ 21 22The ``blkverify`` protocol has two child block devices, the "test" device and the 23"raw" device. Read/write operations are mirrored to both devices so their 24state should always be in sync. 25 26The "raw" device is a raw image, a flat file, that has identical starting 27contents to the "test" image. The idea is that the "raw" device will handle 28read/write operations correctly and not corrupt data. It can be used as a 29reference for comparison against the "test" device. 30 31After a mirrored read operation completes, ``blkverify`` will compare the data and 32raise an error if it is not identical. This makes it possible to catch the 33first instance where corrupt data is read. 34 35Example 36------- 37 38Imagine raw.img has 0xcd repeated throughout its first sector:: 39 40 $ ./qemu-io -c 'read -v 0 512' raw.img 41 00000000: cd cd cd cd cd cd cd cd cd cd cd cd cd cd cd cd ................ 42 00000010: cd cd cd cd cd cd cd cd cd cd cd cd cd cd cd cd ................ 43 [...] 44 000001e0: cd cd cd cd cd cd cd cd cd cd cd cd cd cd cd cd ................ 45 000001f0: cd cd cd cd cd cd cd cd cd cd cd cd cd cd cd cd ................ 46 read 512/512 bytes at offset 0 47 512.000000 bytes, 1 ops; 0.0000 sec (97.656 MiB/sec and 200000.0000 ops/sec) 48 49And test.img is corrupt, its first sector is zeroed when it shouldn't be:: 50 51 $ ./qemu-io -c 'read -v 0 512' test.img 52 00000000: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ 53 00000010: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ 54 [...] 55 000001e0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ 56 000001f0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ 57 read 512/512 bytes at offset 0 58 512.000000 bytes, 1 ops; 0.0000 sec (81.380 MiB/sec and 166666.6667 ops/sec) 59 60This error is caught by ``blkverify``:: 61 62 $ ./qemu-io -c 'read 0 512' blkverify:a.img:b.img 63 blkverify: read sector_num=0 nb_sectors=4 contents mismatch in sector 0 64 65A more realistic scenario is verifying the installation of a guest OS:: 66 67 $ ./qemu-img create raw.img 16G 68 $ ./qemu-img create -f qcow2 test.qcow2 16G 69 $ ./qemu-system-x86_64 -cdrom debian.iso \ 70 -drive file=blkverify:raw.img:test.qcow2 71 72If the installation is aborted when ``blkverify`` detects corruption, use ``qemu-io`` 73to explore the contents of the disk image at the sector in question. 74