mirror of
https://github.com/Motorhead1991/qemu.git
synced 2025-08-21 00:53:27 -06:00
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
4 changed files with 91 additions and 73 deletions
|
|
@ -3871,7 +3871,7 @@ F: nbd/
|
||||||
F: include/block/nbd*
|
F: include/block/nbd*
|
||||||
F: qemu-nbd.*
|
F: qemu-nbd.*
|
||||||
F: blockdev-nbd.c
|
F: blockdev-nbd.c
|
||||||
F: docs/interop/nbd.txt
|
F: docs/interop/nbd.rst
|
||||||
F: docs/tools/qemu-nbd.rst
|
F: docs/tools/qemu-nbd.rst
|
||||||
F: tests/qemu-iotests/tests/*nbd*
|
F: tests/qemu-iotests/tests/*nbd*
|
||||||
T: git https://repo.or.cz/qemu/ericb.git 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-vmstate
|
||||||
dbus-display
|
dbus-display
|
||||||
live-block-operations
|
live-block-operations
|
||||||
|
nbd
|
||||||
pr-helper
|
pr-helper
|
||||||
qmp-spec
|
qmp-spec
|
||||||
qemu-ga
|
qemu-ga
|
||||||
|
|
|
||||||
89
docs/interop/nbd.rst
Normal file
89
docs/interop/nbd.rst
Normal file
|
|
@ -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…
Add table
Add a link
Reference in a new issue