mirrors/qemu
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: improve qcow2 spec about extending image header

Browse Source 
Make it more obvious how to add new fields to the version 3 header and
how to interpret them.

The specification is adjusted so that 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 of
   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>
Reviewed-by: Eric Blake <eblake@redhat.com>
Message-Id: <20200131142219.3264-2-vsementsov@virtuozzo.com>
Reviewed-by: Alberto Garcia <berto@igalia.com>
[mreitz: s/some its/some of its/]
Signed-off-by: Max Reitz <mreitz@redhat.com>
This commit is contained in:
Vladimir Sementsov-Ogievskiy 2020-01-31 17:22:18 +03:00 committed by Max Reitz
parent 672f9d0df1
commit 3ae3fcfae5
1 changed files with 42 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

45
docs/interop/qcow2.txt
View File

@ -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,45 @@ 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
to set field B, but does not care about field A which precedes B. More
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 than or equal
to the 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
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: