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

On Sun, 5 Jun 2022 at 01:16, <oxr463@gmx.us> wrote:
>
> 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%)

Thanks for these conversions. Unfortunately at least the version
of Sphinx I have doesn't seem to be happy with them :-(

replay.txt was converted in commit 04d0583a4f5d000 already.

On my version of Sphinx there are a number of errors reported
(since Sphinx bails out on first error you need to fix up each
one to see the next):

/mnt/nvmedisk/linaro/qemu-from-laptop/qemu/docs/devel/blkverify.rst:70:Unexpected
indentation.

/mnt/nvmedisk/linaro/qemu-from-laptop/qemu/docs/devel/rcu.rst:43:Block
quote ends without a blank line; unexpected unindent.

/mnt/nvmedisk/linaro/qemu-from-laptop/qemu/docs/devel/rcu.rst:89:Inline
emphasis start-string without end-string.

/mnt/nvmedisk/linaro/qemu-from-laptop/qemu/docs/devel/rcu.rst:103:Definition
list ends without a blank line; unexpected unindent.

/mnt/nvmedisk/linaro/qemu-from-laptop/qemu/docs/devel/rcu.rst:112:Unexpected
indentation.

/mnt/nvmedisk/linaro/qemu-from-laptop/qemu/docs/devel/rcu.rst:120:Inline
emphasis start-string without end-string.

/mnt/nvmedisk/linaro/qemu-from-laptop/qemu/docs/devel/rcu.rst:129:Inline
emphasis start-string without end-string.

/mnt/nvmedisk/linaro/qemu-from-laptop/qemu/docs/devel/rcu.rst:151:Inline
emphasis start-string without end-string.

/mnt/nvmedisk/linaro/qemu-from-laptop/qemu/docs/devel/virtio-migration.rst:12:Unexpected
indentation.


These are caused largely by two things:

(1) An indented section in the documentation that's intended to be
an ASCII-art diagram or command line example and should be rendered
in fixed-width text needs to be preceded by a double-colon. Otherwise
it's just a normal indented paragraph (and if it has things like
multiple lines with indentation of their own then Sphinx will complain
about incorrect intendation).

(2) Text like
 typeof(*p) qatomic_rcu_read(p);
needs to be surrounded by ``...`` so that the '*' isn't interpreted as
the *emphasis* markup (and also so it ends up as fixed-width font).
That in turn means that we should mark up the other cases in rcu.rst
similarly even if they happen not to have '*' characters, for consistency.

Also, if you look at the rendered HTML for these files you'll
see it looks a bit odd where Sphinx's formatting rules don't find
the input text to be a syntax error but still aren't interpreting
it the way the original text documentation was written, as for
instance in the list of rule attributes in blkdebug.rst.

Finally, when a .txt file has a copyright/license statement in it,
we don't want that to appear in the rendered HTML documentation.
We handle this by putting it in a Sphinx comment. There's an
example of this in docs/system/replay.rst.

Since all that implies that each of these files is going to need a bit
more changes than just fixing up the section titles, I think it
would probably be preferable to split this into more than one commit.

thanks
-- PMM