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.mayd...@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 <ebl...@redhat.com> -- Eric Blake, Principal Software Engineer Red Hat, Inc. Virtualization: qemu.org | libguestfs.org
