mirrors/qemu
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
bf8e925eb5
qemu/docs/interop/nbd.txt

58 lines
2.2 KiB
Plaintext
Raw Normal View History

docs/interop: add nbd.txt Describe new metadata namespace: "qemu". Signed-off-by: Vladimir Sementsov-Ogievskiy <vsementsov@virtuozzo.com> Message-Id: <20180609151758.17343-7-vsementsov@virtuozzo.com> Reviewed-by: Eric Blake <eblake@redhat.com> [eblake: grammar tweaks] Signed-off-by: Eric Blake <eblake@redhat.com>
2018-06-09 18:17:58 +03:00
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 only one type of context,
related to exposing the contents of a dirty bitmap alongside the
associated disk contents. That context has 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, means that the extent is "dirty"
For NBD_OPT_LIST_META_CONTEXT the following queries are supported
in addition to "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.
nbd: Document timeline of various features It can be useful to figure out which NBD protocol features are exposed by a server, as well as what features a client will take advantage of if available, for a given qemu release. It's not always precise to base features on version numbers (thanks to downstream backports), but any documentation is better than making users search through git logs themselves. This patch originally stemmed from a request to document that pristine 3.0 has a known bug where NBD_OPT_LIST_META_CONTEXT with 0 queries forgot to advertise an available "qemu:dirty-bitmap" context, but documenting bugs like this (or the fact that 3.0 also botched NBD_CMD_CACHE) gets to be too much details, especially since buggy releases will be less likely connection targets over time. Instead, I chose to just remind users to check stable release branches. Suggested-by: Vladimir Sementsov-Ogievskiy <vsementsov@virtuozzo.com> Signed-off-by: Eric Blake <eblake@redhat.com> Message-Id: <20181215135324.152629-3-eblake@redhat.com> Reviewed-by: Richard W.M. Jones <rjones@redhat.com> Reviewed-by: Vladimir Sementsov-Ogievskiy <vsementsov@virtuozzo.com>
2018-12-15 16:53:04 +03:00
= 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
nbd: Prepare for NBD_CMD_FLAG_FAST_ZERO Commit fe0480d6 and friends added BDRV_REQ_NO_FALLBACK as a way to avoid wasting time on a preliminary write-zero request that will later be rewritten by actual data, if it is known that the write-zero request will use a slow fallback; but in doing so, could not optimize for NBD. The NBD specification is now considering an extension that will allow passing on those semantics; this patch updates the new protocol bits and 'qemu-nbd --list' output to recognize the bit, as well as the new errno value possible when using the new flag; while upcoming patches will improve the client to use the feature when present, and the server to advertise support for it. The NBD spec recommends (but not requires) that ENOTSUP be avoided for all but failures of a fast zero (the only time it is mandatory to avoid an ENOTSUP failure is when fast zero is supported but not requested during write zeroes; the questionable use is for ENOTSUP to other actions like a normal write request). However, clients that get an unexpected ENOTSUP will either already be treating it the same as EINVAL, or may appreciate the extra bit of information. We were equally loose for returning EOVERFLOW in more situations than recommended by the spec, so if it turns out to be a problem in practice, a later patch can tighten handling for both error codes. Signed-off-by: Eric Blake <eblake@redhat.com> Message-Id: <20190823143726.27062-3-eblake@redhat.com> Reviewed-by: Vladimir Sementsov-Ogievskiy <vsementsov@virtuozzo.com> [eblake: tweak commit message, also handle EOPNOTSUPP]
2019-08-23 17:37:23 +03:00
* 4.2: NBD_FLAG_CAN_MULTI_CONN for sharable read-only exports,
NBD_CMD_FLAG_FAST_ZERO
Reference in New Issue Copy Permalink