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

[Eric Blake]

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.

>  
>                        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
> 

-- 
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3226
Virtualization:  qemu.org | libvirt.org

signature.asc
Description: OpenPGP digital signature