From: Eric Blake <eblake@redhat.com>
To: Vladimir Sementsov-Ogievskiy <vsementsov@virtuozzo.com>,
qemu-block@nongnu.org
Cc: kwolf@redhat.com, armbru@redhat.com, qemu-devel@nongnu.org,
dplotnikov@virtuozzo.com, den@openvz.org, mreitz@redhat.com
Subject: Re: [PATCH v10 1/2] docs: improve qcow2 spec about extending image header
Date: Mon, 20 Jan 2020 13:42:01 -0600 [thread overview]
Message-ID: <e457c8c4-ae37-9b30-5580-40b34bbf458c@redhat.com> (raw)
In-Reply-To: <20200120171345.24345-2-vsementsov@virtuozzo.com>
On 1/20/20 11:13 AM, 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:
s/so for/so that for/
>
> 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 <vsementsov@virtuozzo.com>
> ---
> docs/interop/qcow2.txt | 44 +++++++++++++++++++++++++++++++++++++++---
> 1 file changed, 41 insertions(+), 3 deletions(-)
>
> diff --git a/docs/interop/qcow2.txt b/docs/interop/qcow2.txt
> index af5711e533..355925c35e 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,44 @@ 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 multiple
> + of 8.
> +
> +
> +=== Additional fields (version 3 and higher) ===
> +
> +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
We're inconsistent on 'zeros' (git grep has 201 hits) vs. 'zeroes' (688
hits); I prefer the latter, but won't object if you don't tweak it since
this is the first use of either spelling in qcow2.txt.
> +to set field B, but does not care about field A, which precedes B. More
s/A, which/A which/
> +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 a specific incompatible bit.
> +
> +*. A field is considered not present when header_length is less or equal to the
s/less/less than/
> +field's offset. Also, all additional fields are not present for version 2.
> +
> + < ... No additional fields in the header currently ... >
> +
> +
> +=== Header padding ===
> +
> +@header_length must be a multiple of 8, which means that if the end of the last
> +additional field is not aligned, some padding is needed. This padding must be
> +zeroed, so that, if some existing (or future) additional field will fall into
s/that, if/that if/
> +the padding, it will be interpreted accordingly to point [3.] of the previous
> +paragraph, i.e. in the same manner as when this field is not present.
> +
> +
> +=== Header extensions ===
>
> Directly after the image header, optional sections called header extensions can
> be stored. Each extension has a structure like the following:
>
We're down to few enough grammar nits that I'm happy with:
Reviewed-by: Eric Blake <eblake@redhat.com>
--
Eric Blake, Principal Software Engineer
Red Hat, Inc. +1-919-301-3226
Virtualization: qemu.org | libvirt.org
next prev parent reply other threads:[~2020-01-20 19:42 UTC|newest]
Thread overview: 10+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-01-20 17:13 [PATCH v10 0/2] qcow2: add zstd cluster compression Vladimir Sementsov-Ogievskiy
2020-01-20 17:13 ` [PATCH v10 1/2] docs: improve qcow2 spec about extending image header Vladimir Sementsov-Ogievskiy
2020-01-20 19:42 ` Eric Blake [this message]
2020-01-21 16:18 ` Max Reitz
2020-01-31 14:05 ` Vladimir Sementsov-Ogievskiy
2020-01-31 13:55 ` Vladimir Sementsov-Ogievskiy
2020-01-20 17:13 ` [PATCH v10 2/2] docs: qcow2: introduce compression type feature Vladimir Sementsov-Ogievskiy
2020-01-20 19:46 ` Eric Blake
2020-01-21 9:06 ` Vladimir Sementsov-Ogievskiy
2020-01-21 16:20 ` Max Reitz
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=e457c8c4-ae37-9b30-5580-40b34bbf458c@redhat.com \
--to=eblake@redhat.com \
--cc=armbru@redhat.com \
--cc=den@openvz.org \
--cc=dplotnikov@virtuozzo.com \
--cc=kwolf@redhat.com \
--cc=mreitz@redhat.com \
--cc=qemu-block@nongnu.org \
--cc=qemu-devel@nongnu.org \
--cc=vsementsov@virtuozzo.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).