[Nbd] [PATCH v2] doc: Allow NBD_CMD_FLAG_NO_HOLE during NBD_CMD_WRITE
qemu already has an existing server implementation option that will
explicitly search the payload of NBD_CMD_WRITE for large blocks of
zeroes, and punch holes in the underlying file. For old clients
that don't know how to use the new NBD_CMD_WRITE_ZEROES, this is a
workaround to keep the server's destination file approximately as
sparse as the client's source. However, for new clients that know
how to explicitly request holes, it is unnecessary overhead; and
can lead to the server punching a hole and risking fragmentation or
future ENOSPC even when the client explicitly wanted to write
zeroes rather than a hole. So it makes sense to let the new
NBD_CMD_FLAG_NO_HOLE work for WRITE as well as WRITE_ZEROES.
Signed-off-by: Eric Blake <eblake@...696...>
---
v2: fix some typos, add a sentence about server MUST support
NBD_CMD_FLAG_NO_HOLE if it advertises NBD_FLAG_SEND_WRITE_ZEROES
doc/proto.md | 38 ++++++++++++++++++++++++++++++--------
1 file changed, 30 insertions(+), 8 deletions(-)
diff --git a/doc/proto.md b/doc/proto.md
index 35a3266..bca0525 100644
--- a/doc/proto.md
+++ b/doc/proto.md
@@ -487,7 +487,7 @@ valid may depend on negotiation during the handshake phase.
`NBD_CMD_WRITE_ZEROES` commands. SHOULD be set to 1 if the client requires
"Force Unit Access" mode of operation. MUST NOT be set unless transmission
flags included `NBD_FLAG_SEND_FUA`.
-- bit 1, `NBD_CMD_NO_HOLE`; defined by the experimental `WRITE_ZEROES`
+- bit 1, `NBD_CMD_FLAG_NO_HOLE`; defined by the experimental `WRITE_ZEROES`
extension; see below.
- bit 2, `NBD_CMD_FLAG_DF`; defined by the experimental `STRUCTURED_REPLY`
extension; see below
@@ -574,7 +574,7 @@ The following request types exist:
After issuing this command, a client MUST NOT make any assumptions
about the contents of the export affected by this command, until
- overwriting it again with `NBD_CMD_WRITE`.
+ overwriting it again with `NBD_CMD_WRITE` or `NBD_CMD_WRITE_ZEROES`.
A client MUST NOT send a trim request unless `NBD_FLAG_SEND_TRIM`
was set in the transmission flags field.
@@ -737,8 +737,14 @@ by a sparse file. With current NBD command set, the client has to issue
through the wire. The server has to write the data onto disk, effectively
losing the sparseness.
-To remedy this, a `WRITE_ZEROES` extension is envisioned. This extension adds
-one new command and one new command flag.
+To remedy this, a `WRITE_ZEROES` extension is envisioned. This
+extension adds one new transmission flag, one new command, and one new
+command flag; and refines an existing command.
+
+* `NBD_FLAG_SEND_WRITE_ZEROES`
+
+ The server SHOULD set this transmission flag to 1 if the
+ `NBD_CMD_WRITE_ZEROES` request is supported.
* `NBD_CMD_WRITE_ZEROES`
@@ -772,12 +778,28 @@ The server SHOULD return `ENOSPC` if it receives a write zeroes request
including one or more sectors beyond the size of the device. It SHOULD
return `EPERM` if it receives a write zeroes request on a read-only export.
+* `NBD_CMD_WRITE`
+
+ By default, the server MAY search for large contiguous blocks of
+ all zero content, and use trimming to zero out those portions of
+ the write, even if it did not advertise `NBD_FLAG_SEND_TRIM`; but
+ it MUST ensure that any trimmed areas of data read back as zero.
+ However, the client MAY set the command flag
+ `NBD_CMD_FLAG_NO_HOLE` to inform the server that the entire
+ written area MUST be fully provisioned, ensuring that future
+ writes to the same area will not cause fragmentation or cause
+ failure due to insufficient space. Clients SHOULD NOT set this
+ flag unless the server advertised `NBD_FLAG_SEND_WRITE_ZEROES` in
+ the transmission flags.
+
The extension adds the following new command flag:
-- `NBD_CMD_FLAG_NO_HOLE`; valid during `NBD_CMD_WRITE_ZEROES`.
- SHOULD be set to 1 if the client wants to ensure that the server does
- not create a hole. The client MAY send `NBD_CMD_FLAG_NO_HOLE` even
- if `NBD_FLAG_SEND_TRIM` was not set in the transmission flags field.
+- `NBD_CMD_FLAG_NO_HOLE`; valid during `NBD_CMD_WRITE` and
+ `NBD_CMD_WRITE_ZEROES`. SHOULD be set to 1 if the client wants to
+ ensure that the server does not create a hole. The client MAY send
+ `NBD_CMD_FLAG_NO_HOLE` even if `NBD_FLAG_SEND_TRIM` was not set in
+ the transmission flags field. The server MUST support the use of
+ this flag if it advertises `NBD_FLAG_SEND_WRITE_ZEROES`.
### `STRUCTURED_REPLY` extension
--
2.5.5
Reply to: