| Message ID | 20240801170131.3977807-3-peter.maydell@linaro.org |
|---|---|
| State | New |
| Headers | show |
| Series | docs: more conversions from txt to rst | expand |
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>
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.
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
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