[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [PATCH 1/2] qapi/block-core: Improve MapEntry documentation
From: |
Markus Armbruster |
Subject: |
Re: [PATCH 1/2] qapi/block-core: Improve MapEntry documentation |
Date: |
Fri, 06 Nov 2020 08:44:55 +0100 |
User-agent: |
Gnus/5.13 (Gnus v5.13) Emacs/27.1 (gnu/linux) |
Max Reitz <mreitz@redhat.com> writes:
> MapEntry and BlockDeviceMapEntry are kind of the same thing, and the
> latter is not used, so we want to remove it. However, the documentation
> it provides for some fields is better than that of MapEntry, so steal
> some of it for the latter.
>
> (And adjust them a bit in the process, because I feel like we can make
> them even clearer.)
>
> Signed-off-by: Max Reitz <mreitz@redhat.com>
> ---
> qapi/block-core.json | 18 +++++++++++++-----
> 1 file changed, 13 insertions(+), 5 deletions(-)
>
> diff --git a/qapi/block-core.json b/qapi/block-core.json
> index 1b8b4156b4..3f86675357 100644
> --- a/qapi/block-core.json
> +++ b/qapi/block-core.json
> @@ -244,17 +244,25 @@
> #
> # Mapping information from a virtual block range to a host file range
> #
> -# @start: the start byte of the mapped virtual range
> +# @start: virtual (guest) offset of the first byte described by this
> +# entry
> #
> # @length: the number of bytes of the mapped virtual range
> #
> -# @data: whether the mapped range has data
> +# @data: reading the image will actually read data from a file (in
> +# particular, if @offset is present this means that the sectors
> +# are not simply preallocated, but contain actual data in raw
> +# format)
> #
> -# @zero: whether the virtual blocks are zeroed
> +# @zero: whether the virtual blocks read as zeroes
> #
> -# @depth: the depth of the mapping
> +# @depth: number of layers (0 = top image, 1 = top image's backing
> +# file, ..., n - 1 = bottom image (where n is the number of
> +# images in the chain)) before reaching one for which the
> +# range is allocated
> #
> -# @offset: the offset in file that the virtual sectors are mapped to
> +# @offset: if present, the image file stores the data for this range
> +# in raw format at the given (host) offset
> #
> # @filename: filename that is referred to by @offset
> #
I can't vouch for the comment's accuracy without reading a lot of code,
but I can say that the comment is clearly much clearer, so:
Acked-by: Markus Armbruster <armbru@redhat.com>