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

[Kevin Wolf]

Am 12.04.2012 23:14, schrieb Anthony Liguori:
> On 04/12/2012 10:01 AM, Kevin Wolf wrote:
>> This updates the qcow2 specification to cover version 3. It contains the
>> following changes:
>>
>> - Added compatible/incompatible/auto-clear feature bits plus an optional
>>    feature name table to allow useful error messages even if an older
>>    version doesn't know some feature at all.
>>
>> - Configurable refcount width. If you don't want to use internal
>>    snapshots, make refcounts one bit and save cache space and I/O.
>>
>> - Zero cluster flags. This allows discard even with a backing file that
>>    doesn't contain zeros. It is also useful for copy-on-read/image
>>    streaming, as you'll want to keep sparseness without accessing the
>>    remote image for an unallocated cluster all the time.
>>
>> - Fixed internal snapshot metadata to use 64 bit VM state size. You
>>    can't save a snapshot of a VM with>= 4 GB RAM today.
>>
>> - Extended internal snapshot metadata to contain the disk size, so that
>>    resizing images that have snapshots can be allowed in the future.
>>
>> Signed-off-by: Kevin Wolf<address@hidden>
>> ---
>>   docs/specs/qcow2.txt |  121 
>> ++++++++++++++++++++++++++++++++++++++++---------
>>   1 files changed, 98 insertions(+), 23 deletions(-)
>>
>> diff --git a/docs/specs/qcow2.txt b/docs/specs/qcow2.txt
>> index b6adcad..00c5696 100644
>> --- a/docs/specs/qcow2.txt
>> +++ b/docs/specs/qcow2.txt
>> @@ -18,7 +18,7 @@ The first cluster of a qcow2 image contains the file 
>> header:
>>                       QCOW magic string ("QFI\xfb")
>>
>>             4 -  7:   version
>> -                    Version number (only valid value is 2)
>> +                    Version number (valid values are 2 and 3)
> 
> Which version will `qemu-img create -f qcow2 foo.img 10G' use?
> 
> It looks like it depends on the compat_level option?  Why not just do `-f 
> qcow3?

Yes, if you want a non-default version, you use qemu-img create -o
compat=0.10/1.1. Otherwise you just get whatever is the default for the
specific qemu version that you're using. My plan was to leave the
default at version 2 for 1.1 and switch to version 3 at 1.2 when it has
matured a bit more.

The change is really not much different from adding an incompatible
feature flag, and you wouldn't change the format name for that, but just
add a switch.

In the code, the only difference is the version number that is written
to the header in bdrv_create, which is exactly what image creation
options are for. And in the user interface, I think users will be glad
that they won't have to change their scripts, update their libvirt etc.

>>
>>             8 - 15:   backing_file_offset
>>                       Offset into the image file at which the backing file 
>> name
>> @@ -67,12 +67,45 @@ 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.
>> +
>> +         72 -  79:  incompatible_features
>> +                    Bitmask of incompatible features. An implementation must
>> +                    fail to open an image if an unknown bit is set.
>> +
>> +                    Bits 0-63:  Reserved (set to 0)
>> +
>> +         80 -  87:  compatible_features
>> +                    Bitmask of compatible features. An implementation can
>> +                    safely ignore any unknown bits that are set.
>> +
>> +                    Bits 0-63:  Reserved (set to 0)
>> +
>> +         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-63:  Reserved (set to 0)
>> +
>> +         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.
> 
> It may be nicer this an order since that way, any value would be valid.  So 
> v2 
> would be assumed to be refcount_order=4.

"any" is rather theoretical as large values don't make any sense.
Especially anything that becomes larger than the cluster size. I guess I
should add an upper boundary of 64 bits/order 6.

But yeah, I'll consider to change it.

Kevin