Introduce a request type with payload. Use it to add 64bit support to data-less commands.
Signed-off-by: Vladimir Sementsov-Ogievskiy <[email protected]> --- 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` -- 2.21.0
