Update proto.txt

[nbd.git] / doc / proto.txt

diff --git a/doc/proto.txt b/doc/proto.txt
index fe5e819..4869e02 100644 (file)
--- a/doc/proto.txt
+++ b/doc/proto.txt
@@ -26,15 +26,17 @@ server during the handshake.
 There are two message types in the data pushing phase: the request, and
 the response.
 
 There are two message types in the data pushing phase: the request, and
 the response.
 

-There are three request types in the data pushing phase: NBD_CMD_READ,
-NBD_CMD_WRITE, and NBD_CMD_DISC (disconnect).
+There are four request types in the data pushing phase: NBD_CMD_READ,
+NBD_CMD_WRITE, NBD_CMD_DISC (disconnect), and NBD_CMD_FLUSH.

 
 The request is sent by the client; the response by the server. A request
 header consists a 32 bit magic number (magic), a 32 bit field denoting
 the request type (see below; 'type'), a 64 bit handle ('handle'), a 64
 bit data offset ('from'), and a 32 bit length ('len'). In case of a
 write request, the header is immediately followed by 'len' bytes of
 
 The request is sent by the client; the response by the server. A request
 header consists a 32 bit magic number (magic), a 32 bit field denoting
 the request type (see below; 'type'), a 64 bit handle ('handle'), a 64
 bit data offset ('from'), and a 32 bit length ('len'). In case of a
 write request, the header is immediately followed by 'len' bytes of

-data.
+data. In the case of NBD_CMD_FLUSH, the offset and length should
+be zero (meaning "flush entire device"); other values are reserved
+for future use (e.g. for flushing specific areas without a write).

 
 The reply contains three fields: a 32 bit magic number ('magic'), a 32
 bit error code ('error'; 0, unless an error occurred in which case it is
 
 The reply contains three fields: a 32 bit magic number ('magic'), a 32
 bit error code ('error'; 0, unless an error occurred in which case it is

@@ -50,6 +52,16 @@ we change that to asynchronous handling, handling the disconnect request
 will probably be postponed until there are no other outstanding
 requests.
 
 will probably be postponed until there are no other outstanding
 requests.
 

+A flush request will not be sent unless NBD_FLAG_SEND_FLUSH is set,
+and indicates the backing file should be fdatasync()'d to disk.
+
+The top 16 bits of the request are flags. NBD_CMD_FLAG_FUA implies
+a force unit access, and can currently only be usefully combined
+with NBD_CMD_WRITE. This is implemented using sync_file_range
+if present, else by fdatasync() of that file (note not all files
+in a multifile environment). NBD_CMD_FLAG_FUA will not be set
+unless NBD_FLAG_SEND_FUA is set.
+

 There are two versions of the negotiation: the 'old' style (nbd <=
 2.9.16) and the 'new' style (nbd >= 2.9.17, though due to a bug it does
 not work with anything below 2.9.18). What follows is a description of
 There are two versions of the negotiation: the 'old' style (nbd <=
 2.9.16) and the 'new' style (nbd >= 2.9.17, though due to a bug it does
 not work with anything below 2.9.18). What follows is a description of

@@ -83,10 +95,13 @@ only still supported for backwards compatibility.
 'new' style handshake
 ---------------------
 
 'new' style handshake
 ---------------------
 

-A client who wants to use the new style negotiation MUST connect on the
-IANA-reserved port for NBD, 10809. The server may listen on other ports
-as well, but it will use the old style handshake on those. The server
-will refuse to allow old-style negotiations on the new-style port.
+A client who wants to use the new style negotiation should connect on
+the IANA-reserved port for NBD, 10809. The server may listen on other
+ports as well, but it will use the old style handshake on those. The
+server will refuse to allow old-style negotiations on the new-style
+port. For debugging purposes, the server may change the port on which to
+listen for new-style negotiation, but this should not happen for
+production purposes.

 
 S: "NBDMAGIC" (as in the old style handshake)
 S: 0x49484156454F5054 (note different magic number)
 
 S: "NBDMAGIC" (as in the old style handshake)
 S: 0x49484156454F5054 (note different magic number)