Re: [Qemu-devel] [PATCH] doc: Flip bit sense for allowing trim during WRITE_ZEROES

["Denis V. Lunev" <den@openvz.org>]

On 04/02/2016 12:29 AM, Eric Blake wrote:
> Rather than requiring allocation by default and allowing trims
> only on request during WRITE_ZEROES, it seems like a better
> default is to allow server optimizations by default and require
> full allocation by specific request.  Since WRITE_ZEROES is
> experimental and has not yet been implemented, we can flip the
> sense of the command flag so that the default flags of all 0s
> is the most efficient, and flags (whether _FUA or _NO_HOLE) are
> added to make the operation have tighter constraints but
> possibly slower execution.
>
> The name NO_HOLE is also slightly nicer at expressing the fact
> that there is no dependency on whether NBD_CMD_TRIM is supported.
>
> Also tweak a couple of formatting issues for consistency (for
> example, only reserve a bit number in one place).
>
> Signed-off-by: Eric Blake <eblake@redhat.com>
> ---
>   doc/proto.md | 30 +++++++++++++++++-------------
>   1 file changed, 17 insertions(+), 13 deletions(-)
>
> diff --git a/doc/proto.md b/doc/proto.md
> index 758a661..725af4d 100644
> --- a/doc/proto.md
> +++ b/doc/proto.md
> @@ -288,10 +288,10 @@ 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
> -- bit 7, `NBD_FLAG_SEND_DF`; defined by the `STRUCTURED_REPLY` extension;
> -  see below.
> +- bit 6, `NBD_FLAG_SEND_WRITE_ZEROES`; defined by the experimental
> +  `WRITE_ZEROES` extension; see below.
> +- bit 7, `NBD_FLAG_SEND_DF`; defined by the experimental `STRUCTURED_REPLY`
> +  extension; see below.
>
>   Clients SHOULD ignore unknown flags.
>
> @@ -483,7 +483,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_MAY_TRIM`; defined by the experimental `WRITE_ZEROES`
> +- bit 1, `NBD_CMD_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
> @@ -736,7 +736,7 @@ 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)
> +* `NBD_CMD_WRITE_ZEROES`
>
>       A write request with no payload. Length and offset define the location
>       and amount of data to be zeroed.
> @@ -753,9 +753,13 @@ one new command and one new command flag.
>       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.
> +    By default, the server MAY use trimming to zero out the area, even
> +    if it did not advertise `NBD_FLAG_SEND_TRIM`; but it MUST ensure
> +    that the data reads back as zero.  However, the client MAY set the
> +    command flag `NBD_CMD_FLAG_NO_HOLE` to inform the server that the
> +    area MUST be fully provisioned, ensuring that future writes to the
> +    same area will not cause fragmentation or cause failure due to
> +    insufficient space.
>
>       If an error occurs, the server SHOULD set the appropriate error code
>       in the error field. The server MAY then close the connection.
> @@ -766,9 +770,9 @@ 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
> +- `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.
>
>   ### `STRUCTURED_REPLY` extension
> @@ -893,7 +897,7 @@ error, and alters the reply to the `NBD_CMD_READ` request.
>         were sent earlier in the structured reply, the server SHOULD NOT
>         send multiple distinct offsets that lie within the bounds of a
>         single content chunk.  Valid as a reply to `NBD_CMD_READ`,
> -      `NBD_CMD_WRITE`, and `NBD_CMD_TRIM`.
> +      `NBD_CMD_WRITE`, `NBD_CMD_WRITE_ZEROES`, and `NBD_CMD_TRIM`.
>
>         The payload is structured as:
>
- do not see the problem in this change. It looks correct to me