Re: [PATCH 1/2] block: Expose block limits for images in QMP

[Markus Armbruster <armbru@redhat.com>]

Kevin Wolf <kwolf@redhat.com> writes:

> This information can be useful both for debugging and for management
> tools trying to configure guest devices with the optimal limits
> (possibly across multiple hosts). There is no reason not to make it
> available, so just add it to BlockNodeInfo.
>
> Signed-off-by: Kevin Wolf <kwolf@redhat.com>
> ---
>  qapi/block-core.json             | 59 ++++++++++++++++++++++++++++++++
>  block/qapi.c                     | 34 ++++++++++++++++--
>  tests/qemu-iotests/184           |  3 +-
>  tests/qemu-iotests/184.out       |  8 -----
>  tests/qemu-iotests/common.filter |  3 +-
>  5 files changed, 94 insertions(+), 13 deletions(-)
>
> diff --git a/qapi/block-core.json b/qapi/block-core.json
> index dc6eb4ae23..eda041ac1c 100644
> --- a/qapi/block-core.json
> +++ b/qapi/block-core.json
> @@ -275,6 +275,62 @@
>        'file': 'ImageInfoSpecificFileWrapper'
>    } }
>  
> +##
> +# @BlockLimitsInfo:
> +#
> +# @request-alignment: Alignment requirement, in bytes, for offset/length of I/O
> +#     requests.
> +#
> +# @max-discard: Maximum number of bytes that can be discarded at once. If not
> +#     present, there is no specific maximum.
> +#
> +# @discard-alignment: Optimal alignment for discard requests in bytes. A power
> +#     of 2 is best, but not mandatory. If not present, discards don't have a
> +#     alignment requirement different from @request-alignment.

What does the second sentence try to convey?  As far as I can tell, QMP
has BlockLimitsInfo is only in the result of query-block and
query-named-block-nodes, i.e. it's not something the user picks.

> +#
> +# @max-write-zeroes: Maximum number of bytes that can be zeroed out at once. If
> +#     not present, there is no specific maximum.
> +#
> +# @write-zeroes-alignment: Optimal alignment for write_zeroes requests in
> +#     bytes. A power of 2 is best, but not mandatory. If not present,
> +#     write_zeroes doesn't have a alignment requirement different from
> +#     @request-alignment.

Likewise.

> +#
> +# @opt-transfer: Optimal transfer length in bytes. If not present, there is no
> +#     preferred size.
> +#
> +# @max-transfer: Maximal transfer length in bytes. If not present, there is no
> +#     specific maximum.
> +#
> +# @max-hw-transfer: Maximal hardware transfer length in bytes.  Applies
> +#     whenever transfers to the device bypass the kernel I/O scheduler, for
> +#     example with SG_IO. If not present, there is no specific maximum.
> +#
> +# @max-iov: Maximum number of scatter/gather elements
> +#
> +# @max-hw-iov: Maximal number of scatter/gather elements allowed by the hardware.

Maximum number

> +#     Applies whenever transfers to the device bypass the kernel I/O scheduler,
> +#     for example with SG_IO. If not present, the hardware limits is unknown
> +#     and @max-iov is always used.
> +#
> +# @min-mem-alignment: memory alignment in bytes so that no bounce buffer is needed
> +#
> +# @opt-mem-alignment: memory alignment in bytes that is used for bounce buffers

Why is this "opt"?  I guess it means "optimal".

> +##
> +{ 'struct': 'BlockLimitsInfo',
> +  'data': { 'request-alignment': 'uint32',
> +            '*max-discard': 'uint64',
> +            '*discard-alignment': 'uint32',
> +            '*max-write-zeroes': 'uint64',
> +            '*write-zeroes-alignment': 'uint32',
> +            '*opt-transfer': 'uint32',
> +            '*max-transfer': 'uint32',
> +            '*max-hw-transfer': 'uint32',
> +            'max-iov': 'int',
> +            '*max-hw-iov': 'int',
> +            'min-mem-alignment': 'size',
> +            'opt-mem-alignment': 'size' } }
> +
>  ##
>  # @BlockNodeInfo:
>  #
> @@ -304,6 +360,8 @@
>  #
>  # @snapshots: list of VM snapshots
>  #
> +# @limits: block limits that are used for I/O on the node (Since 10.2)
> +#
>  # @format-specific: structure supplying additional format-specific
>  #     information (since 1.7)
>  #
> @@ -315,6 +373,7 @@
>             '*cluster-size': 'int', '*encrypted': 'bool', '*compressed': 'bool',
>             '*backing-filename': 'str', '*full-backing-filename': 'str',
>             '*backing-filename-format': 'str', '*snapshots': ['SnapshotInfo'],
> +           '*limits': 'BlockLimitsInfo',
>             '*format-specific': 'ImageInfoSpecific' } }
>  
>  ##

docs/devel/qapi-code-gen.rst:

    For legibility, wrap text paragraphs so every line is at most 70
    characters long.

    Separate sentences with two spaces.

[...]