mirror of https://gitlab.com/qemu-project/qemu
docs/devel/blkverify: Convert to rST format
Convert blkverify.txt to rST format. Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Reviewed-by: Thomas Huth <thuth@redhat.com> Message-id: 20240816132212.3602106-3-peter.maydell@linaro.org
This commit is contained in:
parent
d5f42aac04
commit
78ac2d8df6
|
@ -3890,6 +3890,7 @@ M: Stefan Hajnoczi <stefanha@redhat.com>
|
||||||
L: qemu-block@nongnu.org
|
L: qemu-block@nongnu.org
|
||||||
S: Supported
|
S: Supported
|
||||||
F: block/blkverify.c
|
F: block/blkverify.c
|
||||||
|
F: docs/devel/blkverify.rst
|
||||||
|
|
||||||
bochs
|
bochs
|
||||||
M: Stefan Hajnoczi <stefanha@redhat.com>
|
M: Stefan Hajnoczi <stefanha@redhat.com>
|
||||||
|
|
|
@ -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.
|
driver is operating correctly.
|
||||||
|
|
||||||
It is difficult to test and debug block drivers against real guests. Often
|
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
|
the guest. These issues are extremely hard to trace back to bugs in the block
|
||||||
driver.
|
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.
|
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
|
"raw" device. Read/write operations are mirrored to both devices so their
|
||||||
state should always be in sync.
|
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
|
read/write operations correctly and not corrupt data. It can be used as a
|
||||||
reference for comparison against the "test" device.
|
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
|
raise an error if it is not identical. This makes it possible to catch the
|
||||||
first instance where corrupt data is read.
|
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
|
$ ./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 ................
|
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
|
read 512/512 bytes at offset 0
|
||||||
512.000000 bytes, 1 ops; 0.0000 sec (97.656 MiB/sec and 200000.0000 ops/sec)
|
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
|
$ ./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 ................
|
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
|
read 512/512 bytes at offset 0
|
||||||
512.000000 bytes, 1 ops; 0.0000 sec (81.380 MiB/sec and 166666.6667 ops/sec)
|
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
|
$ ./qemu-io -c 'read 0 512' blkverify:a.img:b.img
|
||||||
blkverify: read sector_num=0 nb_sectors=4 contents mismatch in sector 0
|
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 raw.img 16G
|
||||||
$ ./qemu-img create -f qcow2 test.qcow2 16G
|
$ ./qemu-img create -f qcow2 test.qcow2 16G
|
||||||
$ ./qemu-system-x86_64 -cdrom debian.iso \
|
$ ./qemu-system-x86_64 -cdrom debian.iso \
|
||||||
-drive file=blkverify:raw.img:test.qcow2
|
-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.
|
to explore the contents of the disk image at the sector in question.
|
|
@ -15,3 +15,4 @@ testing infrastructure.
|
||||||
ci
|
ci
|
||||||
fuzzing
|
fuzzing
|
||||||
blkdebug
|
blkdebug
|
||||||
|
blkverify
|
||||||
|
|
Loading…
Reference in New Issue