Re: [Qemu-block] [Qemu-devel] [PATCH v11 2/3] qemu-img info lists bitmap directory entries

[Vladimir Sementsov-Ogievskiy]

01.02.2019 21:39, Markus Armbruster wrote:
> Andrey Shinkevich <address@hidden> writes:
> 
>> In the 'Format specific information' section of the 'qemu-img info'
>> command output, the supplemental information about existing QCOW2
>> bitmaps will be shown, such as a bitmap name, flags and granularity:
>>
>> image: /vz/vmprivate/VM1/harddisk.hdd
>> file format: qcow2
>> virtual size: 64G (68719476736 bytes)
>> disk size: 3.0M
>> cluster_size: 1048576
>> Format specific information:
>>      compat: 1.1
>>      lazy refcounts: true
>>      bitmaps:
>>          [0]:
>>              flags:
>>                  [0]: in-use
>>                  [1]: auto
>>              name: back-up1
>>              unknown flags: 4
>>              granularity: 65536
>>          [1]:
>>              flags:
>>                  [0]: in-use
>>                  [1]: auto
>>              name: back-up2
>>              unknown flags: 8
>>              granularity: 65536
>>      refcount bits: 16
>>      corrupt: false
>>
>> Signed-off-by: Andrey Shinkevich <address@hidden>
>> ---
> [...]
>> diff --git a/qapi/block-core.json b/qapi/block-core.json
>> index 91685be..271e0df 100644
>> --- a/qapi/block-core.json
>> +++ b/qapi/block-core.json
>> @@ -69,6 +69,8 @@
>>   # @encrypt: details about encryption parameters; only set if image
>>   #           is encrypted (since 2.10)
>>   #
>> +# @bitmaps: A list of qcow2 bitmap details (since 4.0)
>> +#
>>   # Since: 1.7
>>   ##
>>   { 'struct': 'ImageInfoSpecificQCow2',
>> @@ -77,7 +79,8 @@
>>         '*lazy-refcounts': 'bool',
>>         '*corrupt': 'bool',
>>         'refcount-bits': 'int',
>> -      '*encrypt': 'ImageInfoSpecificQCow2Encryption'
>> +      '*encrypt': 'ImageInfoSpecificQCow2Encryption',
>> +      '*bitmaps': ['Qcow2BitmapInfo']
>>     } }
>>   
>>   ##
>> @@ -454,6 +457,41 @@
>>              'status': 'DirtyBitmapStatus'} }
>>   
>>   ##
>> +# @Qcow2BitmapInfoFlags:
>> +#
>> +# An enumeration of flags that a bitmap can report to the user.
>> +#
>> +# @in-use: The bitmap was not saved correctly and may be inconsistent.
> 
> I doubt the casual reader could guess the meaning from the name.  What
> about @dirty?

I'd prefer to keep it matching Qcow2 format specification. This Info aims
to export qcow2 specifics as is. And Qcow2 spec is not something qemu-internal,
why is it worse than QQPI, and why to have different name for the same thing
in different parts of spec?

We may instead rephrase it like

The bitmap is possibly in use by other process or was not saved correctly (and
therefore this flag was not cleared). The data of the bitmap may be 
inconsistent.

to reflect in-use name of the flag..


And, if we change it to @dirty, we at least should add a comment that this field
matches IN_USE flag of qcow2 format.

> 
>> +#
>> +# @auto: The bitmap must reflect all changes of the virtual disk by any
>> +#        application that would write to this qcow2 file.
>> +#
>> +# Since: 4.0
>> +##
>> +{ 'enum': 'Qcow2BitmapInfoFlags',
>> +  'data': ['in-use', 'auto'] }
>> +
>> +##
>> +# @Qcow2BitmapInfo:
>> +#
>> +# Qcow2 bitmap information.
>> +#
>> +# @name: the name of the bitmap
>> +#
>> +# @granularity: granularity of the bitmap in bytes
>> +#
>> +# @flags: recognized flags of the bitmap
>> +#
>> +# @unknown-flags: any remaining flags not recognized by the current qemu 
>> version
> 
> Intended use cases for @unknown-flags?
> 
>> +#
>> +# Since: 4.0
>> +##
>> +{ 'struct': 'Qcow2BitmapInfo',
>> +  'data': {'name': 'str', 'granularity': 'uint32',
>> +           'flags': ['Qcow2BitmapInfoFlags'],
>> +           '*unknown-flags': 'uint32' } }
>> +
>> +##
>>   # @BlockLatencyHistogramInfo:
>>   #
>>   # Block latency histogram.


-- 
Best regards,
Vladimir