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 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
-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
@@ -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.
 
+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
@@ -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: 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).
 
+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:
 
-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)