[PATCH] docs/devel/*.txt: convert remaining files to restructuredText

[oxr463]

From: Lucas Ramage <lucas.ramage@infinite-omicron.com>

Buglink: https://gitlab.com/qemu-project/qemu/-/issues/527
Signed-off-by: Lucas Ramage <lucas.ramage@infinite-omicron.com>
---
 docs/devel/{blkdebug.txt => blkdebug.rst}     |  8 +++++-
 docs/devel/{blkverify.txt => blkverify.rst}   | 12 ++++++---
 docs/devel/index-build.rst                    |  2 ++
 docs/devel/index-internals.rst                |  5 ++++
 docs/devel/{lockcnt.txt => lockcnt.rst}       | 25 ++++++++++---------
 ...e-iothreads.txt => multiple-iothreads.rst} |  3 +++
 docs/devel/{rcu.txt => rcu.rst}               |  0
 docs/devel/{replay.txt => replay.rst}         | 11 +++++---
 ...tio-migration.txt => virtio-migration.rst} |  6 ++---
 9 files changed, 48 insertions(+), 24 deletions(-)
 rename docs/devel/{blkdebug.txt => blkdebug.rst} (99%)
 rename docs/devel/{blkverify.txt => blkverify.rst} (94%)
 rename docs/devel/{lockcnt.txt => lockcnt.rst} (95%)
 rename docs/devel/{multiple-iothreads.txt => multiple-iothreads.rst} (99%)
 rename docs/devel/{rcu.txt => rcu.rst} (100%)
 rename docs/devel/{replay.txt => replay.rst} (96%)
 rename docs/devel/{virtio-migration.txt => virtio-migration.rst} (98%)

diff --git a/docs/devel/blkdebug.txt b/docs/devel/blkdebug.rst
similarity index 99%
rename from docs/devel/blkdebug.txt
rename to docs/devel/blkdebug.rst
index 0b0c128d35..660d35aaf8 100644
--- a/docs/devel/blkdebug.txt
+++ b/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
diff --git a/docs/devel/blkverify.txt b/docs/devel/blkverify.rst
similarity index 94%
rename from docs/devel/blkverify.txt
rename to docs/devel/blkverify.rst
index aca826c51c..7e1b0fb500 100644
--- a/docs/devel/blkverify.txt
+++ b/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:

diff --git a/docs/devel/index-build.rst b/docs/devel/index-build.rst
index 1002a533a6..514ef308fc 100644
--- a/docs/devel/index-build.rst
+++ b/docs/devel/index-build.rst
@@ -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
diff --git a/docs/devel/index-internals.rst b/docs/devel/index-internals.rst
index e1a93df263..16f57b87da 100644
--- a/docs/devel/index-internals.rst
+++ b/docs/devel/index-internals.rst
@@ -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
diff --git a/docs/devel/lockcnt.txt b/docs/devel/lockcnt.rst
similarity index 95%
rename from docs/devel/lockcnt.txt
rename to docs/devel/lockcnt.rst
index a3fb3bc5d8..0968af46b6 100644
--- a/docs/devel/lockcnt.txt
+++ b/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) {
diff --git a/docs/devel/multiple-iothreads.txt 
b/docs/devel/multiple-iothreads.rst
similarity index 99%
rename from docs/devel/multiple-iothreads.txt
rename to docs/devel/multiple-iothreads.rst
index aeb997bed5..8e7e55b294 100644
--- a/docs/devel/multiple-iothreads.txt
+++ b/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
diff --git a/docs/devel/rcu.txt b/docs/devel/rcu.rst
similarity index 100%
rename from docs/devel/rcu.txt
rename to docs/devel/rcu.rst
diff --git a/docs/devel/replay.txt b/docs/devel/replay.rst
similarity index 96%
rename from docs/devel/replay.txt
rename to docs/devel/replay.rst
index e641c35add..cddc9333c3 100644
--- a/docs/devel/replay.txt
+++ b/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).
diff --git a/docs/devel/virtio-migration.txt b/docs/devel/virtio-migration.rst
similarity index 98%
rename from docs/devel/virtio-migration.txt
rename to docs/devel/virtio-migration.rst
index 98a6b0ffb5..a8a221ab34 100644
--- a/docs/devel/virtio-migration.txt
+++ b/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
--
2.34.2