Remove double "it", and redundant information about defaults

[nbd.git] / doc / proto.txt

diff --git a/doc/proto.txt b/doc/proto.txt
index aa247af..bd26657 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 implementing 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

@@ -107,14 +119,17 @@ The generic format of setting an option is as follows:
 C: 0x49484156454F5054 (note same new-style handshake's magic number)
 C: 32 bits denoting the chosen option (NBD_OPT_EXPORT_NAME is the only
    possible value currently)
 C: 0x49484156454F5054 (note same new-style handshake's magic number)
 C: 32 bits denoting the chosen option (NBD_OPT_EXPORT_NAME is the only
    possible value currently)

+C: unsigned 32 bit length of option data

 C: (any data needed for the chosen option)
 S: (any response as needed and defined by the chosen option; currently
    this does not happen).
 
 C: (any data needed for the chosen option)
 S: (any response as needed and defined by the chosen option; currently
    this does not happen).
 

+The presence of the option length in every option allows the server
+to skip any options presented by the client that it does not
+understand.
+

 The data needed for the NBD_OPT_EXPORT_NAME option is:
 
 The data needed for the NBD_OPT_EXPORT_NAME option is:
 

-C: unsigned 32 bit length (denotes the length of the name used, not
-   including any terminating NUL byte)

 C: name of the export (character string of length as specified,
    not terminated by any NUL bytes or similar)
 
 C: name of the export (character string of length as specified,
    not terminated by any NUL bytes or similar)