Re: [PATCH 2/5] docs/interop/nbd.txt: Convert to rST

[Eric Blake]

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)?

>  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