[nbd PATCH 1/1] docs: Add NBD_INFO_INIT_STATE protocol extension

[Eric Blake <eblake@redhat.com>]

Various algorithms dealing with image files can optimize their
performance if they know that the destination begins life with all
zero content.  While NBD_CMD_BLOCK_STATUS could query this, it can
currently do so only 4G at a time, and only if the block status
"base:allocation" extension is present. Adding a new extension may be
easier for some servers to implement (the query only has to be
accurate at the time the client first connects, rather than something
that tracks the state of the export over time), and clients can use
their optimizations with much less traffic.

Signed-off-by: Eric Blake <eblake@redhat.com>
---
 doc/proto.md | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)

diff --git a/doc/proto.md b/doc/proto.md
index 61d57b5..e053b17 100644
--- a/doc/proto.md
+++ b/doc/proto.md
@@ -1549,6 +1549,32 @@ during option haggling in the fixed newstyle negotiation.
       - 32 bits, preferred block size  
       - 32 bits, maximum block size  

+    * `NBD_INFO_INIT_STATE` (4)
+
+      Represents any properties of the export that are known by the
+      server to be true when the connection is first established, even
+      if these properties might change by later actions.  A server MAY
+      leave a particular property bit unset even if that property is
+      true; and a client SHOULD treat a reply of 0 for all properties
+      the same as if the server had omitted `NBD_INFO_INIT_STATE` in
+      its reply.  A client MUST ignore unknown property bits.  The
+      *length* MUST be 4, and the reply payload is interpreted as:
+
+      - 16 bits, `NBD_INFO_INIT_STATE`  
+      - 16 bits, bitwise-or of known properties  
+
+      The following bits represent known properties:
+
+      - bit 0, `NBD_INIT_SPARSE`; the image contains at least one
+        region that is not fully allocated, whether or not the
+        combination of `NBD_CMD_BLOCK_STATUS` with the
+        "base:allocation" meta context would report the same (via
+        `NBD_STATE_HOLE`) for at least one byte.
+      - bit 1, `NBD_INIT_ZERO`; all bytes in the export initially read
+        as zeroes, whether or not the combination of
+        `NBD_CMD_BLOCK_STATUS` with the "base:allocation" meta context
+        would report the same (via `NBD_STATE_ZERO`) over all bytes.
+
 * `NBD_REP_META_CONTEXT` (4)

     A description of a metadata context. Data:
-- 
2.24.1