diff options
| -rw-r--r-- | MAINTAINERS | 1 | ||||
| -rw-r--r-- | docs/devel/testing/blkverify.rst (renamed from docs/devel/blkverify.txt) | 30 | ||||
| -rw-r--r-- | docs/devel/testing/index.rst | 1 |
3 files changed, 19 insertions, 13 deletions
diff --git a/MAINTAINERS b/MAINTAINERS index d4eb221..22cc98b 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -3890,6 +3890,7 @@ M: Stefan Hajnoczi <stefanha@redhat.com> L: qemu-block@nongnu.org S: Supported F: block/blkverify.c +F: docs/devel/blkverify.rst bochs M: Stefan Hajnoczi <stefanha@redhat.com> diff --git a/docs/devel/blkverify.txt b/docs/devel/testing/blkverify.rst index aca826c..2a71778 100644 --- a/docs/devel/blkverify.txt +++ b/docs/devel/testing/blkverify.rst @@ -1,8 +1,10 @@ -= Block driver correctness testing with blkverify = +Block driver correctness testing with ``blkverify`` +=================================================== -== Introduction == +Introduction +------------ -This document describes how to use the blkverify protocol to test that a block +This document describes how to use the ``blkverify`` protocol to test that a block driver is operating correctly. It is difficult to test and debug block drivers against real guests. Often @@ -11,12 +13,13 @@ of the executable. Other times obscure errors are raised by a program inside the guest. These issues are extremely hard to trace back to bugs in the block driver. -Blkverify solves this problem by catching data corruption inside QEMU the first +``blkverify`` solves this problem by catching data corruption inside QEMU the first time bad data is read and reporting the disk sector that is corrupted. -== How it works == +How it works +------------ -The blkverify protocol has two child block devices, the "test" device and the +The ``blkverify`` protocol has two child block devices, the "test" device and the "raw" device. Read/write operations are mirrored to both devices so their state should always be in sync. @@ -25,13 +28,14 @@ contents to the "test" image. The idea is that the "raw" device will handle read/write operations correctly and not corrupt data. It can be used as a reference for comparison against the "test" device. -After a mirrored read operation completes, blkverify will compare the data and +After a mirrored read operation completes, ``blkverify`` will compare the data and raise an error if it is not identical. This makes it possible to catch the first instance where corrupt data is read. -== Example == +Example +------- -Imagine raw.img has 0xcd repeated throughout its first sector: +Imagine raw.img has 0xcd repeated throughout its first sector:: $ ./qemu-io -c 'read -v 0 512' raw.img 00000000: cd cd cd cd cd cd cd cd cd cd cd cd cd cd cd cd ................ @@ -42,7 +46,7 @@ Imagine raw.img has 0xcd repeated throughout its first sector: read 512/512 bytes at offset 0 512.000000 bytes, 1 ops; 0.0000 sec (97.656 MiB/sec and 200000.0000 ops/sec) -And test.img is corrupt, its first sector is zeroed when it shouldn't be: +And test.img is corrupt, its first sector is zeroed when it shouldn't be:: $ ./qemu-io -c 'read -v 0 512' test.img 00000000: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ @@ -53,17 +57,17 @@ And test.img is corrupt, its first sector is zeroed when it shouldn't be: read 512/512 bytes at offset 0 512.000000 bytes, 1 ops; 0.0000 sec (81.380 MiB/sec and 166666.6667 ops/sec) -This error is caught by blkverify: +This error is caught by ``blkverify``:: $ ./qemu-io -c 'read 0 512' blkverify:a.img:b.img blkverify: read sector_num=0 nb_sectors=4 contents mismatch in sector 0 -A more realistic scenario is verifying the installation of a guest OS: +A more realistic scenario is verifying the installation of a guest OS:: $ ./qemu-img create raw.img 16G $ ./qemu-img create -f qcow2 test.qcow2 16G $ ./qemu-system-x86_64 -cdrom debian.iso \ -drive file=blkverify:raw.img:test.qcow2 -If the installation is aborted when blkverify detects corruption, use qemu-io +If the installation is aborted when ``blkverify`` detects corruption, use ``qemu-io`` to explore the contents of the disk image at the sector in question. diff --git a/docs/devel/testing/index.rst b/docs/devel/testing/index.rst index 9e772c7..1171f7d 100644 --- a/docs/devel/testing/index.rst +++ b/docs/devel/testing/index.rst @@ -15,3 +15,4 @@ testing infrastructure. ci fuzzing blkdebug + blkverify |