Merge tag 'pull-request-2021-11-22' of https://gitlab.com/thuth/qemu into staging

* Documentation updates

# gpg: Signature made Mon 22 Nov 2021 03:05:39 PM CET
# gpg:                using RSA key 27B88847EEE0250118F3EAB92ED9D774FE702DB5
# gpg:                issuer "thuth@redhat.com"
# gpg: Good signature from "Thomas Huth <th.huth@gmx.de>" [full]
# gpg:                 aka "Thomas Huth <thuth@redhat.com>" [full]
# gpg:                 aka "Thomas Huth <th.huth@posteo.de>" [unknown]
# gpg:                 aka "Thomas Huth <huth@tuxfamily.org>" [full]

* tag 'pull-request-2021-11-22' of https://gitlab.com/thuth/qemu:
  docs: Render binary names as monospaced text
  docs: Use double quotes instead of single quotes for COLO
  docs: Drop deprecated 'props' from object-add
  Fix some typos in documentation (found by codespell)
  docs: List more commit-message tags in "submitting-a-patch"
  docs: Fix botched rST conversion of 'submitting-a-patch.rst'

Signed-off-by: Richard Henderson <richard.henderson@linaro.org>

30 files changed, 307 insertions, 201 deletions

diff --git a/docs/COLO-FT.txt b/docs/COLO-FT.txt
index 8d6d53a5a2..8ec653f81c 100644
--- a/docs/COLO-FT.txt
+++ b/docs/COLO-FT.txt
@@ -209,9 +209,9 @@ children.0=childs0 \
 
 
 3. On Secondary VM's QEMU monitor, issue command
-{'execute':'qmp_capabilities'}
-{'execute': 'nbd-server-start', 'arguments': {'addr': {'type': 'inet', 'data': {'host': '0.0.0.0', 'port': '9999'} } } }
-{'execute': 'nbd-server-add', 'arguments': {'device': 'parent0', 'writable': true } }
+{"execute":"qmp_capabilities"}
+{"execute": "nbd-server-start", "arguments": {"addr": {"type": "inet", "data": {"host": "0.0.0.0", "port": "9999"} } } }
+{"execute": "nbd-server-add", "arguments": {"device": "parent0", "writable": true } }
 
 Note:
   a. The qmp command nbd-server-start and nbd-server-add must be run
@@ -222,11 +222,11 @@ Note:
      will be merged into the parent disk on failover.
 
 4. On Primary VM's QEMU monitor, issue command:
-{'execute':'qmp_capabilities'}
-{'execute': 'human-monitor-command', 'arguments': {'command-line': 'drive_add -n buddy driver=replication,mode=primary,file.driver=nbd,file.host=127.0.0.2,file.port=9999,file.export=parent0,node-name=replication0'}}
-{'execute': 'x-blockdev-change', 'arguments':{'parent': 'colo-disk0', 'node': 'replication0' } }
-{'execute': 'migrate-set-capabilities', 'arguments': {'capabilities': [ {'capability': 'x-colo', 'state': true } ] } }
-{'execute': 'migrate', 'arguments': {'uri': 'tcp:127.0.0.2:9998' } }
+{"execute":"qmp_capabilities"}
+{"execute": "human-monitor-command", "arguments": {"command-line": "drive_add -n buddy driver=replication,mode=primary,file.driver=nbd,file.host=127.0.0.2,file.port=9999,file.export=parent0,node-name=replication0"}}
+{"execute": "x-blockdev-change", "arguments":{"parent": "colo-disk0", "node": "replication0" } }
+{"execute": "migrate-set-capabilities", "arguments": {"capabilities": [ {"capability": "x-colo", "state": true } ] } }
+{"execute": "migrate", "arguments": {"uri": "tcp:127.0.0.2:9998" } }
 
   Note:
   a. There should be only one NBD Client for each primary disk.
@@ -249,59 +249,59 @@ if you want to resume the replication, follow "Secondary resume replication"
 == Primary Failover ==
 The Secondary died, resume on the Primary
 
-{'execute': 'x-blockdev-change', 'arguments':{ 'parent': 'colo-disk0', 'child': 'children.1'} }
-{'execute': 'human-monitor-command', 'arguments':{ 'command-line': 'drive_del replication0' } }
-{'execute': 'object-del', 'arguments':{ 'id': 'comp0' } }
-{'execute': 'object-del', 'arguments':{ 'id': 'iothread1' } }
-{'execute': 'object-del', 'arguments':{ 'id': 'm0' } }
-{'execute': 'object-del', 'arguments':{ 'id': 'redire0' } }
-{'execute': 'object-del', 'arguments':{ 'id': 'redire1' } }
-{'execute': 'x-colo-lost-heartbeat' }
+{"execute": "x-blockdev-change", "arguments":{ "parent": "colo-disk0", "child": "children.1"} }
+{"execute": "human-monitor-command", "arguments":{ "command-line": "drive_del replication0" } }
+{"execute": "object-del", "arguments":{ "id": "comp0" } }
+{"execute": "object-del", "arguments":{ "id": "iothread1" } }
+{"execute": "object-del", "arguments":{ "id": "m0" } }
+{"execute": "object-del", "arguments":{ "id": "redire0" } }
+{"execute": "object-del", "arguments":{ "id": "redire1" } }
+{"execute": "x-colo-lost-heartbeat" }
 
 == Secondary Failover ==
 The Primary died, resume on the Secondary and prepare to become the new Primary
 
-{'execute': 'nbd-server-stop'}
-{'execute': 'x-colo-lost-heartbeat'}
+{"execute": "nbd-server-stop"}
+{"execute": "x-colo-lost-heartbeat"}
 
-{'execute': 'object-del', 'arguments':{ 'id': 'f2' } }
-{'execute': 'object-del', 'arguments':{ 'id': 'f1' } }
-{'execute': 'chardev-remove', 'arguments':{ 'id': 'red1' } }
-{'execute': 'chardev-remove', 'arguments':{ 'id': 'red0' } }
+{"execute": "object-del", "arguments":{ "id": "f2" } }
+{"execute": "object-del", "arguments":{ "id": "f1" } }
+{"execute": "chardev-remove", "arguments":{ "id": "red1" } }
+{"execute": "chardev-remove", "arguments":{ "id": "red0" } }
 
-{'execute': 'chardev-add', 'arguments':{ 'id': 'mirror0', 'backend': {'type': 'socket', 'data': {'addr': { 'type': 'inet', 'data': { 'host': '0.0.0.0', 'port': '9003' } }, 'server': true } } } }
-{'execute': 'chardev-add', 'arguments':{ 'id': 'compare1', 'backend': {'type': 'socket', 'data': {'addr': { 'type': 'inet', 'data': { 'host': '0.0.0.0', 'port': '9004' } }, 'server': true } } } }
-{'execute': 'chardev-add', 'arguments':{ 'id': 'compare0', 'backend': {'type': 'socket', 'data': {'addr': { 'type': 'inet', 'data': { 'host': '127.0.0.1', 'port': '9001' } }, 'server': true } } } }
-{'execute': 'chardev-add', 'arguments':{ 'id': 'compare0-0', 'backend': {'type': 'socket', 'data': {'addr': { 'type': 'inet', 'data': { 'host': '127.0.0.1', 'port': '9001' } }, 'server': false } } } }
-{'execute': 'chardev-add', 'arguments':{ 'id': 'compare_out', 'backend': {'type': 'socket', 'data': {'addr': { 'type': 'inet', 'data': { 'host': '127.0.0.1', 'port': '9005' } }, 'server': true } } } }
-{'execute': 'chardev-add', 'arguments':{ 'id': 'compare_out0', 'backend': {'type': 'socket', 'data': {'addr': { 'type': 'inet', 'data': { 'host': '127.0.0.1', 'port': '9005' } }, 'server': false } } } }
+{"execute": "chardev-add", "arguments":{ "id": "mirror0", "backend": {"type": "socket", "data": {"addr": { "type": "inet", "data": { "host": "0.0.0.0", "port": "9003" } }, "server": true } } } }
+{"execute": "chardev-add", "arguments":{ "id": "compare1", "backend": {"type": "socket", "data": {"addr": { "type": "inet", "data": { "host": "0.0.0.0", "port": "9004" } }, "server": true } } } }
+{"execute": "chardev-add", "arguments":{ "id": "compare0", "backend": {"type": "socket", "data": {"addr": { "type": "inet", "data": { "host": "127.0.0.1", "port": "9001" } }, "server": true } } } }
+{"execute": "chardev-add", "arguments":{ "id": "compare0-0", "backend": {"type": "socket", "data": {"addr": { "type": "inet", "data": { "host": "127.0.0.1", "port": "9001" } }, "server": false } } } }
+{"execute": "chardev-add", "arguments":{ "id": "compare_out", "backend": {"type": "socket", "data": {"addr": { "type": "inet", "data": { "host": "127.0.0.1", "port": "9005" } }, "server": true } } } }
+{"execute": "chardev-add", "arguments":{ "id": "compare_out0", "backend": {"type": "socket", "data": {"addr": { "type": "inet", "data": { "host": "127.0.0.1", "port": "9005" } }, "server": false } } } }
 
 == Primary resume replication ==
 Resume replication after new Secondary is up.
 
 Start the new Secondary (Steps 2 and 3 above), then on the Primary:
-{'execute': 'drive-mirror', 'arguments':{ 'device': 'colo-disk0', 'job-id': 'resync', 'target': 'nbd://127.0.0.2:9999/parent0', 'mode': 'existing', 'format': 'raw', 'sync': 'full'} }
+{"execute": "drive-mirror", "arguments":{ "device": "colo-disk0", "job-id": "resync", "target": "nbd://127.0.0.2:9999/parent0", "mode": "existing", "format": "raw", "sync": "full"} }
 
 Wait until disk is synced, then:
-{'execute': 'stop'}
-{'execute': 'block-job-cancel', 'arguments':{ 'device': 'resync'} }
+{"execute": "stop"}
+{"execute": "block-job-cancel", "arguments":{ "device": "resync"} }
 
-{'execute': 'human-monitor-command', 'arguments':{ 'command-line': 'drive_add -n buddy driver=replication,mode=primary,file.driver=nbd,file.host=127.0.0.2,file.port=9999,file.export=parent0,node-name=replication0'}}
-{'execute': 'x-blockdev-change', 'arguments':{ 'parent': 'colo-disk0', 'node': 'replication0' } }
+{"execute": "human-monitor-command", "arguments":{ "command-line": "drive_add -n buddy driver=replication,mode=primary,file.driver=nbd,file.host=127.0.0.2,file.port=9999,file.export=parent0,node-name=replication0"}}
+{"execute": "x-blockdev-change", "arguments":{ "parent": "colo-disk0", "node": "replication0" } }
 
-{'execute': 'object-add', 'arguments':{ 'qom-type': 'filter-mirror', 'id': 'm0', 'props': { 'netdev': 'hn0', 'queue': 'tx', 'outdev': 'mirror0' } } }
-{'execute': 'object-add', 'arguments':{ 'qom-type': 'filter-redirector', 'id': 'redire0', 'props': { 'netdev': 'hn0', 'queue': 'rx', 'indev': 'compare_out' } } }
-{'execute': 'object-add', 'arguments':{ 'qom-type': 'filter-redirector', 'id': 'redire1', 'props': { 'netdev': 'hn0', 'queue': 'rx', 'outdev': 'compare0' } } }
-{'execute': 'object-add', 'arguments':{ 'qom-type': 'iothread', 'id': 'iothread1' } }
-{'execute': 'object-add', 'arguments':{ 'qom-type': 'colo-compare', 'id': 'comp0', 'props': { 'primary_in': 'compare0-0', 'secondary_in': 'compare1', 'outdev': 'compare_out0', 'iothread': 'iothread1' } } }
+{"execute": "object-add", "arguments":{ "qom-type": "filter-mirror", "id": "m0", "netdev": "hn0", "queue": "tx", "outdev": "mirror0" } }
+{"execute": "object-add", "arguments":{ "qom-type": "filter-redirector", "id": "redire0", "netdev": "hn0", "queue": "rx", "indev": "compare_out" } }
+{"execute": "object-add", "arguments":{ "qom-type": "filter-redirector", "id": "redire1", "netdev": "hn0", "queue": "rx", "outdev": "compare0" } }
+{"execute": "object-add", "arguments":{ "qom-type": "iothread", "id": "iothread1" } }
+{"execute": "object-add", "arguments":{ "qom-type": "colo-compare", "id": "comp0", "primary_in": "compare0-0", "secondary_in": "compare1", "outdev": "compare_out0", "iothread": "iothread1" } }
 
-{'execute': 'migrate-set-capabilities', 'arguments':{ 'capabilities': [ {'capability': 'x-colo', 'state': true } ] } }
-{'execute': 'migrate', 'arguments':{ 'uri': 'tcp:127.0.0.2:9998' } }
+{"execute": "migrate-set-capabilities", "arguments":{ "capabilities": [ {"capability": "x-colo", "state": true } ] } }
+{"execute": "migrate", "arguments":{ "uri": "tcp:127.0.0.2:9998" } }
 
 Note:
 If this Primary previously was a Secondary, then we need to insert the
 filters before the filter-rewriter by using the
-"'insert': 'before', 'position': 'id=rew0'" Options. See below.
+""insert": "before", "position": "id=rew0"" Options. See below.
 
 == Secondary resume replication ==
 Become Primary and resume replication after new Secondary is up. Note
@@ -309,23 +309,23 @@ that now 127.0.0.1 is the Secondary and 127.0.0.2 is the Primary.
 
 Start the new Secondary (Steps 2 and 3 above, but with primary_ip=127.0.0.2),
 then on the old Secondary:
-{'execute': 'drive-mirror', 'arguments':{ 'device': 'colo-disk0', 'job-id': 'resync', 'target': 'nbd://127.0.0.1:9999/parent0', 'mode': 'existing', 'format': 'raw', 'sync': 'full'} }
+{"execute": "drive-mirror", "arguments":{ "device": "colo-disk0", "job-id": "resync", "target": "nbd://127.0.0.1:9999/parent0", "mode": "existing", "format": "raw", "sync": "full"} }
 
 Wait until disk is synced, then:
-{'execute': 'stop'}
-{'execute': 'block-job-cancel', 'arguments':{ 'device': 'resync' } }
+{"execute": "stop"}
+{"execute": "block-job-cancel", "arguments":{ "device": "resync" } }
 
-{'execute': 'human-monitor-command', 'arguments':{ 'command-line': 'drive_add -n buddy driver=replication,mode=primary,file.driver=nbd,file.host=127.0.0.1,file.port=9999,file.export=parent0,node-name=replication0'}}
-{'execute': 'x-blockdev-change', 'arguments':{ 'parent': 'colo-disk0', 'node': 'replication0' } }
+{"execute": "human-monitor-command", "arguments":{ "command-line": "drive_add -n buddy driver=replication,mode=primary,file.driver=nbd,file.host=127.0.0.1,file.port=9999,file.export=parent0,node-name=replication0"}}
+{"execute": "x-blockdev-change", "arguments":{ "parent": "colo-disk0", "node": "replication0" } }
 
-{'execute': 'object-add', 'arguments':{ 'qom-type': 'filter-mirror', 'id': 'm0', 'props': { 'insert': 'before', 'position': 'id=rew0', 'netdev': 'hn0', 'queue': 'tx', 'outdev': 'mirror0' } } }
-{'execute': 'object-add', 'arguments':{ 'qom-type': 'filter-redirector', 'id': 'redire0', 'props': { 'insert': 'before', 'position': 'id=rew0', 'netdev': 'hn0', 'queue': 'rx', 'indev': 'compare_out' } } }
-{'execute': 'object-add', 'arguments':{ 'qom-type': 'filter-redirector', 'id': 'redire1', 'props': { 'insert': 'before', 'position': 'id=rew0', 'netdev': 'hn0', 'queue': 'rx', 'outdev': 'compare0' } } }
-{'execute': 'object-add', 'arguments':{ 'qom-type': 'iothread', 'id': 'iothread1' } }
-{'execute': 'object-add', 'arguments':{ 'qom-type': 'colo-compare', 'id': 'comp0', 'props': { 'primary_in': 'compare0-0', 'secondary_in': 'compare1', 'outdev': 'compare_out0', 'iothread': 'iothread1' } } }
+{"execute": "object-add", "arguments":{ "qom-type": "filter-mirror", "id": "m0", "insert": "before", "position": "id=rew0", "netdev": "hn0", "queue": "tx", "outdev": "mirror0" } }
+{"execute": "object-add", "arguments":{ "qom-type": "filter-redirector", "id": "redire0", "insert": "before", "position": "id=rew0", "netdev": "hn0", "queue": "rx", "indev": "compare_out" } }
+{"execute": "object-add", "arguments":{ "qom-type": "filter-redirector", "id": "redire1", "insert": "before", "position": "id=rew0", "netdev": "hn0", "queue": "rx", "outdev": "compare0" } }
+{"execute": "object-add", "arguments":{ "qom-type": "iothread", "id": "iothread1" } }
+{"execute": "object-add", "arguments":{ "qom-type": "colo-compare", "id": "comp0", "primary_in": "compare0-0", "secondary_in": "compare1", "outdev": "compare_out0", "iothread": "iothread1" } }
 
-{'execute': 'migrate-set-capabilities', 'arguments':{ 'capabilities': [ {'capability': 'x-colo', 'state': true } ] } }
-{'execute': 'migrate', 'arguments':{ 'uri': 'tcp:127.0.0.1:9998' } }
+{"execute": "migrate-set-capabilities", "arguments":{ "capabilities": [ {"capability": "x-colo", "state": true } ] } }
+{"execute": "migrate", "arguments":{ "uri": "tcp:127.0.0.1:9998" } }
 
 == TODO ==
 1. Support shared storage.
diff --git a/docs/about/removed-features.rst b/docs/about/removed-features.rst
index 9d0d90c90d..d42c3341de 100644
--- a/docs/about/removed-features.rst
+++ b/docs/about/removed-features.rst
@@ -658,8 +658,8 @@ enforce that any failure to open the backing image (including if the
 backing file is missing or an incorrect format was specified) is an
 error when ``-u`` is not used.
 
-qemu-img amend to adjust backing file (removed in 6.1)
-''''''''''''''''''''''''''''''''''''''''''''''''''''''
+``qemu-img amend`` to adjust backing file (removed in 6.1)
+''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
 
 The use of ``qemu-img amend`` to modify the name or format of a qcow2
 backing image was never fully documented or tested, and interferes
@@ -670,8 +670,8 @@ backing chain should be performed with ``qemu-img rebase -u`` either
 before or after the remaining changes being performed by amend, as
 appropriate.
 
-qemu-img backing file without format (removed in 6.1)
-'''''''''''''''''''''''''''''''''''''''''''''''''''''
+``qemu-img`` backing file without format (removed in 6.1)
+'''''''''''''''''''''''''''''''''''''''''''''''''''''''''
 
 The use of ``qemu-img create``, ``qemu-img rebase``, or ``qemu-img
 convert`` to create or modify an image that depends on a backing file
diff --git a/docs/block-replication.txt b/docs/block-replication.txt
index 59eb2b33b3..b0f23761c6 100644
--- a/docs/block-replication.txt
+++ b/docs/block-replication.txt
@@ -156,15 +156,15 @@ Primary:
          children.0.driver=raw
 
   Run qmp command in primary qemu:
-    { 'execute': 'human-monitor-command',
-      'arguments': {
-          'command-line': 'drive_add -n buddy driver=replication,mode=primary,file.driver=nbd,file.host=xxxx,file.port=xxxx,file.export=colo1,node-name=nbd_client1'
+    { "execute": "human-monitor-command",
+      "arguments": {
+          "command-line": "drive_add -n buddy driver=replication,mode=primary,file.driver=nbd,file.host=xxxx,file.port=xxxx,file.export=colo1,node-name=nbd_client1"
       }
     }
-    { 'execute': 'x-blockdev-change',
-      'arguments': {
-          'parent': 'colo1',
-          'node': 'nbd_client1'
+    { "execute": "x-blockdev-change",
+      "arguments": {
+          "parent": "colo1",
+          "node": "nbd_client1"
       }
     }
   Note:
@@ -189,21 +189,21 @@ Secondary:
          vote-threshold=1,children.0=childs1
 
   Then run qmp command in secondary qemu:
-    { 'execute': 'nbd-server-start',
-      'arguments': {
-          'addr': {
-              'type': 'inet',
-              'data': {
-                  'host': 'xxx',
-                  'port': 'xxx'
+    { "execute": "nbd-server-start",
+      "arguments": {
+          "addr": {
+              "type": "inet",
+              "data": {
+                  "host": "xxx",
+                  "port": "xxx"
               }
           }
       }
     }
-    { 'execute': 'nbd-server-add',
-      'arguments': {
-          'device': 'colo1',
-          'writable': true
+    { "execute": "nbd-server-add",
+      "arguments": {
+          "device": "colo1",
+          "writable": true
       }
     }
 
@@ -223,22 +223,22 @@ After Failover:
 Primary:
   The secondary host is down, so we should run the following qmp command
   to remove the nbd child from the quorum:
-  { 'execute': 'x-blockdev-change',
-    'arguments': {
-        'parent': 'colo1',
-        'child': 'children.1'
+  { "execute": "x-blockdev-change",
+    "arguments": {
+        "parent": "colo1",
+        "child": "children.1"
     }
   }
-  { 'execute': 'human-monitor-command',
-    'arguments': {
-        'command-line': 'drive_del xxxx'
+  { "execute": "human-monitor-command",
+    "arguments": {
+        "command-line": "drive_del xxxx"
     }
   }
   Note: there is no qmp command to remove the blockdev now
 
 Secondary:
   The primary host is down, so we should do the following thing:
-  { 'execute': 'nbd-server-stop' }
+  { "execute": "nbd-server-stop" }
 
 Promote Secondary to Primary:
   see COLO-FT.txt
diff --git a/docs/devel/build-system.rst b/docs/devel/build-system.rst
index 7a83f5fc0d..431caba7aa 100644
--- a/docs/devel/build-system.rst
+++ b/docs/devel/build-system.rst
@@ -121,11 +121,11 @@ process for:
 
 1) executables, which include:
 
-   - Tools - qemu-img, qemu-nbd, qga (guest agent), etc
+   - Tools - ``qemu-img``, ``qemu-nbd``, ``qga`` (guest agent), etc
 
-   - System emulators - qemu-system-$ARCH
+   - System emulators - ``qemu-system-$ARCH``
 
-   - Userspace emulators - qemu-$ARCH
+   - Userspace emulators - ``qemu-$ARCH``
 
    - Unit tests
 
diff --git a/docs/devel/multi-process.rst b/docs/devel/multi-process.rst
index e5758a79ab..e4801751f2 100644
--- a/docs/devel/multi-process.rst
+++ b/docs/devel/multi-process.rst
@@ -187,9 +187,9 @@ desired, in which the emulation application should only be allowed to
 access the files or devices the VM it's running on behalf of can access.
 #### qemu-io model
 
-Qemu-io is a test harness used to test changes to the QEMU block backend
-object code. (e.g., the code that implements disk images for disk driver
-emulation) Qemu-io is not a device emulation application per se, but it
+``qemu-io`` is a test harness used to test changes to the QEMU block backend
+object code (e.g., the code that implements disk images for disk driver
+emulation). ``qemu-io`` is not a device emulation application per se, but it
 does compile the QEMU block objects into a separate binary from the main
 QEMU one. This could be useful for disk device emulation, since its
 emulation applications will need to include the QEMU block objects.
@@ -641,7 +641,7 @@ the CPU that issued the MMIO.
 +==========+========================+
 | rid      | range MMIO is within   |
 +----------+------------------------+
-| offset   | offset withing *rid*   |
+| offset   | offset within *rid*    |
 +----------+------------------------+
 | type     | e.g., load or store    |
 +----------+------------------------+
diff --git a/docs/devel/qgraph.rst b/docs/devel/qgraph.rst
index db44d71002..43342d9d65 100644
--- a/docs/devel/qgraph.rst
+++ b/docs/devel/qgraph.rst
@@ -14,7 +14,7 @@ support that device.
 Using only libqos APIs, the test has to manually take care of
 covering all the setups, and build the correct command line.
 
-This also introduces backward compability issues: if a device/driver command
+This also introduces backward compatibility issues: if a device/driver command
 line name is changed, all tests that use that will not work
 properly anymore and need to be adjusted.
 
diff --git a/docs/devel/stable-process.rst b/docs/devel/stable-process.rst
index e541b983fa..c21fb86645 100644
--- a/docs/devel/stable-process.rst
+++ b/docs/devel/stable-process.rst
@@ -1,3 +1,5 @@
+.. _stable-process:
+
 QEMU and the stable process
 ===========================
 
diff --git a/docs/devel/style.rst b/docs/devel/style.rst
index e00af62e76..9c5c0fffd9 100644
--- a/docs/devel/style.rst
+++ b/docs/devel/style.rst
@@ -1,3 +1,5 @@
+.. _coding-style:
+
 =================
 QEMU Coding Style
 =================
diff --git a/docs/devel/submitting-a-patch.rst b/docs/devel/submitting-a-patch.rst
index 6fefc67d52..e51259eb9c 100644
--- a/docs/devel/submitting-a-patch.rst
+++ b/docs/devel/submitting-a-patch.rst
@@ -1,3 +1,5 @@
+.. _submitting-a-patch:
+
 Submitting a Patch
 ==================
 
@@ -20,11 +22,11 @@ one-shot fix, the bare minimum we ask is that:
    should not be posted on the bug tracker, posted on forums, or
    externally hosted and linked to. (We have other mailing lists too,
    but all patches must go to qemu-devel, possibly with a Cc: to another
-   list.) ``git send-email`` works best for delivering the patch without
-   mangling it (`hints for setting it
-   up <http://lxr.free-electrons.com/source/Documentation/process/email-clients.rst>`__),
-   but attachments can be used as a last resort on a first-time
-   submission.
+   list.) ``git send-email`` (`step-by-step setup
+   guide <https://git-send-email.io/>`__ and `hints and
+   tips <https://elixir.bootlin.com/linux/latest/source/Documentation/process/email-clients.rst>`__)
+   works best for delivering the patch without mangling it, but
+   attachments can be used as a last resort on a first-time submission.
 -  You must read replies to your message, and be willing to act on them.
    Note, however, that maintainers are often willing to manually fix up
    first-time contributions, since there is a learning curve involved in
@@ -45,6 +47,8 @@ Reading the table of contents below should already give you an idea of
 the basic requirements. Use the table of contents as a reference, and
 read the parts that you have doubts about.
 
+.. contents:: Table of Contents
+
 .. _writing_your_patches:
 
 Writing your Patches
@@ -60,11 +64,9 @@ check that you are in compliance with our coding standards. Be aware
 that ``checkpatch.pl`` is not infallible, though, especially where C
 preprocessor macros are involved; use some common sense too. See also:
 
-- `QEMU Coding Style
-  <https://qemu-project.gitlab.io/qemu/devel/style.html>`__
-
+-  :ref:`coding-style`
 -  `Automate a checkpatch run on
-   commit <http://blog.vmsplice.net/2011/03/how-to-automatically-run-checkpatchpl.html>`__
+   commit <https://blog.vmsplice.net/2011/03/how-to-automatically-run-checkpatchpl.html>`__
 
 .. _base_patches_against_current_git_master:
 
@@ -76,6 +78,13 @@ of QEMU because development will have moved on from then and it probably
 won't even apply to master. We only apply selected bugfixes to release
 branches and then only as backports once the code has gone into master.
 
+It is also okay to base patches on top of other on-going work that is
+not yet part of the git master branch. To aid continuous integration
+tools, such as `patchew <http://patchew.org/QEMU/>`__, you should `add a
+tag <https://lists.gnu.org/archive/html/qemu-devel/2017-08/msg01288.html>`__
+line ``Based-on: $MESSAGE_ID`` to your cover letter to make the series
+dependency obvious.
+
 .. _split_up_long_patches:
 
 Split up long patches
@@ -104,18 +113,17 @@ Make code motion patches easy to review
 If a series requires large blocks of code motion, there are tricks for
 making the refactoring easier to review. Split up the series so that
 semantic changes (or even function renames) are done in a separate patch
-from the raw code motion. Use a one-time setup of
-``git config diff.renames true; git config diff.algorithm patience``
-(Refer to `git-config <http://git-scm.com/docs/git-config>`__.)  The
-``diff.renames`` property ensures file rename patches will be given in a
-more compact representation that focuses only on the differences across
-the file rename, instead of showing the entire old file as a deletion
-and the new file as an insertion. Meanwhile, the 'diff.algorithm'
-property ensures that extracting a non-contiguous subset of one file
-into a new file, but where all extracted parts occur in the same order
-both before and after the patch, will reduce churn in trying to treat
-unrelated ``}`` lines in the original file as separating hunks of
-changes.
+from the raw code motion. Use a one-time setup of ``git config
+diff.renames true;`` ``git config diff.algorithm patience`` (refer to
+`git-config <http://git-scm.com/docs/git-config>`__). The 'diff.renames'
+property ensures file rename patches will be given in a more compact
+representation that focuses only on the differences across the file
+rename, instead of showing the entire old file as a deletion and the new
+file as an insertion. Meanwhile, the 'diff.algorithm' property ensures
+that extracting a non-contiguous subset of one file into a new file, but
+where all extracted parts occur in the same order both before and after
+the patch, will reduce churn in trying to treat unrelated ``}`` lines in
+the original file as separating hunks of changes.
 
 Ideally, a code motion patch can be reviewed by doing::
 
@@ -138,8 +146,7 @@ as a separate patch which makes no semantic changes; don't put it in the
 same patch as your bug fix.
 
 For smaller patches in less frequently changed areas of QEMU, consider
-using the `trivial patches process
-<https://qemu-project.gitlab.io/qemu/devel/style.html>`__.
+using the :ref:`trivial-patches` process.
 
 .. _write_a_meaningful_commit_message:
 
@@ -154,7 +161,7 @@ QEMU follows the usual standard for git commit messages: the first line
 (which becomes the email subject line) is "subsystem: single line
 summary of change". Whether the "single line summary of change" starts
 with a capital is a matter of taste, but we prefer that the summary does
-not end in ".". Look at ``git shortlog -30`` for an idea of sample
+not end in a dot. Look at ``git shortlog -30`` for an idea of sample
 subject lines. Then there is a blank line and a more detailed
 description of the patch, another blank and your Signed-off-by: line.
 Please do not use lines that are longer than 76 characters in your
@@ -170,11 +177,79 @@ displays the subject line some distance apart (that is, a body that
 starts with "... so that" as a continuation of the subject line is
 harder to follow).
 
+If your patch fixes a commit that is already in the repository, please
+add an additional line with "Fixes: <at-least-12-digits-of-SHA-commit-id>
+("Fixed commit subject")" below the patch description / before your
+"Signed-off-by:" line in the commit message.
+
+If your patch fixes a bug in the gitlab bug tracker, please add a line
+with "Resolves: <URL-of-the-bug>" to the commit message, too. Gitlab can
+close bugs automatically once commits with the "Resolved:" keyword get
+merged into the master branch of the project. And if your patch addresses
+a bug in another public bug tracker, you can also use a line with
+"Buglink: <URL-of-the-bug>" for reference here, too.
+
+Example::
+
+ Fixes: 14055ce53c2d ("s390x/tcg: avoid overflows in time2tod/tod2time")
+ Resolves: https://gitlab.com/qemu-project/qemu/-/issues/42
+ Buglink: https://bugs.launchpad.net/qemu/+bug/1804323``
+
+Some other tags that are used in commit messages include "Message-Id:"
+"Tested-by:", "Acked-by:", "Reported-by:", "Suggested-by:".  See ``git
+log`` for these keywords for example usage.
+
+.. _test_your_patches:
+
+Test your patches
+~~~~~~~~~~~~~~~~~
+
+Although QEMU has `continuous integration
+services <Testing#Continuous_Integration>`__ that attempt to test
+patches submitted to the list, it still saves everyone time if you have
+already tested that your patch compiles and works. Because QEMU is such
+a large project, it's okay to use configure arguments to limit what is
+built for faster turnaround during your development time; but it is
+still wise to also check that your patches work with a full build before
+submitting a series, especially if your changes might have an unintended
+effect on other areas of the code you don't normally experiment with.
+See `Testing <Testing>`__ for more details on what tests are available.
+Also, it is a wise idea to include a testsuite addition as part of your
+patches - either to ensure that future changes won't regress your new
+feature, or to add a test which exposes the bug that the rest of your
+series fixes. Keeping separate commits for the test and the fix allows
+reviewers to rebase the test to occur first to prove it catches the
+problem, then again to place it last in the series so that bisection
+doesn't land on a known-broken state.
+
 .. _submitting_your_patches:
 
 Submitting your Patches
 -----------------------
 
+.. _if_you_cannot_send_patch_emails:
+
+If you cannot send patch emails
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In rare cases it may not be possible to send properly formatted patch
+emails. You can use `sourcehut <https://sourcehut.org/>`__ to send your
+patches to the QEMU mailing list by following these steps:
+
+#. Register or sign in to your account
+#. Add your SSH public key in `meta \|
+   keys <https://meta.sr.ht/keys>`__.
+#. Publish your git branch using **git push git@git.sr.ht:~USERNAME/qemu
+   HEAD**
+#. Send your patches to the QEMU mailing list using the web-based
+   ``git-send-email`` UI at https://git.sr.ht/~USERNAME/qemu/send-email
+
+`This video
+<https://spacepub.space/videos/watch/ad258d23-0ac6-488c-83fc-2bacf578de3a>`__
+shows the web-based ``git-send-email`` workflow. Documentation is
+available `here
+<https://man.sr.ht/git.sr.ht/#sending-patches-upstream>`__.
+
 .. _cc_the_relevant_maintainer:
 
 CC the relevant maintainer
@@ -219,17 +294,26 @@ such as 'git-email' on Fedora-based systems.) Patch series need a cover
 letter, with shallow threading (all patches in the series are
 in-reply-to the cover letter, but not to each other); single unrelated
 patches do not need a cover letter (but if you do send a cover letter,
-use --numbered so the cover and the patch have distinct subject lines).
+use ``--numbered`` so the cover and the patch have distinct subject lines).
 Patches are easier to find if they start a new top-level thread, rather
 than being buried in-reply-to another existing thread.
 
+.. _avoid_posting_large_binary_blob:
+
+Avoid posting large binary blob
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you added binaries to the repository, consider producing the patch
+emails using ``git format-patch --no-binary`` and include a link to a
+git repository to fetch the original commit.
+
 .. _patch_emails_must_include_a_signed_off_by_line:
 
 Patch emails must include a ``Signed-off-by:`` line
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-For more information see `1.12) Sign your work
-<http://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/Documentation/SubmittingPatches?id=f6f94e2ab1b33f0082ac22d71f66385a60d8157f#n296>`__.
+For more information see `SubmittingPatches 1.12
+<http://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/Documentation/SubmittingPatches?id=f6f94e2ab1b33f0082ac22d71f66385a60d8157f#n297>`__.
 This is vital or we will not be able to apply your patch! Please use
 your real name to sign a patch (not an alias or acronym).
 
@@ -246,8 +330,13 @@ that author's Signed-off-by: line is mandatory, with the same spelling.
 Include a meaningful cover letter
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-This usually applies only to a series that includes multiple patches;
-the cover letter explains the overall goal of such a series.
+This is a requirement for any series with multiple patches (as it aids
+continuous integration), but optional for an isolated patch. The cover
+letter explains the overall goal of such a series, and also provides a
+convenient 0/N email for others to reply to the series as a whole. A
+one-time setup of ``git config format.coverletter auto`` (refer to
+`git-config <http://git-scm.com/docs/git-config>`__) will generate the
+cover letter as needed.
 
 When reviewers don't know your goal at the start of their review, they
 may object to early changes that don't make sense until the end of the
@@ -288,6 +377,18 @@ it's best to:
    of the patchset you're looking for review on, and why reviewers
    should care
 
+.. _consider_whether_your_patch_is_applicable_for_stable:
+
+Consider whether your patch is applicable for stable
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If your patch fixes a severe issue or a regression, it may be applicable
+for stable. In that case, consider adding ``Cc: qemu-stable@nongnu.org``
+to your patch to notify the stable maintainers.
+
+For more details on how QEMU's stable process works, refer to the
+:ref:`stable-process` page.
+
 .. _participating_in_code_review:
 
 Participating in Code Review
@@ -367,19 +468,19 @@ Include version history in patchset revisions
 
 For later versions of patches, include a summary of changes from
 previous versions, but not in the commit message itself. In an email
-formatted as a git patch, the commit message is the part above the "---"
+formatted as a git patch, the commit message is the part above the ``---``
 line, and this will go into the git changelog when the patch is
 committed. This part should be a self-contained description of what this
 version of the patch does, written to make sense to anybody who comes
 back to look at this commit in git in six months' time. The part below
-the "---" line and above the patch proper (git format-patch puts the
+the ``---`` line and above the patch proper (git format-patch puts the
 diffstat here) is a good place to put remarks for people reading the
 patch email, and this is where the "changes since previous version"
-summary belongs. The
-`git-publish <https://github.com/stefanha/git-publish>`__ script can
-help with tracking a good summary across versions. Also, the
-`git-backport-diff <https://github.com/codyprime/git-scripts>`__ script
-can help focus reviewers on what changed between revisions.
+summary belongs. The `git-publish
+<https://github.com/stefanha/git-publish>`__ script can help with
+tracking a good summary across versions. Also, the `git-backport-diff
+<https://github.com/codyprime/git-scripts>`__ script can help focus
+reviewers on what changed between revisions.
 
 .. _tips_and_tricks:
 
@@ -411,27 +512,32 @@ If your patch seems to have been ignored
 If your patchset has received no replies you should "ping" it after a
 week or two, by sending an email as a reply-to-all to the patch mail,
 including the word "ping" and ideally also a link to the page for the
-patch on
-`patchwork <http://patchwork.ozlabs.org/project/qemu-devel/list/>`__ or
-GMANE. It's worth double-checking for reasons why your patch might have
-been ignored (forgot to CC the maintainer? annoyed people by failing to
-respond to review comments on an earlier version?), but often for
-less-maintained areas of QEMU patches do just slip through the cracks.
-If your ping is also ignored, ping again after another week or so. As
-the submitter, you are the person with the most motivation to get your
-patch applied, so you have to be persistent.
+patch on `patchew <https://patchew.org/QEMU/>`__ or
+`lore.kernel.org <https://lore.kernel.org/qemu-devel/>`__. It's worth
+double-checking for reasons why your patch might have been ignored
+(forgot to CC the maintainer? annoyed people by failing to respond to
+review comments on an earlier version?), but often for less-maintained
+areas of QEMU patches do just slip through the cracks. If your ping is
+also ignored, ping again after another week or so. As the submitter, you
+are the person with the most motivation to get your patch applied, so
+you have to be persistent.
 
 .. _is_my_patch_in:
 
 Is my patch in?
 ~~~~~~~~~~~~~~~
 
+QEMU has some Continuous Integration machines that try to catch patch
+submission problems as soon as possible.  `patchew
+<http://patchew.org/QEMU/>`__ includes a web interface for tracking the
+status of various threads that have been posted to the list, and may
+send you an automated mail if it detected a problem with your patch.
+
 Once your patch has had enough review on list, the maintainer for that
 area of code will send notification to the list that they are including
 your patch in a particular staging branch. Periodically, the maintainer
-then sends a `pull request
-<https://qemu-project.gitlab.io/qemu/devel/submitting-a-pull-request.html>`__
-for aggregating topic branches into mainline qemu. Generally, you do not
+then takes care of :ref:`submitting-a-pull-request`
+for aggregating topic branches into mainline QEMU. Generally, you do not
 need to send a pull request unless you have contributed enough patches
 to become a maintainer over a particular section of code. Maintainers
 may further modify your commit, by resolving simple merge conflicts or
diff --git a/docs/devel/submitting-a-pull-request.rst b/docs/devel/submitting-a-pull-request.rst
index 8729d29036..c9d1e8afd9 100644
--- a/docs/devel/submitting-a-pull-request.rst
+++ b/docs/devel/submitting-a-pull-request.rst
@@ -1,10 +1,11 @@
-Submit a Pull Request
-=====================
+.. _submitting-a-pull-request:
+
+Submitting a Pull Request
+=========================
 
 QEMU welcomes contributions of code, but we generally expect these to be
 sent as simple patch emails to the mailing list (see our page on
-`submitting a patch
-<https://qemu-project.gitlab.io/qemu/devel/submitting-a-patch.html>`__
+:ref:`submitting-a-patch`
 for more details).  Generally only existing submaintainers of a tree
 will need to submit pull requests, although occasionally for a large
 patch series we might ask a submitter to send a pull request. This page
diff --git a/docs/devel/testing.rst b/docs/devel/testing.rst
index 60c59023e5..755343c7dd 100644
--- a/docs/devel/testing.rst
+++ b/docs/devel/testing.rst
@@ -564,11 +564,11 @@ exploiting a QEMU security bug to compromise the host.
 QEMU binaries
 ~~~~~~~~~~~~~
 
-By default, qemu-system-x86_64 is searched in $PATH to run the guest. If there
-isn't one, or if it is older than 2.10, the test won't work. In this case,
+By default, ``qemu-system-x86_64`` is searched in $PATH to run the guest. If
+there isn't one, or if it is older than 2.10, the test won't work. In this case,
 provide the QEMU binary in env var: ``QEMU=/path/to/qemu-2.10+``.
 
-Likewise the path to qemu-img can be set in QEMU_IMG environment variable.
+Likewise the path to ``qemu-img`` can be set in QEMU_IMG environment variable.
 
 Make jobs
 ~~~~~~~~~
@@ -650,7 +650,7 @@ supported. To start the fuzzer, run
 
   tests/image-fuzzer/runner.py -c '[["qemu-img", "info", "$test_img"]]' /tmp/test qcow2
 
-Alternatively, some command different from "qemu-img info" can be tested, by
+Alternatively, some command different from ``qemu-img info`` can be tested, by
 changing the ``-c`` option.
 
 Integration tests using the Avocado Framework
diff --git a/docs/devel/trivial-patches.rst b/docs/devel/trivial-patches.rst
index db3f2001da..9380c730f7 100644
--- a/docs/devel/trivial-patches.rst
+++ b/docs/devel/trivial-patches.rst
@@ -1,3 +1,5 @@
+.. _trivial-patches:
+
 Trivial Patches
 ===============
 
diff --git a/docs/devel/writing-monitor-commands.rst b/docs/devel/writing-monitor-commands.rst
index b3e2c8481d..1693822f8f 100644
--- a/docs/devel/writing-monitor-commands.rst
+++ b/docs/devel/writing-monitor-commands.rst
@@ -677,7 +677,7 @@ return a single text string::
 
 The ``HumanReadableText`` struct is intended to be used for all
 commands, under the ``x-`` name prefix that are returning unstructured
-text targetted at humans. It should never be used for commands outside
+text targeted at humans. It should never be used for commands outside
 the ``x-`` name prefix, as those should be using structured QAPI types.
 
 Implementing the QMP command
diff --git a/docs/hyperv.txt b/docs/hyperv.txt
index 5d99fd9a72..0417c183a3 100644
--- a/docs/hyperv.txt
+++ b/docs/hyperv.txt
@@ -195,7 +195,7 @@ The enlightenment allows to use Hyper-V SynIC with hardware APICv/AVIC enabled.
 Normally, Hyper-V SynIC disables these hardware feature and suggests the guest
 to use paravirtualized AutoEOI feature.
 Note: enabling this feature on old hardware (without APICv/AVIC support) may
-have negative effect on guest's performace.
+have negative effect on guest's performance.
 
 3.19. hv-no-nonarch-coresharing=on/off/auto
 ===========================================
diff --git a/docs/image-fuzzer.txt b/docs/image-fuzzer.txt
index 3e23ebec33..279cc8c807 100644
--- a/docs/image-fuzzer.txt
+++ b/docs/image-fuzzer.txt
@@ -51,10 +51,10 @@ assumes that core dumps will be generated in the current working directory.
 For comprehensive test results, please, set up your test environment
 properly.
 
-Paths to binaries under test (SUTs) qemu-img and qemu-io are retrieved from
-environment variables. If the environment check fails the runner will
+Paths to binaries under test (SUTs) ``qemu-img`` and ``qemu-io`` are retrieved
+from environment variables. If the environment check fails the runner will
 use SUTs installed in system paths.
-qemu-img is required for creation of backing files, so it's mandatory to set
+``qemu-img`` is required for creation of backing files, so it's mandatory to set
 the related environment variable if it's not installed in the system path.
 For details about environment variables see qemu-iotests/check.
 
diff --git a/docs/system/arm/orangepi.rst b/docs/system/arm/orangepi.rst
index c55694dd91..83c7445197 100644
--- a/docs/system/arm/orangepi.rst
+++ b/docs/system/arm/orangepi.rst
@@ -128,7 +128,7 @@ Alternatively, you can also choose to build you own image with buildroot
 using the orangepi_pc_defconfig. Also see https://buildroot.org for more information.
 
 When using an image as an SD card, it must be resized to a power of two. This can be
-done with the qemu-img command. It is recommended to only increase the image size
+done with the ``qemu-img`` command. It is recommended to only increase the image size
 instead of shrinking it to a power of two, to avoid loss of data. For example,
 to prepare a downloaded Armbian image, first extract it and then increase
 its size to one gigabyte as follows:
diff --git a/docs/system/authz.rst b/docs/system/authz.rst
index 942af39602..55b7315e49 100644
--- a/docs/system/authz.rst
+++ b/docs/system/authz.rst
@@ -77,9 +77,7 @@ To create an instance of this driver via QMP:
      "arguments": {
        "qom-type": "authz-simple",
        "id": "authz0",
-       "props": {
-         "identity": "fred"
-       }
+       "identity": "fred"
      }
    }
 
@@ -110,15 +108,13 @@ To create an instance of this class via QMP:
      "arguments": {
        "qom-type": "authz-list",
        "id": "authz0",
-       "props": {
-         "rules": [
-            { "match": "fred", "policy": "allow", "format": "exact" },
-            { "match": "bob", "policy": "allow", "format": "exact" },
-            { "match": "danb", "policy": "deny", "format": "exact" },
-            { "match": "dan*", "policy": "allow", "format": "glob" }
-         ],
-         "policy": "deny"
-       }
+       "rules": [
+          { "match": "fred", "policy": "allow", "format": "exact" },
+          { "match": "bob", "policy": "allow", "format": "exact" },
+          { "match": "danb", "policy": "deny", "format": "exact" },
+          { "match": "dan*", "policy": "allow", "format": "glob" }
+       ],
+       "policy": "deny"
      }
    }
 
@@ -143,10 +139,8 @@ To create an instance of this class via QMP:
      "arguments": {
        "qom-type": "authz-list-file",
        "id": "authz0",
-       "props": {
-         "filename": "/etc/qemu/myvm-vnc.acl",
-         "refresh": true
-       }
+       "filename": "/etc/qemu/myvm-vnc.acl",
+       "refresh": true
      }
    }
 
diff --git a/docs/system/cpu-models-x86.rst.inc b/docs/system/cpu-models-x86.rst.inc
index 6e8be7d79b..7f6368f999 100644
--- a/docs/system/cpu-models-x86.rst.inc
+++ b/docs/system/cpu-models-x86.rst.inc
@@ -49,7 +49,7 @@ future OS and toolchains are likely to target newer ABIs. The
 table that follows illustrates which ABI compatibility levels
 can be satisfied by the QEMU CPU models. Note that the table only
 lists the long term stable CPU model versions (eg Haswell-v4).
-In addition to whats listed, there are also many CPU model
+In addition to what is listed, there are also many CPU model
 aliases which resolve to a different CPU model version,
 depending on the machine type is in use.
 
diff --git a/docs/system/devices/nvme.rst b/docs/system/devices/nvme.rst
index a1c0db01f6..b5acb2a9c1 100644
--- a/docs/system/devices/nvme.rst
+++ b/docs/system/devices/nvme.rst
@@ -70,7 +70,7 @@ namespaces and additional features, the ``nvme-ns`` device must be used.
 
 The namespaces defined by the ``nvme-ns`` device will attach to the most
 recently defined ``nvme-bus`` that is created by the ``nvme`` device. Namespace
-identifers are allocated automatically, starting from ``1``.
+identifiers are allocated automatically, starting from ``1``.
 
 There are a number of parameters available:
 
diff --git a/docs/system/gdb.rst b/docs/system/gdb.rst
index bdb42dae2f..453eb73f6c 100644
--- a/docs/system/gdb.rst
+++ b/docs/system/gdb.rst
@@ -56,7 +56,7 @@ machine has more than one CPU, QEMU exposes each CPU cluster as a
 separate "inferior", where each CPU within the cluster is a separate
 "thread". Most QEMU machine types have identical CPUs, so there is a
 single cluster which has all the CPUs in it.  A few machine types are
-heterogenous and have multiple clusters: for example the ``sifive_u``
+heterogeneous and have multiple clusters: for example the ``sifive_u``
 machine has a cluster with one E51 core and a second cluster with four
 U54 cores. Here the E51 is the only thread in the first inferior, and
 the U54 cores are all threads in the second inferior.
diff --git a/docs/system/images.rst b/docs/system/images.rst
index 3d9144e625..d000bd6b6f 100644
--- a/docs/system/images.rst
+++ b/docs/system/images.rst
@@ -20,7 +20,7 @@ where myimage.img is the disk image filename and mysize is its size in
 kilobytes. You can add an ``M`` suffix to give the size in megabytes and
 a ``G`` suffix for gigabytes.
 
-See the qemu-img invocation documentation for more information.
+See the ``qemu-img`` invocation documentation for more information.
 
 .. _disk_005fimages_005fsnapshot_005fmode:
 
diff --git a/docs/system/ppc/ppce500.rst b/docs/system/ppc/ppce500.rst
index afc58f60f5..9beef39171 100644
--- a/docs/system/ppc/ppce500.rst
+++ b/docs/system/ppc/ppce500.rst
@@ -75,7 +75,7 @@ as the BIOS. QEMU follows below truth table to select which payload to execute:
 When both -bios and -kernel are present, QEMU loads U-Boot and U-Boot in turns
 automatically loads the kernel image specified by the -kernel parameter via
 U-Boot's built-in "bootm" command, hence a legacy uImage format is required in
-such senario.
+such scenario.
 
 Running Linux kernel
 --------------------
diff --git a/docs/system/qemu-block-drivers.rst.inc b/docs/system/qemu-block-drivers.rst.inc
index 16225710eb..e313784426 100644
--- a/docs/system/qemu-block-drivers.rst.inc
+++ b/docs/system/qemu-block-drivers.rst.inc
@@ -511,13 +511,13 @@ of an inet socket:
 
   |qemu_system| linux.img -hdb nbd+unix://?socket=/tmp/my_socket
 
-In this case, the block device must be exported using qemu-nbd:
+In this case, the block device must be exported using ``qemu-nbd``:
 
 .. parsed-literal::
 
   qemu-nbd --socket=/tmp/my_socket my_disk.qcow2
 
-The use of qemu-nbd allows sharing of a disk between several guests:
+The use of ``qemu-nbd`` allows sharing of a disk between several guests:
 
 .. parsed-literal::
 
@@ -530,7 +530,7 @@ and then you can use it with two guests:
   |qemu_system| linux1.img -hdb nbd+unix://?socket=/tmp/my_socket
   |qemu_system| linux2.img -hdb nbd+unix://?socket=/tmp/my_socket
 
-If the nbd-server uses named exports (supported since NBD 2.9.18, or with QEMU's
+If the ``nbd-server`` uses named exports (supported since NBD 2.9.18, or with QEMU's
 own embedded NBD server), you must specify an export name in the URI:
 
 .. parsed-literal::
diff --git a/docs/system/riscv/shakti-c.rst b/docs/system/riscv/shakti-c.rst
index a6035d42b0..fea57f7b6b 100644
--- a/docs/system/riscv/shakti-c.rst
+++ b/docs/system/riscv/shakti-c.rst
@@ -45,7 +45,7 @@ Shakti SDK can be used to generate the baremetal example UART applications.
 Binary would be generated in:
   software/examples/uart_applns/loopback/output/loopback.shakti
 
-You could also download the precompiled example applicatons using below
+You could also download the precompiled example applications using below
 commands.
 
 .. code-block:: bash
diff --git a/docs/system/tls.rst b/docs/system/tls.rst
index b0973afe1b..1a04674362 100644
--- a/docs/system/tls.rst
+++ b/docs/system/tls.rst
@@ -311,7 +311,7 @@ containing one or more usernames and random keys::
    mkdir -m 0700 /tmp/keys
    psktool -u rich -p /tmp/keys/keys.psk
 
-TLS-enabled servers such as qemu-nbd can use this directory like so::
+TLS-enabled servers such as ``qemu-nbd`` can use this directory like so::
 
    qemu-nbd \
      -t -x / \
diff --git a/docs/throttle.txt b/docs/throttle.txt
index b5b78b7326..0a0453a5ee 100644
--- a/docs/throttle.txt
+++ b/docs/throttle.txt
@@ -273,11 +273,9 @@ A group can be created using the object-add QMP function:
      "arguments": {
        "qom-type": "throttle-group",
        "id": "group0",
-       "props": {
-         "limits" : {
-           "iops-total": 1000
-           "bps-write": 2097152
-         }
+       "limits" : {
+         "iops-total": 1000,
+         "bps-write": 2097152
        }
      }
    }
diff --git a/docs/tools/qemu-img.rst b/docs/tools/qemu-img.rst
index c0a4443146..d663dd92bd 100644
--- a/docs/tools/qemu-img.rst
+++ b/docs/tools/qemu-img.rst
@@ -127,9 +127,9 @@ by the used format or see the format descriptions below for details.
 .. option:: -S SIZE
 
   Indicates the consecutive number of bytes that must contain only zeros
-  for qemu-img to create a sparse image during conversion. This value is rounded
-  down to the nearest 512 bytes. You may use the common size suffixes like
-  ``k`` for kilobytes.
+  for ``qemu-img`` to create a sparse image during conversion. This value is
+  rounded down to the nearest 512 bytes. You may use the common size suffixes
+  like ``k`` for kilobytes.
 
 .. option:: -t CACHE
 
@@ -431,7 +431,7 @@ Command description:
   suppressed from the destination image.
 
   *SPARSE_SIZE* indicates the consecutive number of bytes (defaults to 4k)
-  that must contain only zeros for qemu-img to create a sparse image during
+  that must contain only zeros for ``qemu-img`` to create a sparse image during
   conversion. If *SPARSE_SIZE* is 0, the source will not be scanned for
   unallocated or zero sectors, and the destination image will always be
   fully allocated.
@@ -447,7 +447,7 @@ Command description:
   If the ``-n`` option is specified, the target volume creation will be
   skipped. This is useful for formats such as ``rbd`` if the target
   volume has already been created with site specific options that cannot
-  be supplied through qemu-img.
+  be supplied through ``qemu-img``.
 
   Out of order writes can be enabled with ``-W`` to improve performance.
   This is only recommended for preallocated devices like host devices or other
@@ -472,7 +472,7 @@ Command description:
   If the option *BACKING_FILE* is specified, then the image will record
   only the differences from *BACKING_FILE*. No size needs to be specified in
   this case. *BACKING_FILE* will never be modified unless you use the
-  ``commit`` monitor command (or qemu-img commit).
+  ``commit`` monitor command (or ``qemu-img commit``).
 
   If a relative path name is given, the backing file is looked up relative to
   the directory containing *FILENAME*.
@@ -684,7 +684,7 @@ Command description:
 
   Safe mode
     This is the default mode and performs a real rebase operation. The
-    new backing file may differ from the old one and qemu-img rebase
+    new backing file may differ from the old one and ``qemu-img rebase``
     will take care of keeping the guest-visible content of *FILENAME*
     unchanged.
 
@@ -697,7 +697,7 @@ Command description:
     exists.
 
   Unsafe mode
-    qemu-img uses the unsafe mode if ``-u`` is specified. In this
+    ``qemu-img`` uses the unsafe mode if ``-u`` is specified. In this
     mode, only the backing file name and format of *FILENAME* is changed
     without any checks on the file contents. The user must take care of
     specifying the correct new backing file, or the guest-visible
@@ -735,7 +735,7 @@ Command description:
   sizes accordingly.  Failure to do so will result in data loss!
 
   When shrinking images, the ``--shrink`` option must be given. This informs
-  qemu-img that the user acknowledges all loss of data beyond the truncated
+  ``qemu-img`` that the user acknowledges all loss of data beyond the truncated
   image's end.
 
   After using this command to grow a disk image, you must use file system and
diff --git a/docs/tools/qemu-nbd.rst b/docs/tools/qemu-nbd.rst
index 56e54cd441..6031f96893 100644
--- a/docs/tools/qemu-nbd.rst
+++ b/docs/tools/qemu-nbd.rst
@@ -31,14 +31,14 @@ driver options if ``--image-opts`` is specified.
 
 *dev* is an NBD device.
 
-.. option:: --object type,id=ID,...props...
+.. option:: --object type,id=ID,...
 
   Define a new instance of the *type* object class identified by *ID*.
   See the :manpage:`qemu(1)` manual page for full details of the properties
   supported. The common object types that it makes sense to define are the
   ``secret`` object, which is used to supply passwords and/or encryption
   keys, and the ``tls-creds`` object, which is used to supply TLS
-  credentials for the qemu-nbd server or client.
+  credentials for the ``qemu-nbd`` server or client.
 
 .. option:: -p, --port=PORT
 
@@ -238,7 +238,7 @@ daemon:
 Expose the guest-visible contents of a qcow2 file via a block device
 /dev/nbd0 (and possibly creating /dev/nbd0p1 and friends for
 partitions found within), then disconnect the device when done.
-Access to bind qemu-nbd to an /dev/nbd device generally requires root
+Access to bind ``qemu-nbd`` to a /dev/nbd device generally requires root
 privileges, and may also require the execution of ``modprobe nbd``
 to enable the kernel NBD client module.  *CAUTION*: Do not use
 this method to mount filesystems from an untrusted guest image - a
diff --git a/docs/tools/qemu-storage-daemon.rst b/docs/tools/qemu-storage-daemon.rst
index b8ef4486f1..3e5a9dc032 100644
--- a/docs/tools/qemu-storage-daemon.rst
+++ b/docs/tools/qemu-storage-daemon.rst
@@ -10,9 +10,10 @@ Synopsis
 Description
 -----------
 
-qemu-storage-daemon provides disk image functionality from QEMU, qemu-img, and
-qemu-nbd in a long-running process controlled via QMP commands without running
-a virtual machine. It can export disk images, run block job operations, and
+``qemu-storage-daemon`` provides disk image functionality from QEMU,
+``qemu-img``, and ``qemu-nbd`` in a long-running process controlled via QMP
+commands without running a virtual machine.
+It can export disk images, run block job operations, and
 perform other disk-related operations. The daemon is controlled via a QMP
 monitor and initial configuration from the command-line.
 
diff --git a/docs/tools/virtiofsd.rst b/docs/tools/virtiofsd.rst
index cc31402830..07ac0be551 100644
--- a/docs/tools/virtiofsd.rst
+++ b/docs/tools/virtiofsd.rst
@@ -136,8 +136,8 @@ Extended attribute (xattr) mapping
 By default the name of xattr's used by the client are passed through to the server
 file system.  This can be a problem where either those xattr names are used
 by something on the server (e.g. selinux client/server confusion) or if the
-virtiofsd is running in a container with restricted privileges where it cannot
-access some attributes.
+``virtiofsd`` is running in a container with restricted privileges where it
+cannot access some attributes.
 
 Mapping syntax
 ~~~~~~~~~~~~~~