On 6 Apr 2016, at 16:35, Eric Blake <ebl...@redhat.com> wrote: > Fix several document inconsistencies (missing references, > rewrap long lines, address typos, improve grammar) introduced > in recent patches. > > Signed-off-by: Eric Blake <ebl...@redhat.com>
Reviewed-by: Alex Bligh <a...@alex.org.uk> 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-gene...@lists.sourceforge.net > https://lists.sourceforge.net/lists/listinfo/nbd-general > -- Alex Bligh
