docs/devel/testing/blkverify.rst

   1 Block driver correctness testing with ``blkverify``
   2 ===================================================
   3
   4 Introduction
   5 ------------
   6
   7 This document describes how to use the ``blkverify`` protocol to test that a block
   8 driver is operating correctly.
   9
  10 It is difficult to test and debug block drivers against real guests.  Often
  11 processes inside the guest will crash because corrupt sectors were read as part
  12 of the executable.  Other times obscure errors are raised by a program inside
  13 the guest.  These issues are extremely hard to trace back to bugs in the block
  14 driver.
  15
  16 ``blkverify`` solves this problem by catching data corruption inside QEMU the first
  17 time bad data is read and reporting the disk sector that is corrupted.
  18
  19 How it works
  20 ------------
  21
  22 The ``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
  24 state should always be in sync.
  25
  26 The "raw" device is a raw image, a flat file, that has identical starting
  27 contents to the "test" image.  The idea is that the "raw" device will handle
  28 read/write operations correctly and not corrupt data.  It can be used as a
  29 reference for comparison against the "test" device.
  30
  31 After a mirrored read operation completes, ``blkverify`` will compare the data and
  32 raise an error if it is not identical.  This makes it possible to catch the
  33 first instance where corrupt data is read.
  34
  35 Example
  36 -------
  37
  38 Imagine 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
  49 And 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
  60 This 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
  65 A 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
  72 If the installation is aborted when ``blkverify`` detects corruption, use ``qemu-io``
  73 to explore the contents of the disk image at the sector in question.