On 04/06/2016 01:46 PM, Alex Bligh wrote: > These are changes which possibly have semantic effect > > * Clarify that SHOULD / MUST / MAY etc. when in capitals have an > RFC 2119 meaning using the wording within that RFC. > > * Fix some lowercase use of these words which actually were > meant to be uppercase. > > * Fix some lowercase 'should' which clearly meant 'MUST'; where > it's not obvious, I've made them 'SHOULD' or left them as is. > > Signed-off-by: Alex Bligh <alex@...872...> > --- > doc/proto.md | 64 +++++++++++++++++++++++++++++++++--------------------------- > > @@ -309,16 +315,16 @@ NOT set any of these flags during oldstyle negotiation. > This field of 16 bits is sent by the server after option haggling, or > immediately after the handshake flags field in oldstyle negotiation: > > -- bit 0, `NBD_FLAG_HAS_FLAGS`; should always be 1 > -- bit 1, `NBD_FLAG_READ_ONLY`; should be set to 1 if the export is > +- bit 0, `NBD_FLAG_HAS_FLAGS`; MUST always be 1 > +- bit 1, `NBD_FLAG_READ_ONLY`; MUST be set to 1 if the export is > read-only > -- bit 2, `NBD_FLAG_SEND_FLUSH`; should be set to 1 if the server > +- bit 2, `NBD_FLAG_SEND_FLUSH`; MUST be set to 1 if the server > supports `NBD_CMD_FLUSH` commands A server may be capable of parsing NBD_CMD_FLUSH, but have a per-export policy on whether flushes are acceptable. In fact, it may be entirely reasonable for a server that sets NBD_FLAG_READ_ONLY to intentionally leave NBD_FLAG_SEND_FLUSH clear, even though the same server accepts flush on normal connections. I think this one should stay at SHOULD. > -- bit 3, `NBD_FLAG_SEND_FUA`; should be set to 1 if the server supports > +- bit 3, `NBD_FLAG_SEND_FUA`; MUST be set to 1 if the server supports > the `NBD_CMD_FLAG_FUA` flag Again, FUA is (currently) documented to only have an impact on reads, so I argue that SHOULD allows a server that intentionally clears this bit when NBD_FLAG_READ_ONLY is set. > -- bit 4, `NBD_FLAG_ROTATIONAL`; should be set to 1 to let the client > +- bit 4, `NBD_FLAG_ROTATIONAL`; MUST be set to 1 to let the client > schedule I/O accesses as for a rotational medium The wording sounds like the server always has to set this. Maybe: MUST be set to 1 if the server wants to inform the client to schedule I/O accesses as for a rotational medium. > -- bit 5, `NBD_FLAG_SEND_TRIM`; should be set to 1 if the server supports > +- bit 5, `NBD_FLAG_SEND_TRIM`; MUST be set to 1 if the server supports > `NBD_CMD_TRIM` commands Again, SHOULD may be better since a read-only export can't trim. > + the server is unwilling to perform TLS, it SHOULD reply with > + `NBD_REP_ERR_POLICY`. For backwards compatibility, a client SHOULD > also be prepared to handle `NBD_REP_ERR_UNSUP`. If the client sent see below at [1] > @@ -670,7 +676,7 @@ documented as applicable to the given request. > Which error to return in any other case is not specified by the NBD > protocol. > > -The server SHOULD AVOID returning ENOMEM if at all possible. > +The server SHOULD avoid returning `ENOMEM` if at all possible. The server SHOULD NOT return `ENOMEM` if at all possible. > - For backwards compatibility, clients should be prepared to also > - handle `NBD_REP_ERR_UNSUP`. In this case, they should fall back to > + For backwards compatibility, clients MUST be prepared to also > + handle `NBD_REP_ERR_UNSUP`. In this case, they MUST fall back to > using `NBD_OPT_EXPORT_NAME`. [1] - why is this MUST, when the NBD_OPT_STARTTLS uses SHOULD? Arguably, a client that gets NBD_REP_ERR_UNSUP on NBD_OPT_GO can disconnect rather than falling back to NBD_OPT_EXPORT_NAME, if it refuses to talk to old servers for whatever reason. > > @@ -1008,7 +1014,7 @@ error, and alters the reply to the `NBD_CMD_READ` request. > server MUST use structured replies to the `NBD_CMD_READ` > transmission request. Other extensions that require structured > replies may now be negotiated. > - - For backwards compatibility, clients should be prepared to also > + - For backwards compatibility, clients MUST be prepared to also > handle `NBD_REP_ERR_UNSUP`; in this case, no structured replies > will be sent. Again, is SHOULD better than MUST here? -- Eric Blake eblake redhat com +1-919-301-3266 Libvirt virtualization library http://libvirt.org
Attachment:
signature.asc
Description: OpenPGP digital signature