Re: [PATCH v2 01/12] qapi/common: Clarify what IoOperationType is for

[Markus Armbruster <armbru@redhat.com>]

Hanna Czenczek <hreitz@redhat.com> writes:

> The documentation for this type is a bit sparse right now, and
> specifically does not explain why it is limited to read/write only;
> "I/O operation type" could well imply this should distinguish a much
> broader range of operations like flushes, discards, etc., but it does
> not.
>
> Make a note why that is, which is that these types reflect the block
> device on-error policy settings that we have, which are rerror for read
> and werror for write.
>
> Signed-off-by: Hanna Czenczek <hreitz@redhat.com>
> ---
>  qapi/common.json | 5 ++++-
>  1 file changed, 4 insertions(+), 1 deletion(-)
>
> diff --git a/qapi/common.json b/qapi/common.json
> index 1352e664b23..880eb87a9cb 100644
> --- a/qapi/common.json
> +++ b/qapi/common.json
> @@ -9,7 +9,10 @@
>  
>  ##
>  # @IoOperationType:
> -#     An enumeration of the I/O operation types
> +#     An enumeration of the I/O operation types, limited to the block
> +#     device on-error policy settings we have (rerror and werror).
> +#     For reference, the corresponding error policy values are set in
> +#     `BlockdevOnError`.
>  #
>  # @read: read operation
>  #

I believe I get what you mean only because I read the cover letter
first.

My first attempt

    I/O operation types that may have a block device on-error policy.

is still confusing, because we use "block device" both for frontends and
backends.  I believe "block device on-error policy" refers to the qdev
properties "rerror" and "werror" certain block frontends / device models
have (virtio-blk-device, scsi-hd, scsi-cd, usb-storage).  Possible
clarification:

    These are the properties "rerror" and "werror" certain block device
    models have.

And then maybe

    @read: read operation, corresponding to property "rerror"

    @write: write operation, corresponding to property "werror"