[Qemu-devel] [PATCH 2/1] doc: More details on flag negotiation

[Eric Blake]

Add documentation that makes it clear that the server may add
flags that the client does not recognize, but that the client
may ignore those flags because the server will not change
behavior without agreement; meanwhile, the client must not set
flags the server does not recognize (since there is no second
round of server reply, the only sane course of action is for
the server to disconnect).

Also, give a forward reference to the effect of negotiating
NO_ZEROES on the server's reply to NBD_OPT_EXPORT_NAME, and
call out the fact that none of the server's global flags should
be used during oldstyle negotiation since a client has no chance
to respond with the corresponding client flag.

Signed-off-by: Eric Blake <address@hidden>
---
 doc/proto.md | 17 ++++++++++++++---
 1 file changed, 14 insertions(+), 3 deletions(-)

diff --git a/doc/proto.md b/doc/proto.md
index d0102e0..44579fc 100644
--- a/doc/proto.md
+++ b/doc/proto.md
@@ -103,8 +103,10 @@ C: 32 bits, flags

 This completes the initial phase of negotiation; the client and server
 now both know they understand the first version of the newstyle
-handshake, with no options. What follows is a repeating group of
-options. In non-fixed newstyle only one option can be set
+handshake, with no options. The client SHOULD ignore any global flags
+it does not recognize, while the server MUST close the connection if
+it does not recognize the client's flags.  What follows is a repeating
+group of options. In non-fixed newstyle only one option can be set
 (`NBD_OPT_EXPORT_NAME`), and it is not optional.

 At this point, we move on to option haggling, during which point the
@@ -126,7 +128,8 @@ about the used export:

 S: 64 bits, size of the export in bytes (unsigned)  
 S: 16 bits, export flags  
-S: 124 bytes, zeroes (reserved)
+S: 124 bytes, zeroes (reserved) (unless `NBD_FLAG_C_NO_ZEROES` was
+   negotiated by the client)

 If the server is unwilling to allow the export, it should close the
 connection.
@@ -229,6 +232,10 @@ the first magic number.
   `NBD_FLAG_C_NO_ZEROES` in the client flags field, the server MUST NOT
   send the 124 bytes of zero at the end of the negotiation.

+The server MUST NOT set any other flags, and SHOULD NOT change behaviour
+unless the client responds with a corresponding flag.  The server MUST
+NOT set any of these flags during oldstyle negotiation.
+
 ##### Export flags

 This field of 16 bits is sent by the server after option haggling, or
@@ -259,6 +266,10 @@ receiving the global flags from the server.
   set `NBD_FLAG_NO_ZEROES`. If set, the server MUST NOT send the 124
   bytes of zeroes at the end of the negotiation.

+Clients SHOULD NOT set any other flags; the server MUST drop the
+connection if the client sets an unknown flag, or a flag that does
+not match something advertised by the server.
+
 #### Option types

 These values are used in the "option" field during the option haggling
-- 
2.5.5