From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from eggs.gnu.org ([2001:4830:134:3::10]:54934) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1anCnk-0006p2-5w for qemu-devel@nongnu.org; Mon, 04 Apr 2016 18:16:53 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1anCng-0001AM-VQ for qemu-devel@nongnu.org; Mon, 04 Apr 2016 18:16:52 -0400 Received: from resqmta-po-09v.sys.comcast.net ([96.114.154.168]:59448) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1anCng-00018q-Od for qemu-devel@nongnu.org; Mon, 04 Apr 2016 18:16:48 -0400 From: Eric Blake Date: Mon, 4 Apr 2016 16:15:43 -0600 Message-Id: <1459808143-22482-1-git-send-email-eblake@redhat.com> In-Reply-To: <1459779314-12266-1-git-send-email-eblake@redhat.com> References: <1459779314-12266-1-git-send-email-eblake@redhat.com> Subject: [Qemu-devel] [PATCH v2] doc: Allow NBD_CMD_FLAG_NO_HOLE during NBD_CMD_WRITE List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , To: nbd-general@lists.sourceforge.net Cc: den@openvz.org, qemu-devel@nongnu.org, alex@alex.org.uk, pborzenkov@virtuozzo.com 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 --- 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