Re: [Qemu-devel] [Nbd] [PATCH v2 1/1] NBD proto: add WRITE_ZEROES extension

[Wouter Verhelst]

Hi,

Thanks, applied.

On Thu, Mar 31, 2016 at 04:02:05PM +0300, Denis V. Lunev wrote:
> From: Pavel Borzenkov <address@hidden>
> 
> There exist some cases when a client knows that the data it is going to
> write is all zeroes. Such cases include mirroring or backing up a device
> implemented by a sparse file.
> 
> With current NBD command set, the client has to issue NBD_CMD_WRITE
> command with zeroed payload and transfer these zero bytes through the
> wire. The server has to write the data onto disk, effectively denying
> the sparseness.
> 
> To remedy this, the patch adds WRITE_ZEROES extension with one new
> NBD_CMD_WRITE_ZEROES command.
> 
> Signed-off-by: Pavel Borzenkov <address@hidden>
> Signed-off-by: Denis V. Lunev <address@hidden>
> CC: Wouter Verhelst <address@hidden>
> CC: Paolo Bonzini <address@hidden>
> CC: Kevin Wolf <address@hidden>
> CC: Stefan Hajnoczi <address@hidden>
> CC: Wouter Verhelst <address@hidden>
> CC: Alex Bligh <address@hidden>
> CC: Eric Blake <address@hidden>
> ---
> v2:
>   - rebased on master
>   - explicitly state that the client must not set NBD_CMD_WRITE_ZEROES if
>     support for it wasn't negotiated with the server;
>   - add new command flag's description in format suitable for moving to
>     "Command flags" section.
> 
> 
>  doc/proto.md | 64 
> ++++++++++++++++++++++++++++++++++++++++++++++++++++++++----
>  1 file changed, 60 insertions(+), 4 deletions(-)
> 
> diff --git a/doc/proto.md b/doc/proto.md
> index c1e05c5..a574563 100644
> --- a/doc/proto.md
> +++ b/doc/proto.md
> @@ -261,6 +261,8 @@ immediately after the handshake flags field in oldstyle 
> negotiation:
>    schedule I/O accesses as for a rotational medium
>  - bit 5, `NBD_FLAG_SEND_TRIM`; should be set to 1 if the server supports
>    `NBD_CMD_TRIM` commands
> +- bit 6, `NBD_FLAG_SEND_WRITE_ZEROES`; should be set to 1 if the server
> +  supports `NBD_CMD_WRITE_ZEROES` commands
>  
>  Clients SHOULD ignore unknown flags.
>  
> @@ -444,10 +446,13 @@ affects a particular command.  Clients MUST NOT set a 
> command flag bit
>  that is not documented for the particular command; and whether a flag is
>  valid may depend on negotiation during the handshake phase.
>  
> -- bit 0, `NBD_CMD_FLAG_FUA`; valid during `NBD_CMD_WRITE`.  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 0, `NBD_CMD_FLAG_FUA`; valid during `NBD_CMD_WRITE` and
> +  `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_MAY_TRIM`; defined by the experimental `WRITE_ZEROES`
> +  extension; see below.
>  
>  #### Request types
>  
> @@ -523,6 +528,10 @@ 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_WRITE_ZEROES` (6)
> +
> +    Defined by the experimental `WRITE_ZEROES` extension; see below.
> +
>  * Other requests
>  
>      Some third-party implementations may require additional protocol
> @@ -654,6 +663,53 @@ option reply type.
>        message if they do not also send it as a reply to the
>        `NBD_OPT_SELECT` message.
>  
> +### `WRITE_ZEROES` extension
> +
> +There exist some cases when a client knows that the data it is going to write
> +is all zeroes. Such cases include mirroring or backing up a device 
> implemented
> +by a sparse file. With current NBD command set, the client has to issue
> +`NBD_CMD_WRITE` command with zeroed payload and transfer these zero bytes
> +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.
> +
> +* `NBD_CMD_WRITE_ZEROES` (6)
> +
> +    A write request with no payload. Length and offset define the location
> +    and amount of data to be zeroed.
> +
> +    The server MUST zero out the data on disk, and then send the reply
> +    message. The server MAY send the reply message before the data has
> +    reached permanent storage.
> +
> +    A client MUST NOT send a write zeroes request unless
> +    `NBD_FLAG_SEND_WRITE_ZEROES` was set in the transmission flags field.
> +
> +    If the `NBD_FLAG_SEND_FUA` flag was set in the transmission flags field,
> +    the client MAY set the flag `NBD_CMD_FLAG_FUA` in the command flags 
> field.
> +    If this flag was set, the server MUST NOT send the reply until it has
> +    ensured that the newly-zeroed data has reached permanent storage.
> +
> +    If the flag `NBD_CMD_FLAG_MAY_TRIM` was set by the client in the command
> +    flags field, the server MAY use trimming to zero out the area, but it
> +    MUST ensure that the data reads back as zero.
> +
> +    If an error occurs, the server SHOULD set the appropriate error code
> +    in the error field. The server MAY then close the connection.
> +
> +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.
> +
> +The extension adds the following new command flag:
> +
> +- bit 1, `NBD_CMD_FLAG_MAY_TRIM`; valid during `NBD_CMD_WRITE_ZEROES`.
> +  SHOULD be set to 1 if the client allows the server to use trim to perform
> +  the requested operation. The client MAY send `NBD_CMD_FLAG_MAY_TRIM` even
> +  if `NBD_FLAG_SEND_TRIM` was not set in the transmission flags field.
> +
>  ## About this file
>  
>  This file tries to document the NBD protocol as it is currently
> -- 
> 2.1.4
> 
> 
> ------------------------------------------------------------------------------
> Transform Data into Opportunity.
> Accelerate data analysis in your applications with
> Intel Data Analytics Acceleration Library.
> Click to learn more.
> http://pubads.g.doubleclick.net/gampad/clk?id=278785471&iu=/4140
> _______________________________________________
> Nbd-general mailing list
> address@hidden
> https://lists.sourceforge.net/lists/listinfo/nbd-general
> 

-- 
< ron> I mean, the main *practical* problem with C++, is there's like a dozen
       people in the world who think they really understand all of its rules,
       and pretty much all of them are just lying to themselves too.
 -- #debian-devel, OFTC, 2016-02-12