[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [PATCH v9 1/2] docs: improve qcow2 spec about extending image header
From: |
Max Reitz |
Subject: |
Re: [PATCH v9 1/2] docs: improve qcow2 spec about extending image header |
Date: |
Mon, 20 Jan 2020 17:03:24 +0100 |
User-agent: |
Mozilla/5.0 (X11; Linux x86_64; rv:68.0) Gecko/20100101 Thunderbird/68.3.1 |
On 16.12.19 13:17, Vladimir Sementsov-Ogievskiy wrote:
> Make it more obvious how to add new fields to the version 3 header and
> how to interpret them.
>
> The specification is adjusted so for new defined optional fields:
>
> 1. Software may support some of these optional fields and ignore the
> others, which means that features may be backported to downstream
> Qemu independently.
> 2. If we want to add incompatible field (or a field, for which some its
> values would be incompatible), it must be accompanied by
> incompatible feature bit.
>
> Also the concept of "default is zero" is clarified, as it's strange to
> say that the value of the field is assumed to be zero for the software
> version which don't know about the field at all and don't know how to
> treat it be it zero or not.
>
> Signed-off-by: Vladimir Sementsov-Ogievskiy <address@hidden>
> ---
> docs/interop/qcow2.txt | 39 ++++++++++++++++++++++++++++++++++++---
> 1 file changed, 36 insertions(+), 3 deletions(-)
I put review of this off for so long because I always waited for Eric to
give his R-b, but maybe not.
I generally think that he’s stricter on what to write in documentation,
and accordingly I only have nit picks on spelling and structure:
> diff --git a/docs/interop/qcow2.txt b/docs/interop/qcow2.txt
> index af5711e533..d92c827763 100644
> --- a/docs/interop/qcow2.txt
> +++ b/docs/interop/qcow2.txt
> @@ -79,9 +79,9 @@ The first cluster of a qcow2 image contains the file header:
> Offset into the image file at which the snapshot table
> starts. Must be aligned to a cluster boundary.
>
> -If the version is 3 or higher, the header has the following additional
> fields.
> -For version 2, the values are assumed to be zero, unless specified otherwise
> -in the description of a field.
> +For version 2, the header is exactly 72 bytes in length, and finishes here.
> +For version 3 or higher, the header length is at least 104 bytes, including
> +the next fields through header_length.
>
> 72 - 79: incompatible_features
> Bitmask of incompatible features. An implementation must
> @@ -164,6 +164,39 @@ in the description of a field.
> 100 - 103: header_length
> Length of the header structure in bytes. For version 2
> images, the length is always assumed to be 72 bytes.
> + For version 3 it's at least 104 bytes and must be a
> multiply
s/multiply/multiple/
> + of 8.
> +
> +Additional fields (version 3 and higher)
If this is supposed to be a heading, maybe it should enclosed by “===”
on both sides.
> +
> +In general, these fields are optional and may be safely ignored by the
> software,
> +as well as filled by zeros (which is equal to field absence), if software
> needs
> +to set field B, but don't want to care about field A, which precedes B. More
s/don't/does not/ (or maybe s/don't want/does not/)
> +formally, additional fields have the following compatibility rules:
> +
> +1. If the value of the additional field must not be ignored for correct
> +handling of the file, it will be accompanied by a corresponding incompatible
> +feature bit.
> +
> +2. If there are no unrecognized incompatible feature bits set, an unknown
> +additional field may be safely ignored other than preserving its value when
> +rewriting the image header.
> +
> +3. An explicit value of 0 will have the same behavior as when the field is
> not
> +present*, if not altered by specific incompatible bit.
s/by specific/by a specific/
> +
> +*. Field is not present when header_length is less or equal to field's
> offset.
s/Field/A field/, s/field's/the field's/
(maybe also +considered, as in "A field is considered not present...")
> +Also, all additional fields are not present for version 2.
> +
> + < ... No additional fields in the header currently ... >
This looks a bit weird to me, but the next patch will remove it again,
so who cares.
> +Header padding
Same heading note here (I’d make this “=== Header padding ===”).
> +
> +@header_length must be a multiply of 8, which means that if last additional
> field
s/multiply/multiple/
> +end is not aligned, some padding is needed. This padding must be zeroed, so
> that,
I think s/last additional field end/the last additional field’s end/, or
maybe s/last additional field end/the end of the last additional field/.
> +if some existing (or future) additional field will fall into the padding, it
> +will be interpreted accordingly to point [3.] of the previous paragraph, i.e.
> +in same manner as when this field is not present.
s/in same/in the same/
>
I think there should be a new heading here
(“=== Header extensions ===”).
Max
> Directly after the image header, optional sections called header extensions
> can
> be stored. Each extension has a structure like the following:
>
signature.asc
Description: OpenPGP digital signature
- Re: [PATCH v9 1/2] docs: improve qcow2 spec about extending image header,
Max Reitz <=