Convert nbd.txt to rST format.
Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
---
MAINTAINERS | 2 +-
docs/interop/index.rst | 1 +
docs/interop/nbd.rst | 89 ++++++++++++++++++++++++++++++++++++++++++
docs/interop/nbd.txt | 72 ----------------------------------
4 files changed, 91 insertions(+), 73 deletions(-)
create mode 100644 docs/interop/nbd.rst
delete mode 100644 docs/interop/nbd.txt
diff --git a/MAINTAINERS b/MAINTAINERS
index 2a183fe960b..dd159053dbd 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -3869,7 +3869,7 @@ F: nbd/
F: include/block/nbd*
F: qemu-nbd.*
F: blockdev-nbd.c
-F: docs/interop/nbd.txt
+F: docs/interop/nbd.rst
F: docs/tools/qemu-nbd.rst
F: tests/qemu-iotests/tests/*nbd*
T: git https://repo.or.cz/qemu/ericb.git nbd
diff --git a/docs/interop/index.rst b/docs/interop/index.rst
index ed65395bfb2..b9ceaabc648 100644
--- a/docs/interop/index.rst
+++ b/docs/interop/index.rst
@@ -14,6 +14,7 @@ are useful for making QEMU interoperate with other software.
dbus-vmstate
dbus-display
live-block-operations
+ nbd
pr-helper
qmp-spec
qemu-ga
diff --git a/docs/interop/nbd.rst b/docs/interop/nbd.rst
new file mode 100644
index 00000000000..de079d31fd8
--- /dev/null
+++ b/docs/interop/nbd.rst
@@ -0,0 +1,89 @@
+QEMU NBD protocol support
+=========================
+
+QEMU supports the NBD protocol, and has an internal NBD client (see
+``block/nbd.c``), an internal NBD server (see ``blockdev-nbd.c``), and an
+external NBD server tool (see ``qemu-nbd.c``). The common code is placed
+in ``nbd/*``.
+
+The NBD protocol is specified here:
+https://github.com/NetworkBlockDevice/nbd/blob/master/doc/proto.md
+
+The following paragraphs describe some specific properties of NBD
+protocol realization in QEMU.
+
+Metadata namespaces
+-------------------
+
+QEMU supports the ``base:allocation`` metadata context as defined in the
+NBD protocol specification, and also defines an additional metadata
+namespace ``qemu``.
+
+``qemu`` namespace
+------------------
+
+The ``qemu`` namespace currently contains two available metadata context
+types. The first is related to exposing the contents of a dirty
+bitmap alongside the associated disk contents. That metadata context
+is named with the following form::
+
+ qemu:dirty-bitmap:<dirty-bitmap-export-name>
+
+Each dirty-bitmap metadata context defines only one flag for extents
+in reply for ``NBD_CMD_BLOCK_STATUS``:
+
+bit 0:
+ ``NBD_STATE_DIRTY``, set when the extent is "dirty"
+
+The second is related to exposing the source of various extents within
+the image, with a single metadata context named::
+
+ qemu:allocation-depth
+
+In the allocation depth context, the entire 32-bit value represents a
+depth of which layer in a thin-provisioned backing chain provided the
+data (0 for unallocated, 1 for the active layer, 2 for the first
+backing layer, and so forth).
+
+For ``NBD_OPT_LIST_META_CONTEXT`` the following queries are supported
+in addition to the specific ``qemu:allocation-depth`` and
+``qemu:dirty-bitmap:<dirty-bitmap-export-name>``:
+
+``qemu:``
+ returns list of all available metadata contexts in the namespace
+``qemu:dirty-bitmap:``
+ returns list of all available dirty-bitmap metadata contexts
+
+Features by version
+-------------------
+
+The following list documents which qemu version first implemented
+various features (both as a server exposing the feature, and as a
+client taking advantage of the feature when present), to make it
+easier to plan for cross-version interoperability. Note that in
+several cases, the initial release containing a feature may require
+additional patches from the corresponding stable branch to fix bugs in
+the operation of that feature.
+
+2.6
+ ``NBD_OPT_STARTTLS`` with TLS X.509 Certificates
+2.8
+ ``NBD_CMD_WRITE_ZEROES``
+2.10
+ ``NBD_OPT_GO``, ``NBD_INFO_BLOCK``
+2.11
+ ``NBD_OPT_STRUCTURED_REPLY``
+2.12
+ ``NBD_CMD_BLOCK_STATUS`` for ``base:allocation``
+3.0
+ ``NBD_OPT_STARTTLS`` with TLS Pre-Shared Keys (PSK),
+ ``NBD_CMD_BLOCK_STATUS`` for ``qemu:dirty-bitmap:``, ``NBD_CMD_CACHE``
+4.2
+ ``NBD_FLAG_CAN_MULTI_CONN`` for shareable read-only exports,
+ ``NBD_CMD_FLAG_FAST_ZERO``
+5.2
+ ``NBD_CMD_BLOCK_STATUS`` for ``qemu:allocation-depth``
+7.1
+ ``NBD_FLAG_CAN_MULTI_CONN`` for shareable writable exports
+8.2
+ ``NBD_OPT_EXTENDED_HEADERS``, ``NBD_FLAG_BLOCK_STATUS_PAYLOAD``
diff --git a/docs/interop/nbd.txt b/docs/interop/nbd.txt
deleted file mode 100644
index 18efb251de9..00000000000
--- a/docs/interop/nbd.txt
+++ /dev/null
@@ -1,72 +0,0 @@
-QEMU supports the NBD protocol, and has an internal NBD client (see
-block/nbd.c), an internal NBD server (see blockdev-nbd.c), and an
-external NBD server tool (see qemu-nbd.c). The common code is placed
-in nbd/*.
-
-The NBD protocol is specified here:
-https://github.com/NetworkBlockDevice/nbd/blob/master/doc/proto.md
-
-The following paragraphs describe some specific properties of NBD
-protocol realization in QEMU.
-
-= Metadata namespaces =
-
-QEMU supports the "base:allocation" metadata context as defined in the
-NBD protocol specification, and also defines an additional metadata
-namespace "qemu".
-
-== "qemu" namespace ==
-
-The "qemu" namespace currently contains two available metadata context
-types. The first is related to exposing the contents of a dirty
-bitmap alongside the associated disk contents. That metadata context
-is named with the following form:
-
- qemu:dirty-bitmap:<dirty-bitmap-export-name>
-
-Each dirty-bitmap metadata context defines only one flag for extents
-in reply for NBD_CMD_BLOCK_STATUS:
-
- bit 0: NBD_STATE_DIRTY, set when the extent is "dirty"
-
-The second is related to exposing the source of various extents within
-the image, with a single metadata context named:
-
- qemu:allocation-depth
-
-In the allocation depth context, the entire 32-bit value represents a
-depth of which layer in a thin-provisioned backing chain provided the
-data (0 for unallocated, 1 for the active layer, 2 for the first
-backing layer, and so forth).
-
-For NBD_OPT_LIST_META_CONTEXT the following queries are supported
-in addition to the specific "qemu:allocation-depth" and
-"qemu:dirty-bitmap:<dirty-bitmap-export-name>":
-
-* "qemu:" - returns list of all available metadata contexts in the
- namespace.
-* "qemu:dirty-bitmap:" - returns list of all available dirty-bitmap
- metadata contexts.
-
-= Features by version =
-
-The following list documents which qemu version first implemented
-various features (both as a server exposing the feature, and as a
-client taking advantage of the feature when present), to make it
-easier to plan for cross-version interoperability. Note that in
-several cases, the initial release containing a feature may require
-additional patches from the corresponding stable branch to fix bugs in
-the operation of that feature.
-
-* 2.6: NBD_OPT_STARTTLS with TLS X.509 Certificates
-* 2.8: NBD_CMD_WRITE_ZEROES
-* 2.10: NBD_OPT_GO, NBD_INFO_BLOCK
-* 2.11: NBD_OPT_STRUCTURED_REPLY
-* 2.12: NBD_CMD_BLOCK_STATUS for "base:allocation"
-* 3.0: NBD_OPT_STARTTLS with TLS Pre-Shared Keys (PSK),
-NBD_CMD_BLOCK_STATUS for "qemu:dirty-bitmap:", NBD_CMD_CACHE
-* 4.2: NBD_FLAG_CAN_MULTI_CONN for shareable read-only exports,
-NBD_CMD_FLAG_FAST_ZERO
-* 5.2: NBD_CMD_BLOCK_STATUS for "qemu:allocation-depth"
-* 7.1: NBD_FLAG_CAN_MULTI_CONN for shareable writable exports
-* 8.2: NBD_OPT_EXTENDED_HEADERS, NBD_FLAG_BLOCK_STATUS_PAYLOAD
--
2.34.1On Thu, Aug 01, 2024 at 06:01:28PM GMT, Peter Maydell wrote: > Convert nbd.txt to rST format. > > Signed-off-by: Peter Maydell <peter.maydell@linaro.org> > --- > MAINTAINERS | 2 +- > docs/interop/index.rst | 1 + > docs/interop/nbd.rst | 89 ++++++++++++++++++++++++++++++++++++++++++ > docs/interop/nbd.txt | 72 ---------------------------------- > 4 files changed, 91 insertions(+), 73 deletions(-) > create mode 100644 docs/interop/nbd.rst > delete mode 100644 docs/interop/nbd.txt > > diff --git a/MAINTAINERS b/MAINTAINERS > index 2a183fe960b..dd159053dbd 100644 > --- a/MAINTAINERS > +++ b/MAINTAINERS > @@ -3869,7 +3869,7 @@ F: nbd/ > F: include/block/nbd* > F: qemu-nbd.* > F: blockdev-nbd.c > -F: docs/interop/nbd.txt > +F: docs/interop/nbd.rst Upstream NBD has a link to the nbd.txt page; I'll have to update that link to the new name. Is it worth creating a git symlink so the old name remains a stable point to link to (even though it is no longer purely text)? > F: docs/tools/qemu-nbd.rst > F: tests/qemu-iotests/tests/*nbd* > T: git https://repo.or.cz/qemu/ericb.git nbd > diff --git a/docs/interop/index.rst b/docs/interop/index.rst > index ed65395bfb2..b9ceaabc648 100644 > --- a/docs/interop/index.rst > +++ b/docs/interop/index.rst > @@ -14,6 +14,7 @@ are useful for making QEMU interoperate with other software. > dbus-vmstate > dbus-display > live-block-operations > + nbd > pr-helper > qmp-spec > qemu-ga > diff --git a/docs/interop/nbd.rst b/docs/interop/nbd.rst > new file mode 100644 > index 00000000000..de079d31fd8 > --- /dev/null > +++ b/docs/interop/nbd.rst > @@ -0,0 +1,89 @@ > +QEMU NBD protocol support > +========================= > + > +QEMU supports the NBD protocol, and has an internal NBD client (see > +``block/nbd.c``), an internal NBD server (see ``blockdev-nbd.c``), and an > +external NBD server tool (see ``qemu-nbd.c``). The common code is placed > +in ``nbd/*``. Accurate translation, and accurate information although incomplete - maybe I should do a followup patch to mention that qemu-storage-daemon can also expose an NBD server? Doesn't affect review of this patch. > + > +The NBD protocol is specified here: > +https://github.com/NetworkBlockDevice/nbd/blob/master/doc/proto.md > + > +The following paragraphs describe some specific properties of NBD > +protocol realization in QEMU. > + > +Metadata namespaces > +------------------- > + > +QEMU supports the ``base:allocation`` metadata context as defined in the > +NBD protocol specification, and also defines an additional metadata > +namespace ``qemu``. > + > +``qemu`` namespace > +------------------ > + > +The ``qemu`` namespace currently contains two available metadata context > +types. The first is related to exposing the contents of a dirty > +bitmap alongside the associated disk contents. That metadata context > +is named with the following form:: > + > + qemu:dirty-bitmap:<dirty-bitmap-export-name> > + > +Each dirty-bitmap metadata context defines only one flag for extents > +in reply for ``NBD_CMD_BLOCK_STATUS``: > + > +bit 0: > + ``NBD_STATE_DIRTY``, set when the extent is "dirty" > + > +The second is related to exposing the source of various extents within > +the image, with a single metadata context named:: I'm not an rst expert, so I'm assuming the difference between ending a line in : vs :: is intentional and affects the rendering; but as far as I can tell, the rendered result worked, so I don't see any problems with the patch. Reviewed-by: Eric Blake <eblake@redhat.com> -- Eric Blake, Principal Software Engineer Red Hat, Inc. Virtualization: qemu.org | libguestfs.org
On Thu, 1 Aug 2024 at 19:39, Eric Blake <eblake@redhat.com> wrote: > > On Thu, Aug 01, 2024 at 06:01:28PM GMT, Peter Maydell wrote: > > Convert nbd.txt to rST format. > > > > Signed-off-by: Peter Maydell <peter.maydell@linaro.org> > > --- > > MAINTAINERS | 2 +- > > docs/interop/index.rst | 1 + > > docs/interop/nbd.rst | 89 ++++++++++++++++++++++++++++++++++++++++++ > > docs/interop/nbd.txt | 72 ---------------------------------- > > 4 files changed, 91 insertions(+), 73 deletions(-) > > create mode 100644 docs/interop/nbd.rst > > delete mode 100644 docs/interop/nbd.txt > > > > diff --git a/MAINTAINERS b/MAINTAINERS > > index 2a183fe960b..dd159053dbd 100644 > > --- a/MAINTAINERS > > +++ b/MAINTAINERS > > @@ -3869,7 +3869,7 @@ F: nbd/ > > F: include/block/nbd* > > F: qemu-nbd.* > > F: blockdev-nbd.c > > -F: docs/interop/nbd.txt > > +F: docs/interop/nbd.rst > > Upstream NBD has a link to the nbd.txt page; I'll have to update that > link to the new name. Is it worth creating a git symlink so the old > name remains a stable point to link to (even though it is no longer > purely text)? I'm not super enthusiastic about doing that -- we haven't created symlinks for any of the other document conversions we've done. > > +The second is related to exposing the source of various extents within > > +the image, with a single metadata context named:: > > I'm not an rst expert, so I'm assuming the difference between ending a > line in : vs :: is intentional and affects the rendering; but as far > as I can tell, the rendered result worked, so I don't see any problems > with the patch. Ending with double-colon is a shorthand for "display a single colon, and then the following text is a literal block". It has the same effect as if you used a single colon and then the normal double-colon-on-its-own-line to mark the literal block. Some sentence ending in a colon: :: This is a literal block, so it's monospaced -- PMM
On Fri, Aug 02, 2024 at 09:39:41AM GMT, Peter Maydell wrote: > On Thu, 1 Aug 2024 at 19:39, Eric Blake <eblake@redhat.com> wrote: > > > > On Thu, Aug 01, 2024 at 06:01:28PM GMT, Peter Maydell wrote: > > > Convert nbd.txt to rST format. > > > > > > -F: docs/interop/nbd.txt > > > +F: docs/interop/nbd.rst > > > > Upstream NBD has a link to the nbd.txt page; I'll have to update that > > link to the new name. Is it worth creating a git symlink so the old > > name remains a stable point to link to (even though it is no longer > > purely text)? > > I'm not super enthusiastic about doing that -- we haven't created > symlinks for any of the other document conversions we've done. Okay, a stability symlink is not necessary. Currently, the NBD spec points to the raw qemu.txt because nothing is rendered into our online pages; but I plan to instead point it into the rendered version reachable from https://www.qemu.org/docs/master/interop/index.html once your patch lands. I also found a typo in that page (right next to where nbd will appear), so I'm submitting that patch as a followup to this thread, if that's okay. -- Eric Blake, Principal Software Engineer Red Hat, Inc. Virtualization: qemu.org | libguestfs.org
© 2016 - 2024 Red Hat, Inc.