Re: [Qemu-devel] [RFC PATCH 01/16] Specification for qcow2 version 3

[Eric Blake <eblake@redhat.com>]

[-- Attachment #1: Type: text/plain, Size: 4231 bytes --]

On 03/27/2012 09:03 AM, Kevin Wolf wrote:
> This is the second draft for what I think could be added when we increase qcow2's
> version number to 3. This includes points that have been made by several people
> over the past few months. We're probably not going to implement this next week,
> but I think it's important to get discussions started early, so here it is.
> 

> +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.
> +
> +         72 -  79:  incompatible_features
> +                    Bitmask of incompatible features. An implementation must
> +                    fail to open an image if an unknown bit is set.
> +
> +                    Bit 0:      The reference counts in the image file may be
> +                                inaccurate. Implementations must check/rebuild
> +                                them if they rely on them.
> +
> +                    Bit 1:      Enable subclusters. This affects the L2 table
> +                                format.
> +
> +                    Bits 2-31:  Reserved (set to 0)

Offsets 72-79 forms 8 bytes, so this should be bits 2-63 are reserved.

> +
> +         80 -  87:  compatible_features
> +                    Bitmask of compatible features. An implementation can
> +                    safely ignore any unknown bits that are set.
> +
> +                    Bits 0-31:  Reserved (set to 0)

Again, bits 0-63, based on offsets.

> +
> +         88 -  95:  autoclear_features
> +                    Bitmask of auto-clear features. An implementation may only
> +                    write to an image with unknown auto-clear features if it
> +                    clears the respective bits from this field first.
> +
> +                    Bits 0-31:  Reserved (set to 0)

And again.

> +
> +         96 -  99:  refcount_bits
> +                    Size of a reference count block entry in bits. For version 2
> +                    images, the size is always assumed to be 16 bits. The size
> +                    must be a power of two.
> +                    [ TODO: Define order in sub-byte sizes ]
> +
> +        100 - 103:  header_length
> +                    Length of the header structure in bytes. For version 2
> +                    images, the length is always assumed to be 72 bytes.

Might be a good idea to require this to be a multiple of 8, since both
72 and 104 qualify, and since header extensions are also required to be
padded out to multiples of 8.

> +== Feature name table ==
> +
> +A feature name table is an optional header extension that contains the name for
> +features used by the image. It can be used by applications that don't know
> +the respective feature (e.g. because the feature was introduced only later) to
> +display a useful error message.
> +
> +The number of entries in the feature name table is determined by the length of
> +the header extension data. Its entries look like this:
> +
> +    Byte       0:   Type of feature (select feature bitmap)
> +                        0: Incompatible feature
> +                        1: Compatible feature
> +                        2: Autoclear feature
> +
> +               1:   Bit number within the selected feature bitmap
> +
> +          2 - 47:   Feature name (padded with zeros, but not necessarily null
> +                    terminated if it has full length)

Semantic nit: The NUL character is all zeros; it is one byte in all
unibyte and multi-byte encodings, and the NUL wide character is the
all-zero wchar_t value; while 'null' refers to a pointer to nowhere.
Saying a string is null terminated is wrong, because you don't have a 4-
or 8-byte NULL pointer at the end of the string, just a one-byte NUL
character.  Therefore, strings are nul-terminated, not null-terminated.

Is this extension capped at 48 bytes, or it is a repeating table of as
many 48-byte multiples as necessary to represent each feature name?

-- 
Eric Blake   eblake@redhat.com    +1-919-301-3266
Libvirt virtualization library http://libvirt.org


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 620 bytes --]