Re: [Nbd] [PATCH] doc: Wording cleanups
On 6 Apr 2016, at 16:35, Eric Blake <eblake@...696...> wrote:
> Fix several document inconsistencies (missing references,
> rewrap long lines, address typos, improve grammar) introduced
> in recent patches.
>
> Signed-off-by: Eric Blake <eblake@...696...>
Reviewed-by: Alex Bligh <alex@...872...>
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
> Nbd-general@lists.sourceforge.net
> https://lists.sourceforge.net/lists/listinfo/nbd-general
>
--
Alex Bligh
Reply to: