Re: [Qemu-devel] [PATCH 03/17] spec: add qcow2-dirty-bitmaps specification

2015-10-09 Thread Max Reitz 
On 08.10.2015 22:28, John Snow wrote:

[...]

> (NB: I never got Max's original reply, so this reply is more to Max than
> to Denis or Vladimir.)

Let's hope you'll see this one, then. :-)

> I'll see your wall of text and raise you my own wall of text...
> 
> We consider the ability to use persistent bitmaps to create incremental
> backups for non-qcow2 images to be a necessary and vital component of
> complete incremental backup solution, especially considering the core
> mechanism of the feature does not really rely on qcow2 for anything
> outside of convenience (e.g. backing files.)
> 
> Vladimir's initial proposal of using .qcow2 to store the bitmap sounded
> good to me, because I wanted to be able to store the bitmap in a qcow2
> file anyway, and expanding the specification to allow it to store
> /arbitrary/ bitmaps seemed like a natural fit to accomplish both goals
> with a minimum of coding.
> 
> However, Max has raised some pretty good points here -- allow me to
> paraphrase his Wall Of Text™:
> 
> - Since this patch is a modification of the qcow2 /specification/ which
> is used by more than just QEMU, we must take care to avoid QEMU-isms
> limitations and design a more universal approach to the specification
> addendum.
> 
> - Specific caps on the number of bitmaps, the granularity of said
> bitmaps, and the resultant size of said bitmaps should be addressed in
> terms of the spec, not in terms of what's necessarily convenient or
> sufficient for QEMU. I think this point will be easy to address with
> some better spec wording.
> 
> - The bitmap language in the spec is generic and doesn't refer much to
> anything. This is partially my fault, as I believe I likely guided
> Vladimir towards using generic language that was tied more to the
> HBitmap format than towards our specific implementation
> (BdrvDirtyBitmap.) I recognize this as a bit of a misguided effort on my
> part to keep things "generic," but what I succeeded in doing was keeping
> it "useless" outside of QEMU. Example: "number of virtual bits" is
> meaningless, but "number of 512 byte sectors" is not.

And these are all things that are only a question of the implementation,
so to speak. While it may not be easy writing up the necessary bits for
the specification, I don't think there'll be much discussion on it.

Except maybe the last bit, because "512 byte sector" basically is
meaningless when talking about a qcow2 file (which works in terms of
clusters), but that's where the second part comes in:

> The last bit is the crux of our problem and the most deserving of our
> attention:
> 
> - For a bitmap to be useful to an application outside of QEMU, all of
> the necessary information for interpreting that bitmap must either be
> present within the file or referenced. For bitmaps that describe the
> file they are stored in, this is trivial with some specification editing.
> 
> For bitmaps stored for /other/ files, this gets... trickier. What is
> this a bitmap for? What does it describe? What data does it describe?
> 
> Node-names and drive names here are useless outside of QEMU and can of
> course change between QEMU invocations or be shared between different
> QEMU instances, so this is useless ...
> 
> We could store filenames, but networked devices and distributed
> filesystems may have interesting relative pathnames that will not remain
> reliable once the .qcow2 file is shuffled around or migrated, so storing
> path-name references seems like a losing battle here, too. Maybe we only
> have a file descriptor and no name at all -- what do we write for the
> "global identifier that uniquely identifies the data we belong to"? Is
> it even possible?

I'd be fine with filenames. It works reasonably well for backing files,
and it's basically the same problem there.

Anyway, even if you could describe the image the dirty bitmap is for,
I'd still oppose putting all that into qcow2. Imagine you're writing a
qcow2 interpreting tool and reading the specification, then:

“This field contains the filename of the image this dirty bitmap is for.
This field contains the filename of the clean image. This field contains
the resolution of the dirty bitmap in units of 512 bytes.”

While this may make sense from the perspective of qemu, it doesn't make
any sense from the perspective of qcow2. As said tool writer, you'd be
asking yourself: “OK, so this information is completely useless because
it says nothing about the qcow2 file itself? Actually, it doesn't even
have any connection to this file.”

It's actually not better than a binary data dump without any information
on how to interpret it, then. Because you cannot interpret it, even
though you know how to; if nothing else, that's because you're writing a
qcow2 tool and the other image is very unlikely to be a qcow2 image as well.

> The only conclusion I can reach here is that storing bitmaps inside of a
> .qcow2 that remain meaningful to external applications is not going to
> be easily possible.
>

Re: [Qemu-devel] [PATCH 03/17] spec: add qcow2-dirty-bitmaps specification

2015-10-08 Thread John Snow 


