Re: [Qemu-block] [PATCH v2 02/22] nbd: Document timeline of various features

[Vladimir Sementsov-Ogievskiy]

15.12.2018 16:53, Eric Blake wrote:
> 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 <address@hidden>
> Signed-off-by: Eric Blake <address@hidden>
> 
> ---
> v2: new patch
> ---
>   docs/interop/nbd.txt | 19 ++++++++++++++++++-
>   1 file changed, 18 insertions(+), 1 deletion(-)
> 
> diff --git a/docs/interop/nbd.txt b/docs/interop/nbd.txt
> index 77b5f459111..2b25f871e7c 100644
> --- a/docs/interop/nbd.txt
> +++ b/docs/interop/nbd.txt
> @@ -15,7 +15,6 @@ 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,
> @@ -36,3 +35,21 @@ in addition to 
> "qemu:dirty-bitmap:<dirty-bitmap-export-name>":
>               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_READ

NBD_OPT_STRUCTURED_REPLY you mean

> +* 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
> 

Hm, trying to check by:

   features=$(echo NBD_OPT_{STARTTLS,GO,STRUCTURED_REPLY} 
NBD_CMD_{WRITE_ZEROES,BLOCK_STATUS,CACHE} NBD_INFO_BLOCK PSK)
   versions=$(echo v2.{5..12}.0 v3.0.0)
   for f in $features; do echo -------------; echo $f; for v in $versions; do 
echo $v:; git grep $f $v; done; done | less

looks correct.

Checked base:allocation/qemu:dirty-bitmap appearance.

Don't want to dig in TLS version checking which is I'm not familiar with, so, 
I'm OK and with s/READ/REPLY:

Reviewed-by: Vladimir Sementsov-Ogievskiy <address@hidden>


-- 
Best regards,
Vladimir