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

diff --git a/MAINTAINERS b/MAINTAINERS
index d4eb221b88c0f2786b44a6d996197f418d05ddb2..22cc98bbfeeecd8638267ef588561fc08e5f88d3 100644 (file)
--- 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/blkverify.txt
deleted file mode 100644 (file)
index aca826c..0000000
--- a/docs/devel/blkverify.txt
+++ /dev/null
@@ -1,69 +0,0 @@
-= Block driver correctness testing with blkverify =
-
-== Introduction ==
-
-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
-processes inside the guest will crash because corrupt sectors were read as part
-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
-time bad data is read and reporting the disk sector that is corrupted.
-
-== How it works ==
-
-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.
-
-The "raw" device is a raw image, a flat file, that has identical starting
-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
-raise an error if it is not identical.  This makes it possible to catch the
-first instance where corrupt data is read.
-
-== Example ==
-
-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  ................
-    00000010:  cd cd cd cd cd cd cd cd cd cd cd cd cd cd cd cd  ................
-    [...]
-    000001e0:  cd cd cd cd cd cd cd cd cd cd cd cd cd cd cd cd  ................
-    000001f0:  cd cd cd cd cd cd cd cd cd cd cd cd cd cd cd cd  ................
-    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:
-
-    $ ./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  ................
-    00000010:  00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ................
-    [...]
-    000001e0:  00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ................
-    000001f0:  00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ................
-    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:
-
-    $ ./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:
-
-    $ ./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
-to explore the contents of the disk image at the sector in question.

diff --git a/docs/devel/testing/blkverify.rst b/docs/devel/testing/blkverify.rst
new file mode 100644 (file)
index 0000000..2a71778
--- /dev/null
+++ b/docs/devel/testing/blkverify.rst
@@ -0,0 +1,73 @@
+Block driver correctness testing with ``blkverify``
+===================================================
+
+Introduction
+------------
+
+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
+processes inside the guest will crash because corrupt sectors were read as part
+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
+time bad data is read and reporting the disk sector that is corrupted.
+
+How it works
+------------
+
+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.
+
+The "raw" device is a raw image, a flat file, that has identical starting
+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
+raise an error if it is not identical.  This makes it possible to catch the
+first instance where corrupt data is read.
+
+Example
+-------
+
+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  ................
+    00000010:  cd cd cd cd cd cd cd cd cd cd cd cd cd cd cd cd  ................
+    [...]
+    000001e0:  cd cd cd cd cd cd cd cd cd cd cd cd cd cd cd cd  ................
+    000001f0:  cd cd cd cd cd cd cd cd cd cd cd cd cd cd cd cd  ................
+    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::
+
+    $ ./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  ................
+    00000010:  00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ................
+    [...]
+    000001e0:  00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ................
+    000001f0:  00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ................
+    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``::
+
+    $ ./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::
+
+    $ ./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``
+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 9e772c7fd1d14f950c663efba877716e5d73eae2..1171f7db8f05f657ddf1f1b7770beab77d26a36f 100644 (file)
--- a/docs/devel/testing/index.rst
+++ b/docs/devel/testing/index.rst
@@ -15,3 +15,4 @@ testing infrastructure.
    ci
    fuzzing
    blkdebug
+   blkverify