Re: [Qemu-devel] [PATCHv4] Improve the documentation of NBD_CMD_FLUSH and NBD_CMD_FLAG_FUA.

[Eric Blake <eblake@redhat.com>]

[-- Attachment #1: Type: text/plain, Size: 2194 bytes --]

On 04/05/2016 09:30 AM, Alex Bligh wrote:
> Improve the documentation of NBD_CMD_FLUSH and NBD_CMD_FLAG_FUA. Specifically
> the latter may be set on any command, and its semantics on commands other
> than NBD_CMD_WRITE need explaining. Further, explain how these relate to
> reordering of commands.
> 
> Signed-off-by: Alex Bligh <alex@alex.org.uk>
> ---
>  doc/proto.md | 59 ++++++++++++++++++++++++++++++++++++++++++++---------------
>  1 file changed, 44 insertions(+), 15 deletions(-)
> 

>  
> -- 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 0, `NBD_CMD_FLAG_FUA`; This flag is valid for all commands, provided
> +  `NBD_FLAG_SEND_FUA` has been negotiated, in which case the server MUST
> +  accept all commands with this bit set (even by ignoring the bit). The
> +  client SHOULD NOT set this bit unless the command has the potential of
> +  writing data (current commands are `NBD_CMD_WRITE`, `NBD_CMD_WRITE_ZEROES`
> +  and `NBD_CMD_TRIM`), however note that existing clients are known to set this
> +  bit on other commands. Subject to that, and provided `NBD_FLAG_SEND_FUA`
> +  is negotiated, the client MAY set this bit on all, no or some commands
> +  as it wishes (see the section on Ordering of messages and writes for
> +  details). If the server receives a command with `NBD_CMD_FLAG_FUA`
> +  set it MUST NOT send its reply to that command until all write
> +  operations (if any) associated with that command command have been

s/command command/command/

> +  completed and persisted to non-volatile storage. If the command does
> +  not in fact write data (for instance on an `NBD_CMD_TRIM` in a situation
> +  where the command as a whole is ignored), the server MAY ignore this bit
> +  being set on such a command.

With the duplicate word removed,
Reviewed-by: Eric Blake <eblake@redhat.com>

-- 
Eric Blake   eblake redhat com    +1-919-301-3266
Libvirt virtualization library http://libvirt.org


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 604 bytes --]