[Nbd] [PATCH/RFCv2] Remove NBD_OPT_BLOCK_SIZE
A server can determine whether a client supports block sizes by
the fact it uses NBD_OPT_INFO or NBD_OPT_GO, as these are part
of the same extension. Therefore there is no need for
NBD_OPT_BLOCK_SIZE, or for NBD_REP_ERR_BLOCK_SIZE_REQD. This
substantially simplifies the extension.
Signed-off-by: Alex Bligh <alex@...872...>
---
doc/proto.md | 81 +++++++++++++++++++-----------------------------------------
1 file changed, 25 insertions(+), 56 deletions(-)
Let's see if Wouter has any comments; if I hear nothing I'll
commit this one.
Changes from v1:
* Per Eric, make use of either NBD_OPT_INFO or NBD_OPT_GO sufficient
to signal support.
* Per Eric, restore comment about O_DIRECT
diff --git a/doc/proto.md b/doc/proto.md
index f7cbcfe..c6ed3bd 100644
--- a/doc/proto.md
+++ b/doc/proto.md
@@ -641,12 +641,24 @@ by other users, so has been moved out of the "experimental" section.
During transmission phase, several operations are constrained by the
export size sent by the final `NBD_OPT_EXPORT_NAME` or `NBD_OPT_GO`,
as well as by three block sizes defined here (minimum, preferred, and
-maximum). If a client can honor server block sizes (as set out in
-`NBD_OPT_BLOCK_SIZE`), it SHOULD announce this
-during the handshake phase, and SHOULD use `NBD_OPT_GO` rather than
-`NBD_OPT_EXPORT_NAME`. A server SHOULD advertise the block size
-contraints during handshake phase via `NBD_OPT_INFO`. A server
-and client MAY agree on block sizes via out of band means.
+maximum).
+
+If a client can honor server block size constraints (as set out below
+and under `NBD_INFO_BLOCK_SIZE`), it SHOULD announce this during the
+handshake phase by using `NBD_OPT_INFO` and/or `NBD_OPT_GO`, and SHOULD
+use `NBD_OPT_GO` rather than `NBD_OPT_EXPORT_NAME`. A server with block
+size constraints other than the default SHOULD advertise the block size
+contraints during handshake phase via `NBD_INFO_BLOCK_SIZE` in response
+to `NBD_OPT_INFO` or `NBD_OPT_GO`. A server and client MAY agree on
+block sizes via out of band means.
+
+Some servers are able to make optimizations, such as opening files
+with O_DIRECT, if they know that the client will obey a particular
+minimum block size, where it must fall back to safer but slower code
+if the client might send unaligned requests. A server is entitled to
+assume that a client that issues `NBD_OPT_INFO` or `NBD_OPT_GO` will
+either support the blocksize constraints it has supplied using
+`NBD_INFO_BLOCK_SIZE`, or will not continue the session.
If block sizes have not been advertised or agreed on externally, then
a client SHOULD assume a default minimum block size of 1, a preferred
@@ -654,9 +666,7 @@ block size of 2^12 (4,096), and a maximum block size of the smaller of
the export size or 0xffffffff (effectively unlimited). A server that
wants to enforce block sizes other than the defaults specified here
MAY refuse to go into transmission phase with a client that uses
-`NBD_OPT_EXPORT_NAME` (via a hard disconnect) or which fails to use
-`NBD_OPT_BLOCK_SIZE` (where the server uses
-`NBD_REP_ERR_BLOCK_SIZE_REQD` in response to `NBD_OPT_GO`), although a
+`NBD_OPT_EXPORT_NAME` (via a hard disconnect), although a
server SHOULD permit such clients if block sizes can be agreed on
externally. When allowing such clients, the server MUST cleanly error
commands that fall outside block size parameters without corrupting
@@ -907,13 +917,6 @@ of the newstyle negotiation.
export. In this case, a FORCEDTLS server MUST NOT send
`NBD_REP_INFO` replies, but a SELECTIVETLS server MAY do so if
this is a TLS-only export.
- - `NBD_REP_ERR_BLOCK_SIZE_REQD`: The server requires the client to
- negotiate `NBD_OPT_BLOCK_SIZE` prior to entering transmission
- phase, because the server will be using non-default block sizes.
- In this case, the server SHOULD first send at least an
- `NBD_REP_INFO` reply with `NBD_INFO_BLOCK_SIZE` data. This
- error MUST NOT be used if the client has already negotiated
- `NBD_OPT_BLOCK_SIZE`.
Additionally, if TLS has not been initiated, the server MAY reply
with `NBD_REP_ERR_TLS_REQD` (instead of `NBD_REP_ERR_UNKNOWN`) to
@@ -957,33 +960,6 @@ of the newstyle negotiation.
Defined by the experimental `STRUCTURED_REPLY` [extension](https://github.com/yoe/nbd/blob/extension-structured-reply/doc/proto.md).
-- `NBD_OPT_BLOCK_SIZE` (9)
-
- The client wishes to inform the server of its intent to obey block
- sizes. The option request has no additional data.
-
- Some servers are able to make optimizations, such as opening files
- with O_DIRECT, if they know that the client will obey a particular
- minimum block size, where it must fall back to safer but slower code
- if the client might send unaligned requests.
-
- The server MUST reply with `NBD_REP_ACK`, after which point the
- client SHOULD use `NBD_OPT_GO` rather than `NBD_OPT_EXPORT_NAME`,
- and the server SHOULD include `NBD_INFO_BLOCK_SIZE` in its reply.
- If successfully negotiated, and the server advertises block sizes,
- the client MUST NOT send unaligned requests.
-
- For backwards compatibility, clients SHOULD be prepared to also
- handle `NBD_REP_ERR_UNSUP`, which means the server SHOULD NOT be
- advertising block sizes, and the client MAY assume the server will
- honor default block sizes.
-
- Note that a client MAY obey non-default block sizes even without
- advertising intent or even when the server does not advertise block
- sizes; and that a server MAY advertise block sizes even when a client
- does not advertise intent. Therefore, the use of this option is
- independent of whether the server uses `NBD_INFO_BLOCK_SIZE`.
-
#### Option reply types
These values are used in the "reply type" field, sent by the server
@@ -1079,18 +1055,18 @@ during option haggling in the fixed newstyle negotiation.
Represents the server's advertised block sizes; see the "Block
sizes" section for more details on what these values represent,
- and on constraints on their values. The server MAY send this
- info whether or not the client has negotiated
- `NBD_OPT_BLOCK_SIZE`, and SHOULD send this info if it intends to
- enforce block sizes other than the defaults. The *length* MUST
- be 14, and the reply payload is interpreted as:
+ and on constraints on their values. The server MUST send this info if
+ it intends to enforce block sizes other than the defaults. After
+ sending this information, the server can legitimately assume that
+ any client that continues the session will support the block size
+ constraints supplied. The *length* MUST be 14, and the reply payload
+ is interpreted as:
- 16 bits, `NBD_INFO_BLOCK_SIZE`
- 32 bits, minimum block size
- 32 bits, preferred block size
- 32 bits, maximum block size
-
There are a number of error reply types, all of which are denoted by
having bit 31 set. All error replies MAY have some data set, in which
case that data is an error message string suitable for display to the user.
@@ -1136,13 +1112,6 @@ case that data is an error message string suitable for display to the user.
The server is unwilling to continue negotiation as it is in the
process of being shut down.
-* `NBD_REP_ERR_BLOCK_SIZE_REQD` (2^32 + 8)
-
- The server is unwilling to enter transmission phase for a given
- export unless the client first acknowledges (via
- `NBD_OPT_BLOCK_SIZE`) that it will obey non-default block sizing
- requirements.
-
### Transmission phase
#### Command flags
--
1.9.1
Reply to: