Introduce a request type with payload. Use it to add 64bit support to
data-less commands.
Signed-off-by: Vladimir Sementsov-Ogievskiy <address@hidden>
---
v1 was "[PATCH 0/2] Structured requests and 64bit commands"
v2: - don't touch structured replies. Still, no reason to not use the
same structure as in structured reply chunk
- instead of documenting separate 64bit commands, just define
support for extended request in original commands.
doc/proto.md | 50 +++++++++++++++++++++++++++++++++++++++++++++++---
1 file changed, 47 insertions(+), 3 deletions(-)
diff --git a/doc/proto.md b/doc/proto.md
index fc7baf6..58e932d 100644
--- a/doc/proto.md
+++ b/doc/proto.md
@@ -279,10 +279,10 @@ a soft disconnect.
### Transmission
-There are three message types in the transmission phase: the request,
-the simple reply, and the structured reply chunk. The
+There are four message types in the transmission phase: the request,
+the extended request, the simple reply, and the structured reply chunk. The
transmission phase consists of a series of transactions, where the
-client submits requests and the server sends corresponding replies
+client submits (extended) requests and the server sends corresponding replies
with either a single simple reply or a series of one or more
structured reply chunks per request. The phase continues until
either side terminates transmission; this can be performed cleanly
@@ -353,6 +353,25 @@ C: 64 bits, offset (unsigned)
C: 32 bits, length (unsigned)
C: (*length* bytes of data if the request is of type `NBD_CMD_WRITE`)
+#### Extended request message
+
+The extended request message, sent by the client, looks as follows:
+
+C: 32 bits, 0x23876289, magic (`NBD_EXTENDED_REQUEST_MAGIC`)
+C: 16 bits, flags
+C: 16 bits, type
+C: 64 bits, handle
+C: 32 bits, length of payload (unsigned)
+C: *length* bytes of payload data (if *length* is nonzero)
+
+The client MUST NOT send extended requests, unless
+NBD_FLAG_EXTENDED_REQUEST is negotiated by the server. If
+NBD_OPT_STRUCTURED_REPLY is negotiated client MAY send extended
+requests of types `NBD_CMD_WRITE_ZEROES`, `NBD_CMD_TRIM`,
+`NBD_CMD_BLOCK_STATUS`.
+If the server (with negotiated NBD_FLAG_EXTENDED_REQUEST) receive
+extended request of unsupported type it MUST reply with `NBD_EINVAL`.
+
#### Simple reply message
The simple reply message MUST be sent by the server in response to all
@@ -1082,6 +1101,8 @@ The field has the following format:
will be faster than a regular write). Clients MUST NOT set the
`NBD_CMD_FLAG_FAST_ZERO` request flag unless this transmission flag
is set.
+- bit 12, `NBD_FLAG_EXTENDED_REQUEST`; allow clients to use
+ extended requests.
Clients SHOULD ignore unknown flags.
@@ -1825,6 +1846,11 @@ contents, the client MUST initiate a hard disconnect.
#### Request types
+The following types are shared for request message and extended
+request message. Still, client MUST NOT send extended request of
+specific type unless support for extended request directly defined
+in type description below.
+
The following request types exist:
* `NBD_CMD_READ` (0)
@@ -1986,6 +2012,12 @@ The following request types exist:
A client MUST NOT send a trim request unless `NBD_FLAG_SEND_TRIM`
was set in the transmission flags field.
+ `NBD_CMD_TRIM` supports extended requests, with the following
+ 16-bytes payload:
+
+ 64 bits: offset
+ 64 bits: length
+
* `NBD_CMD_CACHE` (5)
A cache request. The client is informing the server that it plans
@@ -2095,6 +2127,12 @@ The following request types exist:
including one or more sectors beyond the size of the device. It SHOULD
return `NBD_EPERM` if it receives a write zeroes request on a read-only
export.
+ `NBD_CMD_WRITE_ZEROES` supports extended requests, with the following
+ 16-bytes payload:
+
+ 64 bits: offset
+ 64 bits: length
+
* `NBD_CMD_BLOCK_STATUS` (7)
A block status query request. Length and offset define the range
@@ -2154,6 +2192,12 @@ The following request types exist:
`NBD_EINVAL` if it receives a `NBD_CMD_BLOCK_STATUS` request including
one or more sectors beyond the size of the device.
+ `NBD_CMD_BLOCK_STATUS` supports extended requests, with the following
+ 16-bytes payload:
+
+ 64 bits: offset
+ 64 bits: length
+
* `NBD_CMD_RESIZE` (8)
Defined by the experimental `RESIZE`