Re: [Qemu-devel] [Nbd] [PATCH] doc: Wording cleanups

[Alex Bligh]

On 6 Apr 2016, at 16:35, Eric Blake <address@hidden> wrote:

> Fix several document inconsistencies (missing references,
> rewrap long lines, address typos, improve grammar) introduced
> in recent patches.
> 
> Signed-off-by: Eric Blake <address@hidden>

Reviewed-by: Alex Bligh <address@hidden>

Most of that mess was mine - thanks for clearing it up.

Alex


> 
> ---
> Note that there is still ongoing discussion about the correct
> layout to use for NBD_REP_SERVER in response to NBD_OPT_INFO
> (and whether the layout should be a superset of the
> NBD_OPT_EXPORT_NAME reply) - cleaning that up will be a
> separate patch, once consensus is reached on the best layout.
> ---
> doc/proto.md | 51 +++++++++++++++++++++++++++++++--------------------
> 1 file changed, 31 insertions(+), 20 deletions(-)
> 
> diff --git a/doc/proto.md b/doc/proto.md
> index 4d63b23..3a70209 100644
> --- a/doc/proto.md
> +++ b/doc/proto.md
> @@ -445,8 +445,8 @@ during option haggling in the fixed newstyle negotiation.
>       encoded data suitable for direct display to a human being; with
>       no embedded or terminating NUL characters.
> 
> -    The experimental `INFO` extension (see below) is a client
> -    request where the extra data has a definition other than a
> +    The experimental `INFO` extension (see below) adds two client
> +    option requests where the extra data has a definition other than a
>     UTF-8 message.
> 
> There are a number of error reply types, all of which are denoted by
> @@ -527,7 +527,7 @@ valid may depend on negotiation during the handshake 
> phase.
>   not in fact write data (for instance on an `NBD_CMD_TRIM` in a situation
>   where the command as a whole is ignored), the server MAY ignore this bit
>   being set on such a command.
> -- bit 1, `NBD_CMD_NO_HOLE`; defined by the experimental `WRITE_ZEROES`
> +- bit 1, `NBD_CMD_FLAG_NO_HOLE`; defined by the experimental `WRITE_ZEROES`
>   extension; see below.
> - bit 2, `NBD_CMD_FLAG_DF`; defined by the experimental `STRUCTURED_REPLY`
>   extension; see below
> @@ -608,7 +608,7 @@ The following request types exist:
> 
>     After issuing this command, a client MUST NOT make any assumptions
>     about the contents of the export affected by this command, until
> -    overwriting it again with `NBD_CMD_WRITE`.
> +    overwriting it again with `NBD_CMD_WRITE` or `NBD_CMD_WRITE_ZEROES`.
> 
>     A client MUST NOT send a trim request unless `NBD_FLAG_SEND_TRIM`
>     was set in the transmission flags field.
> @@ -700,15 +700,18 @@ Therefore these commands share common documentation.
> 
> * `NBD_OPT_INFO` and `NBD_OPT_GO`
> 
> -    `NBD_OPT_INFO`: The client wishes to get details about export with the
> -    given name for use in the transmission phase, but does not yet want
> -    to move to the transmission phase.
> +    `NBD_OPT_INFO`: The client wishes to get details about an export
> +    with the given name for use in the transmission phase, but does
> +    not yet want to move to the transmission phase.  When successful,
> +    this option provides more details than `NBD_OPT_LIST`, but only
> +    for a single export name.
> 
> -    `NBD_OPT_GO`: The client wishes to terminate the negotiation phase and
> -    progress to the transmission phase. This client MAY issue this command 
> after
> -    an `NBD_OPT_INFO`, or MAY issue it without a previous `NBD_OPT_INFO`.
> -    `NBD_OPT_GO` can thus be used as a substitute for `NBD_OPT_EXPORT_NAME`
> -    that returns errors.
> +    `NBD_OPT_GO`: The client wishes to terminate the handshake phase
> +    and progress to the transmission phase. This client MAY issue this
> +    command after an `NBD_OPT_INFO`, or MAY issue it without a
> +    previous `NBD_OPT_INFO`.  `NBD_OPT_GO` can thus be used as an
> +    improved version of `NBD_OPT_EXPORT_NAME` that is capable of
> +    returning errors.
> 
>     Data (both commands):
> 
> @@ -742,9 +745,9 @@ Therefore these commands share common documentation.
>     - 16 bits, transmission flags.
>     - 32 bits, length of name (unsigned)
>     - Name of the export. This name MAY be different from the one
> -      given in the `NBD_OPT_INFO` or `NBD_OPT_GO` option in case the server 
> has
> -      multiple alternate names for a single export, or a default
> -      export was specified.
> +      given in the `NBD_OPT_INFO` or `NBD_OPT_GO` option in case the
> +      server has multiple alternate names for a single export, or a
> +      default export was specified.
> 
>     The server MUST NOT fail an NDB_OPT_GO sent with the same parameters
>     as a previous NBD_OPT_INFO which returned successfully (i.e. with
> @@ -754,7 +757,7 @@ Therefore these commands share common documentation.
>     intervening time the client has negotiated other options.
>     The values of the transmission flags MAY differ from what was sent
>     earlier in response to an earlier `NBD_OPT_INFO` (if any), and/or
> -    the server may fail the request, based on other options that were
> +    the server MAY fail the request, based on other options that were
>     negotiated in the meantime.
> 
>     For backwards compatibility, clients should be prepared to also
> @@ -763,14 +766,14 @@ Therefore these commands share common documentation.
> 
>     The reply to an `NBD_OPT_GO` is identical to the reply to `NBD_OPT_INFO`
>     save that if the reply indicates success (i.e. is `NBD_REP_SERVER`),
> -    the client and the server both immediatedly enter the transmission
> +    the client and the server both immediately enter the transmission
>     phase. The server MUST NOT send any zero padding bytes after the
>     `NBD_REP_SERVER` data, whether or not the client negotiated the
>     `NBD_FLAG_C_NO_ZEROES` flag. After sending this reply the server MUST
>     immediately move to the transmission phase, and after receiving this
>     reply, the client MUST immediately move to the transmission phase;
>     therefore, the server MUST NOT send this particular reply until all
> -    other pending option requests have been sent by the server.
> +    other pending option replies have been sent by the server.
> 
> ### `WRITE_ZEROES` extension
> 
> @@ -781,8 +784,14 @@ by a sparse file. With current NBD command set, the 
> client has to issue
> through the wire. The server has to write the data onto disk, effectively
> losing the sparseness.
> 
> -To remedy this, a `WRITE_ZEROES` extension is envisioned. This extension adds
> -one new command and one new command flag.
> +To remedy this, a `WRITE_ZEROES` extension is envisioned. This
> +extension adds one new transmission flag, one new command, and one new
> +command flag.
> +
> +* `NBD_FLAG_SEND_WRITE_ZEROES`
> +
> +    The server SHOULD set this transmission flag to 1 if the
> +    `NBD_CMD_WRITE_ZEROES` request is supported.
> 
> * `NBD_CMD_WRITE_ZEROES`
> 
> @@ -817,6 +826,8 @@ The extension adds the following new command flag:
>   SHOULD be set to 1 if the client wants to ensure that the server does
>   not create a hole. The client MAY send `NBD_CMD_FLAG_NO_HOLE` even
>   if `NBD_FLAG_SEND_TRIM` was not set in the transmission flags field.
> +  The server MUST support the use of this flag if it advertises
> +  `NBD_FLAG_SEND_WRITE_ZEROES`.
> 
> ### `STRUCTURED_REPLY` extension
> 
> -- 
> 2.5.5
> 
> 
> ------------------------------------------------------------------------------
> _______________________________________________
> Nbd-general mailing list
> address@hidden
> https://lists.sourceforge.net/lists/listinfo/nbd-general
> 

-- 
Alex Bligh