On 10/07/2015 03:05 PM, Denis V. Lunev wrote:
> On 10/07/2015 07:47 PM, Max Reitz wrote:
>> On 05.09.2015 18:43, Vladimir Sementsov-Ogievskiy wrote:
>>> Persistent dirty bitmaps will be saved into qcow2 files. It may be used
>>> as 'internal' bitmaps (for qcow2 drives) or as 'external' bitmaps for
>>> other drives (there may be qcow2 file with zero disk size but with
>>> several dirty bitmaps for other drives).
>>>
>>> Signed-off-by: Vladimir Sementsov-Ogievskiy 
>>> ---
>>>   docs/specs/qcow2.txt | 127
>>> ++-
>>>   1 file changed, 126 insertions(+), 1 deletion(-)
>> Overall: I'm strongly against putting dirty bitmaps into qcow2 files, at
>> least not as it is envisioned by this series.
>>
>>
>> If you don't feel like reading why, and you'd rather read what I'd do if
>> you really, really want to put them into qcow2, files, skip ahead until
>> the "RANT OVER" line.
>>
>>
>> The first indication of why that is the case is that this patch does not
>> add any explanation to the qcow2 specification what these dirty bitmaps
>> are. Therefore, there are basically just binary data that is given a
>> name and dumped into a qcow2 file as if it were a tar file.
>>
>> One could argue that this is qemu and we know what dirty bitmaps are.
>> But qcow2.txt is located in docs/specs/, not just in docs/. It is not an
>> explanation, but a *specification*, and as such it should 
>> explainhttp://www.preining.info/blog/2015/10/looking-at-the-facts-sarah-sharps-crusade/
>> everything related to qcow2.
>>
>> As a side notice, we already have a binary data dump in qcow2 files, and
>> that is the VM state. This is bad enough and if it would have been up to
>> me, it would have never been there. That's because it's something only
>> qemu can make use of, and not even different versions of qemu are
>> compatible there, so it was (in my opinion) a pretty bad idea to put it
>> into qcow2.
>>
>> So what this specification is definitely lacking is an explanation on
>> how any independent program (i.e. *not qemu*) is to interpret the dirty
>> bitmaps. I do believe this is possible, as opposed to the VM state. The
>> VM state, nobody can do anything with it, it's even difficult for qemu
>> itself sometimes.
>>
>> So let's imagine this specification would contain an explanation on what
>> dirty bitmaps are and what they mean. Actually, now that I think about
>> it, I cannot really imagine it, because I'm lacking that explanation.
>> What do they mean? As far as I can see from the series, they actually
>> don't mean anything. It's just a dump of data into a qcow2 file, and it
>> can be any bitmap, be it associated with the file itself or not.
>>
>> This is further pointed to by your feature proposal "Allow qcow2 images
>> without l1_table and other staff but only with dirty bitmaps with
>> minimum overhead". There is a file format for exactly that, and it's
>> called tar (yes, you are missing some metadata, but just add a JSON
>> description file to the archive and you're done).
>>
>> By the way: I heard John briefly touch this in his talk at KVM Forum
>> when he explained that this would make qcow2 files something like better
>> tar files, and I didn't like the idea back then either. I was hoping
>> that it would actually be differently, and was waiting for some
>> discussion to appear, but I didn't notice this series, because it
>> doesn't have "qcow2" in the cover letter's subject (and I wasn't CC'd,
>> but I don't really see why I should have been, as I'm not mentioned in
>> the MAINTAINERS file (what a lucky man I am!)). I only just noticed
>> today when I saw a lone reply from John on qemu-block to a patch with a
>> "qcow2:" prefix.
>>
>> So, what you are apparently planning to do is to dump dirty bitmaps into
>> any available qcow2 file. If the image you are operating on is a qcow2
>> file, great! If it isn't, you create some empty qcow2 file and dump the
>> bitmaps there.
>>
>> Then, I'm asking myself why you don't use tar files in the second case,
>> and then, why you don't use tar files in the first case. I do remember
>> John saying that there was a dicussion about it, but I don't know about
>> it, so I don't know why you dropped that idea in favor of making qcow2
>> files tar archives. The only reason I can think of off the top of my
>> head is that we have infrastructure for reading qcow2 files, but not for
>> tar files. However, this series is like just appending a tar file to a
>> qcow2 file, and then implementing a reader for tar archives inside of
>> the qcow2 driver, so it doesn't seem to be much simpler in practice.
>>
>> In any case, if my assumptions so far are more or less correct, no
>> outside program can do anything with the dirty bitmaps contained in the
>> qcow2 file, because they are just binary data which does not necessarily
>> have any connection to the qcow2 file itself. Not even qemu can make
>> sense of them, it appears, it

Re: [Qemu-devel] [PATCH 03/17] spec: add qcow2-dirty-bitmaps specification

2015-10-08 Thread Denis V. Lunev 

On 10/08/2015 11:28 PM, John Snow wrote:


On 10/07/2015 03:05 PM, Denis V. Lunev wrote:

On 10/07/2015 07:47 PM, Max Reitz wrote:

On 05.09.2015 18:43, Vladimir Sementsov-Ogievskiy wrote:

Persistent dirty bitmaps will be saved into qcow2 files. It may be used
as 'internal' bitmaps (for qcow2 drives) or as 'external' bitmaps for
other drives (there may be qcow2 file with zero disk size but with
several dirty bitmaps for other drives).

Signed-off-by: Vladimir Sementsov-Ogievskiy 
---
   docs/specs/qcow2.txt | 127
++-
   1 file changed, 126 insertions(+), 1 deletion(-)

Overall: I'm strongly against putting dirty bitmaps into qcow2 files, at
least not as it is envisioned by this series.


If you don't feel like reading why, and you'd rather read what I'd do if
you really, really want to put them into qcow2, files, skip ahead until
the "RANT OVER" line.


The first indication of why that is the case is that this patch does not
add any explanation to the qcow2 specification what these dirty bitmaps
are. Therefore, there are basically just binary data that is given a
name and dumped into a qcow2 file as if it were a tar file.

One could argue that this is qemu and we know what dirty bitmaps are.
But qcow2.txt is located in docs/specs/, not just in docs/. It is not an
explanation, but a *specification*, and as such it should 
explainhttp://www.preining.info/blog/2015/10/looking-at-the-facts-sarah-sharps-crusade/
everything related to qcow2.

As a side notice, we already have a binary data dump in qcow2 files, and
that is the VM state. This is bad enough and if it would have been up to
me, it would have never been there. That's because it's something only
qemu can make use of, and not even different versions of qemu are
compatible there, so it was (in my opinion) a pretty bad idea to put it
into qcow2.

So what this specification is definitely lacking is an explanation on
how any independent program (i.e. *not qemu*) is to interpret the dirty
bitmaps. I do believe this is possible, as opposed to the VM state. The
VM state, nobody can do anything with it, it's even difficult for qemu
itself sometimes.

So let's imagine this specification would contain an explanation on what
dirty bitmaps are and what they mean. Actually, now that I think about
it, I cannot really imagine it, because I'm lacking that explanation.
What do they mean? As far as I can see from the series, they actually
don't mean anything. It's just a dump of data into a qcow2 file, and it
can be any bitmap, be it associated with the file itself or not.

This is further pointed to by your feature proposal "Allow qcow2 images
without l1_table and other staff but only with dirty bitmaps with
minimum overhead". There is a file format for exactly that, and it's
called tar (yes, you are missing some metadata, but just add a JSON
description file to the archive and you're done).

By the way: I heard John briefly touch this in his talk at KVM Forum
when he explained that this would make qcow2 files something like better
tar files, and I didn't like the idea back then either. I was hoping
that it would actually be differently, and was waiting for some
discussion to appear, but I didn't notice this series, because it
doesn't have "qcow2" in the cover letter's subject (and I wasn't CC'd,
but I don't really see why I should have been, as I'm not mentioned in
the MAINTAINERS file (what a lucky man I am!)). I only just noticed
today when I saw a lone reply from John on qemu-block to a patch with a
"qcow2:" prefix.

So, what you are apparently planning to do is to dump dirty bitmaps into
any available qcow2 file. If the image you are operating on is a qcow2
file, great! If it isn't, you create some empty qcow2 file and dump the
bitmaps there.

Then, I'm asking myself why you don't use tar files in the second case,
and then, why you don't use tar files in the first case. I do remember
John saying that there was a dicussion about it, but I don't know about
it, so I don't know why you dropped that idea in favor of making qcow2
files tar archives. The only reason I can think of off the top of my
head is that we have infrastructure for reading qcow2 files, but not for
tar files. However, this series is like just appending a tar file to a
qcow2 file, and then implementing a reader for tar archives inside of
the qcow2 driver, so it doesn't seem to be much simpler in practice.

In any case, if my assumptions so far are more or less correct, no
outside program can do anything with the dirty bitmaps contained in the
qcow2 file, because they are just binary data which does not necessarily
have any connection to the qcow2 file itself. Not even qemu can make
sense of them, it appears, it needs the user or the management tool to
do so.

I am strongly against putting binary data into a qcow2 file which does
not have any visible connection to the file's contents.

Obviously, it is possible that there is

Re: [Qemu-devel] [PATCH 03/17] spec: add qcow2-dirty-bitmaps specification

2015-10-07 Thread Denis V. Lunev 

On 10/07/2015 07:47 PM, Max Reitz wrote:

On 05.09.2015 18:43, Vladimir Sementsov-Ogievskiy wrote:

Persistent dirty bitmaps will be saved into qcow2 files. It may be used
as 'internal' bitmaps (for qcow2 drives) or as 'external' bitmaps for
other drives (there may be qcow2 file with zero disk size but with
several dirty bitmaps for other drives).

Signed-off-by: Vladimir Sementsov-Ogievskiy 
---
  docs/specs/qcow2.txt | 127 ++-
  1 file changed, 126 insertions(+), 1 deletion(-)

Overall: I'm strongly against putting dirty bitmaps into qcow2 files, at
least not as it is envisioned by this series.


If you don't feel like reading why, and you'd rather read what I'd do if
you really, really want to put them into qcow2, files, skip ahead until
the "RANT OVER" line.


The first indication of why that is the case is that this patch does not
add any explanation to the qcow2 specification what these dirty bitmaps
are. Therefore, there are basically just binary data that is given a
name and dumped into a qcow2 file as if it were a tar file.

One could argue that this is qemu and we know what dirty bitmaps are.
But qcow2.txt is located in docs/specs/, not just in docs/. It is not an
explanation, but a *specification*, and as such it should explain
everything related to qcow2.

As a side notice, we already have a binary data dump in qcow2 files, and
that is the VM state. This is bad enough and if it would have been up to
me, it would have never been there. That's because it's something only
qemu can make use of, and not even different versions of qemu are
compatible there, so it was (in my opinion) a pretty bad idea to put it
into qcow2.

So what this specification is definitely lacking is an explanation on
how any independent program (i.e. *not qemu*) is to interpret the dirty
bitmaps. I do believe this is possible, as opposed to the VM state. The
VM state, nobody can do anything with it, it's even difficult for qemu
itself sometimes.

So let's imagine this specification would contain an explanation on what
dirty bitmaps are and what they mean. Actually, now that I think about
it, I cannot really imagine it, because I'm lacking that explanation.
What do they mean? As far as I can see from the series, they actually
don't mean anything. It's just a dump of data into a qcow2 file, and it
can be any bitmap, be it associated with the file itself or not.

This is further pointed to by your feature proposal "Allow qcow2 images
without l1_table and other staff but only with dirty bitmaps with
minimum overhead". There is a file format for exactly that, and it's
called tar (yes, you are missing some metadata, but just add a JSON
description file to the archive and you're done).

By the way: I heard John briefly touch this in his talk at KVM Forum
when he explained that this would make qcow2 files something like better
tar files, and I didn't like the idea back then either. I was hoping
that it would actually be differently, and was waiting for some
discussion to appear, but I didn't notice this series, because it
doesn't have "qcow2" in the cover letter's subject (and I wasn't CC'd,
but I don't really see why I should have been, as I'm not mentioned in
the MAINTAINERS file (what a lucky man I am!)). I only just noticed
today when I saw a lone reply from John on qemu-block to a patch with a
"qcow2:" prefix.

So, what you are apparently planning to do is to dump dirty bitmaps into
any available qcow2 file. If the image you are operating on is a qcow2
file, great! If it isn't, you create some empty qcow2 file and dump the
bitmaps there.

Then, I'm asking myself why you don't use tar files in the second case,
and then, why you don't use tar files in the first case. I do remember
John saying that there was a dicussion about it, but I don't know about
it, so I don't know why you dropped that idea in favor of making qcow2
files tar archives. The only reason I can think of off the top of my
head is that we have infrastructure for reading qcow2 files, but not for
tar files. However, this series is like just appending a tar file to a
qcow2 file, and then implementing a reader for tar archives inside of
the qcow2 driver, so it doesn't seem to be much simpler in practice.

In any case, if my assumptions so far are more or less correct, no
outside program can do anything with the dirty bitmaps contained in the
qcow2 file, because they are just binary data which does not necessarily
have any connection to the qcow2 file itself. Not even qemu can make
sense of them, it appears, it needs the user or the management tool to
do so.

I am strongly against putting binary data into a qcow2 file which does
not have any visible connection to the file's contents.

Obviously, it is possible that there is some connection which I am just
not seeing, though.



--- RANT OVER ---

Okay, that was enough destructive criticism, now to get some
constructive arguments and ideas.

So,

Re: [Qemu-devel] [PATCH 03/17] spec: add qcow2-dirty-bitmaps specification

2015-10-07 Thread Max Reitz 
On 05.09.2015 18:43, Vladimir Sementsov-Ogievskiy wrote:
> Persistent dirty bitmaps will be saved into qcow2 files. It may be used
> as 'internal' bitmaps (for qcow2 drives) or as 'external' bitmaps for
> other drives (there may be qcow2 file with zero disk size but with
> several dirty bitmaps for other drives).
> 
> Signed-off-by: Vladimir Sementsov-Ogievskiy 
> ---
>  docs/specs/qcow2.txt | 127 
> ++-
>  1 file changed, 126 insertions(+), 1 deletion(-)

Overall: I'm strongly against putting dirty bitmaps into qcow2 files, at
least not as it is envisioned by this series.


If you don't feel like reading why, and you'd rather read what I'd do if
you really, really want to put them into qcow2, files, skip ahead until
the "RANT OVER" line.


The first indication of why that is the case is that this patch does not
add any explanation to the qcow2 specification what these dirty bitmaps
are. Therefore, there are basically just binary data that is given a
name and dumped into a qcow2 file as if it were a tar file.

One could argue that this is qemu and we know what dirty bitmaps are.
But qcow2.txt is located in docs/specs/, not just in docs/. It is not an
explanation, but a *specification*, and as such it should explain
everything related to qcow2.

As a side notice, we already have a binary data dump in qcow2 files, and
that is the VM state. This is bad enough and if it would have been up to
me, it would have never been there. That's because it's something only
qemu can make use of, and not even different versions of qemu are
compatible there, so it was (in my opinion) a pretty bad idea to put it
into qcow2.

So what this specification is definitely lacking is an explanation on
how any independent program (i.e. *not qemu*) is to interpret the dirty
bitmaps. I do believe this is possible, as opposed to the VM state. The
VM state, nobody can do anything with it, it's even difficult for qemu
itself sometimes.

So let's imagine this specification would contain an explanation on what
dirty bitmaps are and what they mean. Actually, now that I think about
it, I cannot really imagine it, because I'm lacking that explanation.
What do they mean? As far as I can see from the series, they actually
don't mean anything. It's just a dump of data into a qcow2 file, and it
can be any bitmap, be it associated with the file itself or not.

This is further pointed to by your feature proposal "Allow qcow2 images
without l1_table and other staff but only with dirty bitmaps with
minimum overhead". There is a file format for exactly that, and it's
called tar (yes, you are missing some metadata, but just add a JSON
description file to the archive and you're done).

By the way: I heard John briefly touch this in his talk at KVM Forum
when he explained that this would make qcow2 files something like better
tar files, and I didn't like the idea back then either. I was hoping
that it would actually be differently, and was waiting for some
discussion to appear, but I didn't notice this series, because it
doesn't have "qcow2" in the cover letter's subject (and I wasn't CC'd,
but I don't really see why I should have been, as I'm not mentioned in
the MAINTAINERS file (what a lucky man I am!)). I only just noticed
today when I saw a lone reply from John on qemu-block to a patch with a
"qcow2:" prefix.

So, what you are apparently planning to do is to dump dirty bitmaps into
any available qcow2 file. If the image you are operating on is a qcow2
file, great! If it isn't, you create some empty qcow2 file and dump the
bitmaps there.

Then, I'm asking myself why you don't use tar files in the second case,
and then, why you don't use tar files in the first case. I do remember
John saying that there was a dicussion about it, but I don't know about
it, so I don't know why you dropped that idea in favor of making qcow2
files tar archives. The only reason I can think of off the top of my
head is that we have infrastructure for reading qcow2 files, but not for
tar files. However, this series is like just appending a tar file to a
qcow2 file, and then implementing a reader for tar archives inside of
the qcow2 driver, so it doesn't seem to be much simpler in practice.

In any case, if my assumptions so far are more or less correct, no
outside program can do anything with the dirty bitmaps contained in the
qcow2 file, because they are just binary data which does not necessarily
have any connection to the qcow2 file itself. Not even qemu can make
sense of them, it appears, it needs the user or the management tool to
do so.

I am strongly against putting binary data into a qcow2 file which does
not have any visible connection to the file's contents.

Obviously, it is possible that there is some connection which I am just
not seeing, though.



--- RANT OVER ---

Okay, that was enough destructive criticism, now to get some
constructive arguments and ideas.

So, there are two points I

Re: [Qemu-devel] [PATCH 03/17] spec: add qcow2-dirty-bitmaps specification

2015-10-06 Thread John Snow 


On 09/05/2015 01:33 PM, Vladimir Sementsov-Ogievskiy wrote:
> On 05.09.2015 19:43, Vladimir Sementsov-Ogievskiy wrote:
>> Persistent dirty bitmaps will be saved into qcow2 files. It may be used
>> as 'internal' bitmaps (for qcow2 drives) or as 'external' bitmaps for
>> other drives (there may be qcow2 file with zero disk size but with
>> several dirty bitmaps for other drives).
>>
>> Signed-off-by: Vladimir Sementsov-Ogievskiy 
>> ---
>>   docs/specs/qcow2.txt | 127
>> ++-
>>   1 file changed, 126 insertions(+), 1 deletion(-)
>>
>> diff --git a/docs/specs/qcow2.txt b/docs/specs/qcow2.txt
>> index 121dfc8..5fc0365 100644
>> --- a/docs/specs/qcow2.txt
>> +++ b/docs/specs/qcow2.txt
>> @@ -103,7 +103,13 @@ in the description of a field.
>>   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)
>> +Bit 0:  Dirty bitmaps bit. If this bit is set
>> then
>> +there is a _consistent_ Dirty bitmaps
>> extension
>> +in the image. If it is not set, but
>> there is a
>> +Dirty bitmaps extension, its data
>> should be
>> +considered as inconsistent.
>> +
>> +Bits 1-63:  Reserved (set to 0)
>>  96 -  99:  refcount_order
>>   Describes the width of a reference count block
>> entry (width
>> @@ -123,6 +129,7 @@ be stored. Each extension has a structure like the
>> following:
>>   0x - End of the header extension area
>>   0xE2792ACA - Backing file format name
>>   0x6803f857 - Feature name table
>> +0x23852875 - Dirty bitmaps
>>   other  - Unknown header extension, can
>> be safely
>>ignored
>>   @@ -166,6 +173,24 @@ the header extension data. Each entry look like
>> this:
>>   terminated if it has full length)
>> +== Dirty bitmaps ==
>> +
>> +Dirty bitmaps is an optional header extension. It provides an ability
>> to store
>> +dirty bitmaps in a qcow2 image. The fields are:
>> +
>> +  0 -  3:  nb_dirty_bitmaps
>> +   The number of dirty bitmaps contained in the
>> image. Valid
>> +   values: 0 - 65535.
>> +
>> +  4 -  7:  dirty_bitmap_directory_size
>> +   Size of the Dirty Bitmap Directory in bytes. Valid
>> values:
>> +   0 - 67108864 (= 1024 * nb_dirty_bitmaps).
>> +
>> +  8 - 15:  dirty_bitmap_directory_offset
>> +   Offset into the image file at which the Dirty Bitmap
>> +   Directory starts. Must be aligned to a cluster
>> boundary.
>> +
>> +
>>   == Host cluster management ==
>> qcow2 manages the allocation of host clusters by maintaining a
>> reference count
>> @@ -360,3 +385,103 @@ Snapshot table entry:
>> variable:   Padding to round up the snapshot table entry
>> size to the
>>   next multiple of 8.
>> +
>> +
>> +== Dirty bitmaps ==
>> +
>> +The feature supports storing dirty bitmaps in a qcow2 image.
>> +
>> +=== Cluster mapping ===
>> +
>> +Dirty bitmaps are stored using a ONE-level structure for the mapping of
>> +bitmaps to host clusters. It is called Dirty Bitmap Table.
>> +
>> +The Dirty Bitmap Table has a variable size (stored in the Dirty Bitmap
>> +Directory Entry) and may use multiple clusters, however it must be
>> contiguous
>> +in the image file.
>> +
>> +Given an offset (in bytes) into the bitmap, the offset into the image
>> file can
>> +be obtained as follows:
>> +
>> +byte_offset =
>> +dirty_bitmap_table[offset / cluster_size] + (offset %
>> cluster_size)
>> +
>> +Taking into accout the granularity of the bitmap, an offset in bits
>> into the
>> +image file can be obtained like this:
>> +
>> +bit_offset =
>> +byte_offset(bit_nr / granularity / 8) * 8 + (bit_nr /
>> granularity) % 8
>> +
>> +Here bit_nr is a number of "virtual" bit of the bitmap, which is
>> covered by
>> +"physical" bit with number (bit_nr / granularity).
>> +
>> +Dirty Bitmap Table entry:
>> +
>> +Bit  0 -  8:Reserved
>> +
>> + 9 - 55:Bits 9-55 of host cluster offset. Must be aligned
>> to a
>> +cluster boundary. If the offset is 0, the cluster is
>> +unallocated, and should be read as all zeros.
>> +
>> +56 - 63:Reserved
>> +
>> +=== Dirty Bitmap Directory ===
>> +
>> +Each dirty bitmap, saved in the image is described in the Dirty Bitmap
>> +Directory entry. Dirty Bitmap Directory is a contiguous area in the
>> image file,
>> +whose starting offset and

Re: [Qemu-devel] [PATCH 03/17] spec: add qcow2-dirty-bitmaps specification

2015-10-06 Thread Eric Blake 
On 10/06/2015 02:22 PM, John Snow wrote:


>>> +Dirty Bitmap Directory Entry:
>>> +

>>> +
>>> +24 - 27:flags
>>> +Bit
>>> +  0: in_use
>>> + The bitmap is in use and may be inconsistent.
>>> +
>>> +  1: self
>>> + The bitmap is a dirty bitmap for the
>>> containing image.
>>> +
>>> +  2: auto
>>> + The bitmap should be autoloaded as block
>>> dirty bitmap.
>>> + Only available if bit 1 (self) is set.
>>> +
>>> +  3: read_only
>>> + The bitmap should not be rewritten.
>>> +
>>> +Bits 4 - 31 are reserved.
>>
>> Is this appropriate as field, reserved for future extensiion? Or we need
>> an additional one? Do we need scheme like with snapshots? (somthing like
>> field 'additional_area_size', and additional offset of this size after
>> the name)
>>
> 
> I think it would remain appropriate as long as we have a version header
> for the bitmap extension as a whole.

Simply requiring that the bits must be 0 is good enough for now.

> 
> e.g. "Bits 4 - 31 are reserved in qcow2.bitmap.v1 ..."
> 
> If a program that only knows about v1 opens a v2 file and find it
> conforms to spec (does not use the new reserved bits), then it can
> continue along happily.

I don't know that you even have to mention versions of the header, so
much as the blanket statement that any set bit not described by this
version of the spec is either a data corruption or evidence of a newer
version of the spec having edited the file in the meantime.  It works as
long as you require conforming clients to set reserved bits to 0.

> 
> If a reserved bit is set, it's an error and the v1 program must not
> alter the image in case it ruins the consistency of the file.
> 
> The usual suspects (Kevin, Markus, Stefan and Eric) may have better
> suggestions for how to handle future compatibility by drawing upon their
> experience with qcow2.

No, I think we're just fine. If any future spec version requires
additional space, then it can use one of the bits 4-31 as a flag to call
out that space, and older clients will handily refuse to operate on the
file without having to know that the bit meant that the header occupied
more space in the newer version of the spec.

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



signature.asc
Description: OpenPGP digital signature

Re: [Qemu-devel] [PATCH 03/17] spec: add qcow2-dirty-bitmaps specification

2015-10-05 Thread John Snow 


On 09/15/2015 12:24 PM, Eric Blake wrote:
> On 09/05/2015 10:43 AM, Vladimir Sementsov-Ogievskiy wrote:
>> Persistent dirty bitmaps will be saved into qcow2 files. It may be used
>> as 'internal' bitmaps (for qcow2 drives) or as 'external' bitmaps for
>> other drives (there may be qcow2 file with zero disk size but with
>> several dirty bitmaps for other drives).
>>
>> Signed-off-by: Vladimir Sementsov-Ogievskiy 
>> ---
>>  docs/specs/qcow2.txt | 127 
>> ++-
>>  1 file changed, 126 insertions(+), 1 deletion(-)
>>
>> diff --git a/docs/specs/qcow2.txt b/docs/specs/qcow2.txt
>> index 121dfc8..5fc0365 100644
>> --- a/docs/specs/qcow2.txt
>> +++ b/docs/specs/qcow2.txt
>> @@ -103,7 +103,13 @@ in the description of a field.
>>  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)
>> +Bit 0:  Dirty bitmaps bit. If this bit is set then
>> +there is a _consistent_ Dirty bitmaps 
>> extension
>> +in the image. If it is not set, but there 
>> is a
>> +Dirty bitmaps extension, its data should be
>> +considered as inconsistent.
> 
> Thanks for documenting this. I don't know that we use underscore for
> _emphasis_ anywhere else in the file, but I don't have any better
> suggestions.  Should you also require that it is an error if this bit is
> set but no Dirty bitmap extension header is present?
> 

An error, but one that can be safely corrected by any fsck-style
utility: clear the bit.

>> +
>> +Bits 1-63:  Reserved (set to 0)
>>  
>>   96 -  99:  refcount_order
>>  Describes the width of a reference count block entry 
>> (width
>> @@ -123,6 +129,7 @@ be stored. Each extension has a structure like the 
>> following:
>>  0x - End of the header extension area
>>  0xE2792ACA - Backing file format name
>>  0x6803f857 - Feature name table
>> +0x23852875 - Dirty bitmaps
>>  other  - Unknown header extension, can be safely
>>   ignored
>>  
>> @@ -166,6 +173,24 @@ the header extension data. Each entry look like this:
>>  terminated if it has full length)
>>  
>>  
>> +== Dirty bitmaps ==
>> +
>> +Dirty bitmaps is an optional header extension. It provides an ability to 
>> store
>> +dirty bitmaps in a qcow2 image. The fields are:
> 
> Might not hurt to remind the reader about the auto-clear feature bit
> mentioned earlier controlling whether this extension can be trusted as
> consistent.
> 
>> +
>> +  0 -  3:  nb_dirty_bitmaps
>> +   The number of dirty bitmaps contained in the image. Valid
>> +   values: 0 - 65535.
>> +
>> +  4 -  7:  dirty_bitmap_directory_size
>> +   Size of the Dirty Bitmap Directory in bytes. Valid 
>> values:
>> +   0 - 67108864 (= 1024 * nb_dirty_bitmaps).
> 
> Is it always going to be 1024 * nb_dirty_bitmaps? If so, why do we need
> a redundant field?  If not, then this wording needs help; from the rest
> of this text, it looks like you want "at most 1024 * nb_dirty_bitmaps".
>  Also, while Dirty Bitmap Directory entries are variable length (and
> thus a variable maximum), they do have a minimum size (so the minimum
> value for dirty_bitmap_directory_size must be larger than 0 unless
> nb_dirty_bitmaps is 0, in which case why would we have this header
> extension)
> 

Agree.

>> +
>> +  8 - 15:  dirty_bitmap_directory_offset
>> +   Offset into the image file at which the Dirty Bitmap
>> +   Directory starts. Must be aligned to a cluster boundary.
>> +
>> +
>>  == Host cluster management ==
>>  
>>  qcow2 manages the allocation of host clusters by maintaining a reference 
>> count
>> @@ -360,3 +385,103 @@ Snapshot table entry:
>>  
>>  variable:   Padding to round up the snapshot table entry size to the
>>  next multiple of 8.
>> +
>> +
>> +== Dirty bitmaps ==
>> +
>> +The feature supports storing dirty bitmaps in a qcow2 image.
>> +
>> +=== Cluster mapping ===
>> +
>> +Dirty bitmaps are stored using a ONE-level structure for the mapping of
>> +bitmaps to host clusters. It is called Dirty Bitmap Table.
> 
> s/ONE/one/ (I didn't see the reason for the emphasis)
> 

Emphasis is likely because that's not how the cluster allocation
mechanism works in qcow2 otherwise. We're essentially storing data
straight into what would otherwise be the L1 table.

It's worth clarifying, in my opinion.

>> +
>> +The Dirty Bitmap Table has a variable size (stored in

Re: [Qemu-devel] [PATCH 03/17] spec: add qcow2-dirty-bitmaps specification

2015-09-16 Thread Vladimir Sementsov-Ogievskiy 

On 15.09.2015 19:24, Eric Blake wrote:

On 09/05/2015 10:43 AM, Vladimir Sementsov-Ogievskiy wrote:

Persistent dirty bitmaps will be saved into qcow2 files. It may be used
as 'internal' bitmaps (for qcow2 drives) or as 'external' bitmaps for
other drives (there may be qcow2 file with zero disk size but with
several dirty bitmaps for other drives).

Signed-off-by: Vladimir Sementsov-Ogievskiy 
---
  docs/specs/qcow2.txt | 127 ++-
  1 file changed, 126 insertions(+), 1 deletion(-)

diff --git a/docs/specs/qcow2.txt b/docs/specs/qcow2.txt
index 121dfc8..5fc0365 100644
--- a/docs/specs/qcow2.txt
+++ b/docs/specs/qcow2.txt
@@ -103,7 +103,13 @@ in the description of a field.
  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)

+Bit 0:  Dirty bitmaps bit. If this bit is set then
+there is a _consistent_ Dirty bitmaps extension
+in the image. If it is not set, but there is a
+Dirty bitmaps extension, its data should be
+considered as inconsistent.

Thanks for documenting this. I don't know that we use underscore for
_emphasis_ anywhere else in the file, but I don't have any better
suggestions.  Should you also require that it is an error if this bit is
set but no Dirty bitmap extension header is present?


There should be an error, if there are cmd flags which tries to load the 
bitmap. If bitmap loading is not loading, would not a warning be enough?





+
+Bits 1-63:  Reserved (set to 0)
  
   96 -  99:  refcount_order

  Describes the width of a reference count block entry 
(width
@@ -123,6 +129,7 @@ be stored. Each extension has a structure like the 
following:
  0x - End of the header extension area
  0xE2792ACA - Backing file format name
  0x6803f857 - Feature name table
+0x23852875 - Dirty bitmaps
  other  - Unknown header extension, can be safely
   ignored
  
@@ -166,6 +173,24 @@ the header extension data. Each entry look like this:

  terminated if it has full length)
  
  
+== Dirty bitmaps ==

+
+Dirty bitmaps is an optional header extension. It provides an ability to store
+dirty bitmaps in a qcow2 image. The fields are:

Might not hurt to remind the reader about the auto-clear feature bit
mentioned earlier controlling whether this extension can be trusted as
consistent.


agree, will add.




+
+  0 -  3:  nb_dirty_bitmaps
+   The number of dirty bitmaps contained in the image. Valid
+   values: 0 - 65535.
+
+  4 -  7:  dirty_bitmap_directory_size
+   Size of the Dirty Bitmap Directory in bytes. Valid values:
+   0 - 67108864 (= 1024 * nb_dirty_bitmaps).

Is it always going to be 1024 * nb_dirty_bitmaps? If so, why do we need
a redundant field?  If not, then this wording needs help; from the rest
of this text, it looks like you want "at most 1024 * nb_dirty_bitmaps".
  Also, while Dirty Bitmap Directory entries are variable length (and
thus a variable maximum), they do have a minimum size (so the minimum
value for dirty_bitmap_directory_size must be larger than 0 unless
nb_dirty_bitmaps is 0, in which case why would we have this header
extension)


Yes, strange mistake.
actually, it shoud be
<= (round_up_to_8byte_boundary(sizeof(dirty bitmap header) + 
max_dirty_bitmap_name)) * nb_dirty_bitmaps

and
> (round_up_to_8byte_boundary(sizeof(dirty bitmap header) + 
min_dirty_bitmap_name)) * nb_dirty_bitmaps


So, what is better to leave there, these formulas, or take max and min 
of nb_dirty_bitmaps?





+
+  8 - 15:  dirty_bitmap_directory_offset
+   Offset into the image file at which the Dirty Bitmap
+   Directory starts. Must be aligned to a cluster boundary.
+
+
  == Host cluster management ==
  
  qcow2 manages the allocation of host clusters by maintaining a reference count

@@ -360,3 +385,103 @@ Snapshot table entry:
  
  variable:   Padding to round up the snapshot table entry size to the

  next multiple of 8.
+
+
+== Dirty bitmaps ==
+
+The feature supports storing dirty bitmaps in a qcow2 image.
+
+=== Cluster mapping ===
+
+Dirty bitmaps are stored using a ONE-level structure for the mapping of
+bitmaps to host clusters. It is called Dirty Bitmap Table.

s/ONE/one/ (I didn't see the reason for the emphasis)


+
+The Dirty Bitmap Table has a variable size (stored in the Dirty Bitmap

s/The/Each/


+Directory Entry) and may use multiple

Re: [Qemu-devel] [PATCH 03/17] spec: add qcow2-dirty-bitmaps specification

2015-09-15 Thread Eric Blake 
On 09/05/2015 10:43 AM, Vladimir Sementsov-Ogievskiy wrote:
> Persistent dirty bitmaps will be saved into qcow2 files. It may be used
> as 'internal' bitmaps (for qcow2 drives) or as 'external' bitmaps for
> other drives (there may be qcow2 file with zero disk size but with
> several dirty bitmaps for other drives).
> 
> Signed-off-by: Vladimir Sementsov-Ogievskiy 
> ---
>  docs/specs/qcow2.txt | 127 
> ++-
>  1 file changed, 126 insertions(+), 1 deletion(-)
> 
> diff --git a/docs/specs/qcow2.txt b/docs/specs/qcow2.txt
> index 121dfc8..5fc0365 100644
> --- a/docs/specs/qcow2.txt
> +++ b/docs/specs/qcow2.txt
> @@ -103,7 +103,13 @@ in the description of a field.
>  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)
> +Bit 0:  Dirty bitmaps bit. If this bit is set then
> +there is a _consistent_ Dirty bitmaps 
> extension
> +in the image. If it is not set, but there is 
> a
> +Dirty bitmaps extension, its data should be
> +considered as inconsistent.

Thanks for documenting this. I don't know that we use underscore for
_emphasis_ anywhere else in the file, but I don't have any better
suggestions.  Should you also require that it is an error if this bit is
set but no Dirty bitmap extension header is present?

> +
> +Bits 1-63:  Reserved (set to 0)
>  
>   96 -  99:  refcount_order
>  Describes the width of a reference count block entry 
> (width
> @@ -123,6 +129,7 @@ be stored. Each extension has a structure like the 
> following:
>  0x - End of the header extension area
>  0xE2792ACA - Backing file format name
>  0x6803f857 - Feature name table
> +0x23852875 - Dirty bitmaps
>  other  - Unknown header extension, can be safely
>   ignored
>  
> @@ -166,6 +173,24 @@ the header extension data. Each entry look like this:
>  terminated if it has full length)
>  
>  
> +== Dirty bitmaps ==
> +
> +Dirty bitmaps is an optional header extension. It provides an ability to 
> store
> +dirty bitmaps in a qcow2 image. The fields are:

Might not hurt to remind the reader about the auto-clear feature bit
mentioned earlier controlling whether this extension can be trusted as
consistent.

> +
> +  0 -  3:  nb_dirty_bitmaps
> +   The number of dirty bitmaps contained in the image. Valid
> +   values: 0 - 65535.
> +
> +  4 -  7:  dirty_bitmap_directory_size
> +   Size of the Dirty Bitmap Directory in bytes. Valid values:
> +   0 - 67108864 (= 1024 * nb_dirty_bitmaps).

Is it always going to be 1024 * nb_dirty_bitmaps? If so, why do we need
a redundant field?  If not, then this wording needs help; from the rest
of this text, it looks like you want "at most 1024 * nb_dirty_bitmaps".
 Also, while Dirty Bitmap Directory entries are variable length (and
thus a variable maximum), they do have a minimum size (so the minimum
value for dirty_bitmap_directory_size must be larger than 0 unless
nb_dirty_bitmaps is 0, in which case why would we have this header
extension)

> +
> +  8 - 15:  dirty_bitmap_directory_offset
> +   Offset into the image file at which the Dirty Bitmap
> +   Directory starts. Must be aligned to a cluster boundary.
> +
> +
>  == Host cluster management ==
>  
>  qcow2 manages the allocation of host clusters by maintaining a reference 
> count
> @@ -360,3 +385,103 @@ Snapshot table entry:
>  
>  variable:   Padding to round up the snapshot table entry size to the
>  next multiple of 8.
> +
> +
> +== Dirty bitmaps ==
> +
> +The feature supports storing dirty bitmaps in a qcow2 image.
> +
> +=== Cluster mapping ===
> +
> +Dirty bitmaps are stored using a ONE-level structure for the mapping of
> +bitmaps to host clusters. It is called Dirty Bitmap Table.

s/ONE/one/ (I didn't see the reason for the emphasis)

> +
> +The Dirty Bitmap Table has a variable size (stored in the Dirty Bitmap

s/The/Each/

> +Directory Entry) and may use multiple clusters, however it must be contiguous
> +in the image file.
> +
> +Given an offset (in bytes) into the bitmap, the offset into the image file 
> can
> +be obtained as follows:
> +
> +byte_offset =
> +dirty_bitmap_table[offset / cluster_size] + (offset % cluster_size)
> +
> +Taking into accout the granularity of the bitmap, an offset in bits into the

s/accout/account/

> +image file can be obtained like this:
> +
> +

Re: [Qemu-devel] [PATCH 03/17] spec: add qcow2-dirty-bitmaps specification

2015-09-05 Thread Vladimir Sementsov-Ogievskiy 

On 05.09.2015 19:43, Vladimir Sementsov-Ogievskiy wrote:

Persistent dirty bitmaps will be saved into qcow2 files. It may be used
as 'internal' bitmaps (for qcow2 drives) or as 'external' bitmaps for
other drives (there may be qcow2 file with zero disk size but with
several dirty bitmaps for other drives).

Signed-off-by: Vladimir Sementsov-Ogievskiy 
---
  docs/specs/qcow2.txt | 127 ++-
  1 file changed, 126 insertions(+), 1 deletion(-)

diff --git a/docs/specs/qcow2.txt b/docs/specs/qcow2.txt
index 121dfc8..5fc0365 100644
--- a/docs/specs/qcow2.txt
+++ b/docs/specs/qcow2.txt
@@ -103,7 +103,13 @@ in the description of a field.
  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)

+Bit 0:  Dirty bitmaps bit. If this bit is set then
+there is a _consistent_ Dirty bitmaps extension
+in the image. If it is not set, but there is a
+Dirty bitmaps extension, its data should be
+considered as inconsistent.
+
+Bits 1-63:  Reserved (set to 0)
  
   96 -  99:  refcount_order

  Describes the width of a reference count block entry 
(width
@@ -123,6 +129,7 @@ be stored. Each extension has a structure like the 
following:
  0x - End of the header extension area
  0xE2792ACA - Backing file format name
  0x6803f857 - Feature name table
+0x23852875 - Dirty bitmaps
  other  - Unknown header extension, can be safely
   ignored
  
@@ -166,6 +173,24 @@ the header extension data. Each entry look like this:

  terminated if it has full length)
  
  
+== Dirty bitmaps ==

+
+Dirty bitmaps is an optional header extension. It provides an ability to store
+dirty bitmaps in a qcow2 image. The fields are:
+
+  0 -  3:  nb_dirty_bitmaps
+   The number of dirty bitmaps contained in the image. Valid
+   values: 0 - 65535.
+
+  4 -  7:  dirty_bitmap_directory_size
+   Size of the Dirty Bitmap Directory in bytes. Valid values:
+   0 - 67108864 (= 1024 * nb_dirty_bitmaps).
+
+  8 - 15:  dirty_bitmap_directory_offset
+   Offset into the image file at which the Dirty Bitmap
+   Directory starts. Must be aligned to a cluster boundary.
+
+
  == Host cluster management ==
  
  qcow2 manages the allocation of host clusters by maintaining a reference count

@@ -360,3 +385,103 @@ Snapshot table entry:
  
  variable:   Padding to round up the snapshot table entry size to the

  next multiple of 8.
+
+
+== Dirty bitmaps ==
+
+The feature supports storing dirty bitmaps in a qcow2 image.
+
+=== Cluster mapping ===
+
+Dirty bitmaps are stored using a ONE-level structure for the mapping of
+bitmaps to host clusters. It is called Dirty Bitmap Table.
+
+The Dirty Bitmap Table has a variable size (stored in the Dirty Bitmap
+Directory Entry) and may use multiple clusters, however it must be contiguous
+in the image file.
+
+Given an offset (in bytes) into the bitmap, the offset into the image file can
+be obtained as follows:
+
+byte_offset =
+dirty_bitmap_table[offset / cluster_size] + (offset % cluster_size)
+
+Taking into accout the granularity of the bitmap, an offset in bits into the
+image file can be obtained like this:
+
+bit_offset =
+byte_offset(bit_nr / granularity / 8) * 8 + (bit_nr / granularity) % 8
+
+Here bit_nr is a number of "virtual" bit of the bitmap, which is covered by
+"physical" bit with number (bit_nr / granularity).
+
+Dirty Bitmap Table entry:
+
+Bit  0 -  8:Reserved
+
+ 9 - 55:Bits 9-55 of host cluster offset. Must be aligned to a
+cluster boundary. If the offset is 0, the cluster is
+unallocated, and should be read as all zeros.
+
+56 - 63:Reserved
+
+=== Dirty Bitmap Directory ===
+
+Each dirty bitmap, saved in the image is described in the Dirty Bitmap
+Directory entry. Dirty Bitmap Directory is a contiguous area in the image file,
+whose starting offset and length are given by the header extension fields
+dirty_bitmap_directory_offset and dirty_bitmap_directory_size. The entries of
+the bitmap directory have variable length, depending on the length of the
+bitmap name.
+
+Dirty Bitmap Directory Entry:
+
+Byte 0 -  7:dirty_bitmap_table_offset
+Offset into the image file at which the Dirty Bitmap Table
+for the bitmap starts. Must be

[Qemu-devel] [PATCH 03/17] spec: add qcow2-dirty-bitmaps specification

2015-09-05 Thread Vladimir Sementsov-Ogievskiy 
Persistent dirty bitmaps will be saved into qcow2 files. It may be used
as 'internal' bitmaps (for qcow2 drives) or as 'external' bitmaps for
other drives (there may be qcow2 file with zero disk size but with
several dirty bitmaps for other drives).

Signed-off-by: Vladimir Sementsov-Ogievskiy 
---
 docs/specs/qcow2.txt | 127 ++-
 1 file changed, 126 insertions(+), 1 deletion(-)

diff --git a/docs/specs/qcow2.txt b/docs/specs/qcow2.txt
index 121dfc8..5fc0365 100644
--- a/docs/specs/qcow2.txt
+++ b/docs/specs/qcow2.txt
@@ -103,7 +103,13 @@ in the description of a field.
 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)
+Bit 0:  Dirty bitmaps bit. If this bit is set then
+there is a _consistent_ Dirty bitmaps extension
+in the image. If it is not set, but there is a
+Dirty bitmaps extension, its data should be
+considered as inconsistent.
+
+Bits 1-63:  Reserved (set to 0)
 
  96 -  99:  refcount_order
 Describes the width of a reference count block entry (width
@@ -123,6 +129,7 @@ be stored. Each extension has a structure like the 
following:
 0x - End of the header extension area
 0xE2792ACA - Backing file format name
 0x6803f857 - Feature name table
+0x23852875 - Dirty bitmaps
 other  - Unknown header extension, can be safely
  ignored
 
@@ -166,6 +173,24 @@ the header extension data. Each entry look like this:
 terminated if it has full length)
 
 
+== Dirty bitmaps ==
+
+Dirty bitmaps is an optional header extension. It provides an ability to store
+dirty bitmaps in a qcow2 image. The fields are:
+
+  0 -  3:  nb_dirty_bitmaps
+   The number of dirty bitmaps contained in the image. Valid
+   values: 0 - 65535.
+
+  4 -  7:  dirty_bitmap_directory_size
+   Size of the Dirty Bitmap Directory in bytes. Valid values:
+   0 - 67108864 (= 1024 * nb_dirty_bitmaps).
+
+  8 - 15:  dirty_bitmap_directory_offset
+   Offset into the image file at which the Dirty Bitmap
+   Directory starts. Must be aligned to a cluster boundary.
+
+
 == Host cluster management ==
 
 qcow2 manages the allocation of host clusters by maintaining a reference count
@@ -360,3 +385,103 @@ Snapshot table entry:
 
 variable:   Padding to round up the snapshot table entry size to the
 next multiple of 8.
+
+
+== Dirty bitmaps ==
+
+The feature supports storing dirty bitmaps in a qcow2 image.
+
+=== Cluster mapping ===
+
+Dirty bitmaps are stored using a ONE-level structure for the mapping of
+bitmaps to host clusters. It is called Dirty Bitmap Table.
+
+The Dirty Bitmap Table has a variable size (stored in the Dirty Bitmap
+Directory Entry) and may use multiple clusters, however it must be contiguous
+in the image file.
+
+Given an offset (in bytes) into the bitmap, the offset into the image file can
+be obtained as follows:
+
+byte_offset =
+dirty_bitmap_table[offset / cluster_size] + (offset % cluster_size)
+
+Taking into accout the granularity of the bitmap, an offset in bits into the
+image file can be obtained like this:
+
+bit_offset =
+byte_offset(bit_nr / granularity / 8) * 8 + (bit_nr / granularity) % 8
+
+Here bit_nr is a number of "virtual" bit of the bitmap, which is covered by
+"physical" bit with number (bit_nr / granularity).
+
+Dirty Bitmap Table entry:
+
+Bit  0 -  8:Reserved
+
+ 9 - 55:Bits 9-55 of host cluster offset. Must be aligned to a
+cluster boundary. If the offset is 0, the cluster is
+unallocated, and should be read as all zeros.
+
+56 - 63:Reserved
+
+=== Dirty Bitmap Directory ===
+
+Each dirty bitmap, saved in the image is described in the Dirty Bitmap
+Directory entry. Dirty Bitmap Directory is a contiguous area in the image file,
+whose starting offset and length are given by the header extension fields
+dirty_bitmap_directory_offset and dirty_bitmap_directory_size. The entries of
+the bitmap directory have variable length, depending on the length of the
+bitmap name.
+
+Dirty Bitmap Directory Entry:
+
+Byte 0 -  7:dirty_bitmap_table_offset
+Offset into the image file at which the Dirty Bitmap Table
+for the bitmap starts. Must be aligned to a cluster
+boundary.
+
+ 8 - 15: