mirror of https://github.com/xemu-project/xemu.git
docs/interop/nbd.txt: Convert to rST
Convert nbd.txt to rST format. Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Reviewed-by: Richard Henderson <richard.henderson@linaro.org> Reviewed-by: Eric Blake <eblake@redhat.com> Message-id: 20240801170131.3977807-3-peter.maydell@linaro.org
This commit is contained in:
Peter Maydell
parent
9ca6876dc0
commit
8dac93a8ee
|
|
@ -3871,7 +3871,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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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``
|
||||
|
|
@ -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
|
||||
Loading…
Reference in New Issue