similarity index 99%
rename from docs/devel/blkdebug.txt
rename to docs/devel/blkdebug.rst
@@ -1,5 +1,6 @@
Block I/O error injection using blkdebug
-----------------------------------------
+========================================
+
Copyright (C) 2014-2015 Red Hat Inc
This work is licensed under the terms of the GNU GPL, version 2 or later. See
@@ -13,6 +14,7 @@ This document gives an overview of the features available in blkdebug.
Background
----------
+
Block drivers have many error code paths that handle I/O errors. Image formats
are especially complex since metadata I/O errors during cluster allocation or
while updating tables happen halfway through request processing and require
@@ -23,6 +25,7 @@ This way, all error paths can be tested to make sure they are correct.
Rules
-----
+
The blkdebug block driver takes a list of "rules" that tell the error injection
engine when to fail an I/O request.
@@ -77,6 +80,7 @@ Rules support the following attributes:
Events
------
+
Block drivers provide information about the type of I/O request they are about
to make so rules can match specific types of requests. For example, the qcow2
block driver tells blkdebug when it accesses the L1 table so rules can match
@@ -98,6 +102,7 @@ meaning of specific events.
State transitions
-----------------
+
There are cases where more power is needed to match a particular I/O request in
a longer sequence of requests. For example:
@@ -149,6 +154,7 @@ State transition rules support the following attributes:
Suspend and resume
------------------
+
Exercising code paths in block drivers may require specific ordering amongst
concurrent requests. The "breakpoint" feature allows requests to be halted on
a blkdebug event and resumed later. This makes it possible to achieve
similarity index 94%
rename from docs/devel/blkverify.txt
rename to docs/devel/blkverify.rst
@@ -1,6 +1,8 @@
-= 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
driver is operating correctly.
@@ -14,7 +16,8 @@ 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 ==
+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
@@ -29,7 +32,8 @@ 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:
@@ -11,6 +11,8 @@ the basics if you are adding new files and targets to the build.
build-system
kconfig
testing
+ blkdebug
+ blkverify
qtest
ci
qapi-code-gen
@@ -11,11 +11,16 @@ Details about QEMU's various subsystems including how to add features to them.
block-coroutine-wrapper
clocks
ebpf_rss
+ lockcnt
migration
multi-process
+ multiple-iothreads
+ rcu
+ replay
reset
s390-dasd-ipl
tracing
vfio-migration
writing-monitor-commands
virtio-backends
+ virtio-migration
similarity index 95%
rename from docs/devel/lockcnt.txt
rename to docs/devel/lockcnt.rst
@@ -1,9 +1,10 @@
-DOCUMENTATION FOR LOCKED COUNTERS (aka QemuLockCnt)
-===================================================
+=================================
+Locked Counters (aka QemuLockCnt)
+=================================
QEMU often uses reference counts to track data structures that are being
accessed and should not be freed. For example, a loop that invoke
-callbacks like this is not safe:
+callbacks like this is not safe::
QLIST_FOREACH_SAFE(ioh, &io_handlers, next, pioh) {
if (ioh->revents & G_IO_OUT) {
@@ -15,7 +16,7 @@ QLIST_FOREACH_SAFE protects against deletion of the current node (ioh)
by stashing away its "next" pointer. However, ioh->fd_write could
actually delete the next node from the list. The simplest way to
avoid this is to mark the node as deleted, and remove it from the
-list in the above loop:
+list in the above loop::
QLIST_FOREACH_SAFE(ioh, &io_handlers, next, pioh) {
if (ioh->deleted) {
@@ -29,7 +30,7 @@ list in the above loop:
}
If however this loop must also be reentrant, i.e. it is possible that
-ioh->fd_write invokes the loop again, some kind of counting is needed:
+ioh->fd_write invokes the loop again, some kind of counting is needed::
walking_handlers++;
QLIST_FOREACH_SAFE(ioh, &io_handlers, next, pioh) {
@@ -101,7 +102,7 @@ can happen concurrently with the read. The RCU API ensures that the
processor and the compiler see all required memory barriers.
This could be implemented simply by protecting the counter with the
-mutex, for example:
+mutex, for example::
// (1)
qemu_mutex_lock(&walking_handlers_mutex);
@@ -183,7 +184,7 @@ QemuLockCnt usage
This section explains the typical usage patterns for QemuLockCnt functions.
Setting a variable to a non-NULL value can be done between
-qemu_lockcnt_lock and qemu_lockcnt_unlock:
+qemu_lockcnt_lock and qemu_lockcnt_unlock::
qemu_lockcnt_lock(&xyz_lockcnt);
if (!xyz) {
@@ -194,7 +195,7 @@ qemu_lockcnt_lock and qemu_lockcnt_unlock:
qemu_lockcnt_unlock(&xyz_lockcnt);
Accessing the value can be done between qemu_lockcnt_inc and
-qemu_lockcnt_dec:
+qemu_lockcnt_dec::
qemu_lockcnt_inc(&xyz_lockcnt);
if (xyz) {
@@ -208,7 +209,7 @@ Freeing the object can similarly use qemu_lockcnt_lock and
qemu_lockcnt_unlock, but you also need to ensure that the count
is zero (i.e. there is no concurrent visit). Because qemu_lockcnt_inc
takes the QemuLockCnt's lock, the count cannot become non-zero while
-the object is being freed. Freeing an object looks like this:
+the object is being freed. Freeing an object looks like this::
qemu_lockcnt_lock(&xyz_lockcnt);
if (!qemu_lockcnt_count(&xyz_lockcnt)) {
@@ -218,7 +219,7 @@ the object is being freed. Freeing an object looks like this:
qemu_lockcnt_unlock(&xyz_lockcnt);
If an object has to be freed right after a visit, you can combine
-the decrement, the locking and the check on count as follows:
+the decrement, the locking and the check on count as follows::
qemu_lockcnt_inc(&xyz_lockcnt);
if (xyz) {
@@ -232,7 +233,7 @@ the decrement, the locking and the check on count as follows:
qemu_lockcnt_unlock(&xyz_lockcnt);
}
-QemuLockCnt can also be used to access a list as follows:
+QemuLockCnt can also be used to access a list as follows::
qemu_lockcnt_inc(&io_handlers_lockcnt);
QLIST_FOREACH_RCU(ioh, &io_handlers, pioh) {
@@ -255,7 +256,7 @@ Again, the RCU primitives are used because new items can be added to the
list during the walk. QLIST_FOREACH_RCU ensures that the processor and
the compiler see the appropriate memory barriers.
-An alternative pattern uses qemu_lockcnt_dec_if_lock:
+An alternative pattern uses qemu_lockcnt_dec_if_lock::
qemu_lockcnt_inc(&io_handlers_lockcnt);
QLIST_FOREACH_SAFE_RCU(ioh, &io_handlers, next, pioh) {
similarity index 99%
rename from docs/devel/multiple-iothreads.txt
rename to docs/devel/multiple-iothreads.rst
@@ -1,3 +1,6 @@
+IOThreads
+=========
+
Copyright (c) 2014-2017 Red Hat Inc.
This work is licensed under the terms of the GNU GPL, version 2 or later. See
similarity index 100%
rename from docs/devel/rcu.txt
rename to docs/devel/rcu.rst
similarity index 96%
rename from docs/devel/replay.txt
rename to docs/devel/replay.rst
@@ -1,3 +1,6 @@
+Replay
+======
+
Record/replay mechanism, that could be enabled through icount mode, expects
the virtual devices to satisfy the following requirements.
@@ -5,7 +8,7 @@ The main idea behind this document is that everything that affects
the guest state during execution in icount mode should be deterministic.
Timers
-======
+------
All virtual devices should use virtual clock for timers that change the guest
state. Virtual clock is deterministic, therefore such timers are deterministic
@@ -19,7 +22,7 @@ the virtual devices (e.g., slirp routing device) that lie outside the
replayed guest.
Bottom halves
-=============
+-------------
Bottom half callbacks, that affect the guest state, should be invoked through
replay_bh_schedule_event or replay_bh_schedule_oneshot_event functions.
@@ -27,7 +30,7 @@ Their invocations are saved in record mode and synchronized with the existing
log in replay mode.
Saving/restoring the VM state
-=============================
+-----------------------------
All fields in the device state structure (including virtual timers)
should be restored by loadvm to the same values they had before savevm.
@@ -38,7 +41,7 @@ is not defined. It means that you should not call functions like
the dependencies that may make restoring the VM state non-deterministic.
Stopping the VM
-===============
+---------------
Stopping the guest should not interfere with its state (with the exception
of the network connections, that could be broken by the remote timeouts).
similarity index 98%
rename from docs/devel/virtio-migration.txt
rename to docs/devel/virtio-migration.rst
@@ -22,7 +22,7 @@ caveats.
Save state procedure
-====================
+--------------------
virtio core virtio transport virtio device
----------- ---------------- -------------
@@ -58,7 +58,7 @@ virtio_save() <----------
Load state procedure
-====================
+--------------------
virtio core virtio transport virtio device
----------- ---------------- -------------
@@ -95,7 +95,7 @@ virtio_load() <----------
Implications of this setup
-==========================
+--------------------------
Devices need to be careful in their state processing during load: The
load_device() procedure is invoked by the core before subsections have