Re: [Qemu-block] [PATCH v2 1/4] docs/interop/qcow2: Improve bitmap flag in_use specification

[Vladimir Sementsov-Ogievskiy]

On 12.03.2019 3:00, Eric Blake wrote:
> On 3/11/19 1:51 PM, Vladimir Sementsov-Ogievskiy wrote:
>> We already use (we didn't notice it) IN_USE flag for marking bitmap
>> metadata outdated, such as AUTO flag, which mirrors enabled/disabled
>> bitmaps. No we are going to support bitmap resize, so it's good to
> 
> s/No/Now/
> 
>> write IN_USE meaning with more details.
>>
>> Signed-off-by: Vladimir Sementsov-Ogievskiy <address@hidden>
>> ---
>>   docs/interop/qcow2.txt | 18 +++++++++++++++---
>>   1 file changed, 15 insertions(+), 3 deletions(-)
>>
>> diff --git a/docs/interop/qcow2.txt b/docs/interop/qcow2.txt
>> index fb5cb47245..575a5f25e2 100644
>> --- a/docs/interop/qcow2.txt
>> +++ b/docs/interop/qcow2.txt
>> @@ -589,7 +589,19 @@ Structure of a bitmap directory entry:
>>                       Bit
>>                         0: in_use
>>                            The bitmap was not saved correctly and may be
>> -                         inconsistent.
>> +                         inconsistent. This inconsitency may touch both 
>> bitmap
> 
> inconsistency
> 
>> +                         data and metadata, and this mean that bitmap state
>> +                         (its data and metadata) was changed but not stored
>> +                         back to the image. This flag doesn't relate to 
>> format
>> +                         corruption, all fields are still correct from qcow2
>> +                         point of view, they just may be outdated.
>> +
>> +                         Note: Currently, Qemu may change (additionally to
>> +                         bitmap data) @auto flag and size of the bitmap 
>> during
>> +                         image resize. This mean, that not only bitmap data
>> +                         may be outdated if @in_use flag set, but also 
>> value of
>> +                         @auto flag and bitmap size (which is indirectly
>> +                         referenced by @bitmap_table_size).
> 
> Feels wordy. Maybe drop the second paragraph starting with Note, and
> merely use this for the first paragraph:
> 
> The bitmap was not saved correctly and may be inconsistent. Although the
> bitmap metadata is still well-formed from a qcow2 perspective, the
> metadata (such as the auto flag or bitmap size) or data contents may be
> outdated.

Sounds good (as always), thanks)

> 
>>   
>>                         1: auto
>>                            The bitmap must reflect all changes of the virtual
>> @@ -717,8 +729,8 @@ corresponding range of the virtual disk (see above) was 
>> written to while the
>>   bitmap was 'enabled'. An unset bit means that this range was not written 
>> to.
>>   
>>   The software doesn't have to sync the bitmap in the image file with its
>> -representation in RAM after each write. Flag 'in_use' should be set while 
>> the
>> -bitmap is not synced.
>> +representation in RAM after each write or metadata change. Flag 'in_use'
>> +should be set while the bitmap is not synced.
>>   
>>   In the image file the 'enabled' state is reflected by the 'auto' flag. If 
>> this
>>   flag is set, the software must consider the bitmap as 'enabled' and start
>>
>