spec: add qcow2 bitmaps extension specification
PATCH v6 1/1 spec: add qcow2 bitmaps extension specification
The new feature for qcow2: storing bitmaps.
This patch adds new header extension to qcow2 - Bitmaps Extension. It provides an ability to store virtual disk related bitmaps in a qcow2 image. For now there is only one type of such bitmaps: Dirty Tracking Bitmap, which just tracks virtual disk changes from some moment.
Note: Only bitmaps, relative to the virtual disk, stored in qcow2 file, should be stored in this qcow2 file. The size of each bitmap (considering its granularity) is equal to virtual disk size.
---
v6:
- reword bitmap_directory_size description
- bitmap type: make 0 reserved
- extra_data_size: resize to 4bytes
Also, I've marked this field as "must be zero". We can always change it, if we decide allowing managing app to specify any extra data, by defining some magic value as a top of user extra data.. So, for now non zeor extra_data_size should be considered as an error.
- swap name and extra_data to give good alignment to extra_data.
v5:
- 'Dirty bitmaps' renamed to 'Bitmaps', as we may have several types of bitmaps.
- rewordings
- move upper bounds to "Notes about Qemu limits"
- s/should/must somewhere. (but not everywhere)
- move name_size field closer to name itself in bitmap header
- add extra data area to bitmap header
- move bitmap data description to separate section
docs/specs/qcow2.txt | 161 ++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 160 insertions(+), 1 deletion(-)
docs/specs/qcow2.txt +160 -1
@@ -103,7 +103,19 @@ 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: Bitmaps extension bit. + This bit is responsible for Bitmaps extension + consistency. + + If it is set, but there is no Bitmaps + extension, this should be considered as an + error. + + If it is not set, but there is a 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 +135,7 @@ be stored. Each extension has a structure like the following: 0x00000000 - End of the header extension area 0xE2792ACA - Backing file format name 0x6803f857 - Feature name table + 0x23852875 - Bitmaps extension other - Unknown header extension, can be safely ignored
@@ -166,6 +179,34 @@ the header extension data. Each entry look like this: terminated if it has full length) +== Bitmaps extension == + +Bitmaps extension is an optional header extension. It provides an ability to +store virtual disk related bitmaps in a qcow2 image. For now there is only one +type of such bitmaps: Dirty Tracking Bitmap, which just tracks virtual disk +changes from some moment. + +The data of the extension should be considered as consistent only if +corresponding auto-clear feature bit is set (see autoclear_features above). + +The fields of Bitmaps extension are: + + 0 - 3: nb_bitmaps + The number of bitmaps contained in the image. Must be + greater or equal to 1. + + Note: Qemu currently only supports up to 65535 bitmaps per + image. + + 4 - 7: bitmap_directory_size + Size of the Bitmap Directory in bytes. It is a cumulative + size of all (nb_bitmaps) bitmap headers. + + 8 - 15: bitmap_directory_offset + Offset into the image file at which the 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 +401,121 @@ Snapshot table entry: variable: Padding to round up the snapshot table entry size to the next multiple of 8. + + +== Bitmaps == + +The feature supports storing bitmaps in a qcow2 image. All bitmaps are related +to the virtual disk, stored in this image. + +=== Bitmap Directory === + +Each bitmap saved in the image is described in a Bitmap Directory entry. Bitmap +Directory is a contiguous area in the image file, whose starting offset and +length are given by the header extension fields bitmap_directory_offset and +bitmap_directory_size. The entries of the bitmap directory have variable +length, depending on the length of the bitmap name and extra data. These +entries are also called bitmap headers. + +Bitmap Directory Entry: + + Byte 0 - 7: bitmap_table_offset + Offset into the image file at which the Bitmap Table + (described below) for the bitmap starts. Must be aligned to + a cluster boundary. + + 8 - 11: bitmap_table_size + Number of entries in the Bitmap Table of the bitmap. + + 12 - 15: flags + Bit + 0: in_use + The bitmap was not saved correctly and may be + inconsistent. + + 1: auto + The bitmap must reflect all changes of the virtual + disk by any application that would write to this qcow2 + file (including writes, snapshot switching, etc.). The + type of this bitmap must be 'Dirty Tracking Bitmap'. + + Bits 2 - 31 are reserved and must be 0. + + 16: type + This field describes the sort of the bitmap. + Values: + 1: Dirty Tracking Bitmap + + Values 0, 2 - 255 are reserved. + + 17: granularity_bits + Granularity bits. Valid values are: 0 - 63. + + Note: Qemu currently doesn't support granularity_bits + greater than 31. + + Granularity is calculated as + granularity = 1 << granularity_bits + + Granularity of the bitmap is how many bytes of the image + accounts for one bit of the bitmap. + + 18 - 19: name_size + Size of the bitmap name. Valid values: 1 - 1023. + + 20 - 23: extra_data_size + Size of type-specific extra data. + + For now, as no extra data is defined, extra_data_size is + reserved and must be zero. + + variable: Type-specific extra data for the bitmap. + + variable: The name of the bitmap (not null terminated). Must be + unique among all bitmap names within the Bitmaps extension. + + variable: Padding to round up the Bitmap Directory Entry size to the + next multiple of 8. + +=== Bitmap Table === + +Bitmaps are stored using a one-level (not two-level like refcounts and guest +clusters mapping) structure for the mapping of bitmaps data to host clusters. +It is called Bitmap Table. + +Each Bitmap Table has a variable size (stored in the Bitmap Directory Entry) +and may use multiple clusters, however it must be contiguous in the image file. + +Bitmap Table entry: + + Bit 0: Reserved and must be zero if bits 9 - 55 are non-zero. + If bits 9 - 55 are zero: + 0: Cluster should be read as all zeros. + 1: Cluster should be read as all ones. + + 1 - 8: Reserved and must be zero. + + 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, see bit 0 description. + + 56 - 63: Reserved and must be zero. + +=== Bitmap Data === + +As noted above, bitmap data is stored in several (or may be one, exactly +bitmap_table_size) separate clusters, described by Bitmap Table. Given an +offset (in bytes) into the bitmap data, the offset into the image file can be +obtained as follows: + + image_offset = + bitmap_table[bitmap_data_offset / cluster_size] + + (bitmap_data_offset % cluster_size) + +Taking into account the granularity of the bitmap, an offset in bits into the +image file, corresponding to byte number byte_nr of the virtual disk can be +calculated like this: + + bit_offset = + image_offset(byte_nr / granularity / 8) * 8 + + (byte_nr / granularity) % 8
Signature · 1 line
2.1.4
Quoted 7 lines · Vladimir Sementsov-Ogievskiy
The new feature for qcow2: storing bitmaps.
This patch adds new header extension to qcow2 - Bitmaps Extension. It provides an ability to store virtual disk related bitmaps in a qcow2 image. For now there is only one type of such bitmaps: Dirty Tracking Bitmap, which just tracks virtual disk changes from some moment.
Quoted 5 lines
Note: Only bitmaps, relative to the virtual disk, stored in qcow2 file, should be stored in this qcow2 file. The size of each bitmap (considering its granularity) is equal to virtual disk size.
Signed-off-by Vladimir Sementsov-Ogievskiy <[email protected]>
I see some issues regarding grammar and phrasing, but I still think nagging about that should be left to native speakers and for the non-RFC versions.
(Or someone can just fix it up on top.)
Thanks!
Quoted 8 lines · Max Reitz
Quoted 7 lines · Vladimir Sementsov-Ogievskiy
The new feature for qcow2: storing bitmaps.
This patch adds new header extension to qcow2 - Bitmaps Extension. It provides an ability to store virtual disk related bitmaps in a qcow2 image. For now there is only one type of such bitmaps: Dirty Tracking Bitmap, which just tracks virtual disk changes from some moment.
Quoted 8 lines
Quoted 5 lines
Note: Only bitmaps, relative to the virtual disk, stored in qcow2 file, should be stored in this qcow2 file. The size of each bitmap (considering its granularity) is equal to virtual disk size.
Signed-off-by Vladimir Sementsov-Ogievskiy <[email protected]>I see some issues regarding grammar and phrasing, but I still think nagging about that should be left to native speakers and for the non-RFC versions.
I've already removed 'RFC' mark)
Quoted 6 lines
(Or someone can just fix it up on top.)
Semantically-reviewed-by Max Reitz <[email protected]>Thanks!
Signature · 3 lines
Best regards, Vladimir * now, @virtuozzo.com instead of @parallels.com. Sorry for this inconvenience.
Quoted 16 lines · Vladimir Sementsov-Ogievskiy
The new feature for qcow2: storing bitmaps.
This patch adds new header extension to qcow2 - Bitmaps Extension. It provides an ability to store virtual disk related bitmaps in a qcow2 image. For now there is only one type of such bitmaps: Dirty Tracking Bitmap, which just tracks virtual disk changes from some moment.
Note: Only bitmaps, relative to the virtual disk, stored in qcow2 file, should be stored in this qcow2 file. The size of each bitmap (considering its granularity) is equal to virtual disk size.
Signed-off-by Vladimir Sementsov-Ogievskiy <[email protected]>---
docs/specs/qcow2.txt the header extension data. Each entry look like this: · line 187
Quoted 9 lines
docs/specs/qcow2.txt +6
-0@@ -166,6 +179,34 @@ the header extension data. Each entry look like this: terminated if it has full length) +== Bitmaps extension == + +Bitmaps extension is an optional header extension. It provides an ability to +store virtual disk related bitmaps in a qcow2 image. For now there is only one +type of such bitmaps: Dirty Tracking Bitmap, which just tracks virtual disk +changes from some moment.
This is already the qcow2 spec, so 'in a qcow2 image' may be redundant.
Possible idea for nicer grammar:
It provides the ability to store bitmaps related to a virtual disk. For now, there is only one bitmap type: Dirty Tracking Bitmap, which tracks virtual disk changes from some moment.
docs/specs/qcow2.txt Snapshot table entry: · line 452
Quoted 2 lines
docs/specs/qcow2.txt +2
-0+ 17: granularity_bits + Granularity bits. Valid values are: 0 - 63.
Elsewhere, the file has 'valid values: 0-63'; dropping 'are' would make this more consistent.
docs/specs/qcow2.txt Snapshot table entry: · line 464
Quoted 12 lines
docs/specs/qcow2.txt +12
-0+ + Note: Qemu currently doesn't support granularity_bits + greater than 31. + + Granularity is calculated as + granularity = 1 << granularity_bits + + Granularity of the bitmap is how many bytes of the image + accounts for one bit of the bitmap. + + 18 - 19: name_size + Size of the bitmap name. Valid values: 1 - 1023.
Should this be more like:
Must be non-zero. Note: Qemu currently doesn't support values greater than 1023.
docs/specs/qcow2.txt Snapshot table entry:
Quoted 4 lines
docs/specs/qcow2.txt +4
-0+=== Bitmap Data === + +As noted above, bitmap data is stored in several (or may be one, exactly +bitmap_table_size) separate clusters, described by Bitmap Table.
bitmap_table_size was documented as "Number of entries in the Bitmap Table of the bitmap", where each entry is 8 bytes. But this sounds like bitmap_table_size == 1 implies that the table is exactly 1 cluster (at least 512 bytes). I think you are trying to imply that the bitmap data occupies ceil(cluster size / 8 / bitmap_tablesize) clusters.
I also wonder if you need more text to cover what happens when the number of entries does not end on a cluster boundary. Must the remaining bits of the cluster containing the tail of the Bitmap be set to all 0, or is it garbage that must be ignored regardless of content?
Signature · 2 lines
Eric Blake eblake redhat com +1-919-301-3266 Libvirt virtualization library http://libvirt.org
Quoted 55 lines · Eric Blake
Quoted 15 lines · Vladimir Sementsov-Ogievskiy
The new feature for qcow2: storing bitmaps.
This patch adds new header extension to qcow2 - Bitmaps Extension. It provides an ability to store virtual disk related bitmaps in a qcow2 image. For now there is only one type of such bitmaps: Dirty Tracking Bitmap, which just tracks virtual disk changes from some moment.
Note: Only bitmaps, relative to the virtual disk, stored in qcow2 file, should be stored in this qcow2 file. The size of each bitmap (considering its granularity) is equal to virtual disk size.
Signed-off-by Vladimir Sementsov-Ogievskiy <[email protected]>---
docs/specs/qcow2.txt the header extension data. Each entry look like this: · line 187
Quoted 9 lines
docs/specs/qcow2.txt +6
-0@@ -166,6 +179,34 @@ the header extension data. Each entry look like this: terminated if it has full length) +== Bitmaps extension == + +Bitmaps extension is an optional header extension. It provides an ability to +store virtual disk related bitmaps in a qcow2 image. For now there is only one +type of such bitmaps: Dirty Tracking Bitmap, which just tracks virtual disk +changes from some moment.This is already the qcow2 spec, so 'in a qcow2 image' may be redundant.
Possible idea for nicer grammar:It provides the ability to store bitmaps related to a virtual disk. For now, there is only one bitmap type: Dirty Tracking Bitmap, which tracks virtual disk changes from some moment.
docs/specs/qcow2.txt Snapshot table entry: · line 452
Quoted 2 lines
docs/specs/qcow2.txt +2
-0+ 17: granularity_bits + Granularity bits. Valid values are: 0 - 63.Elsewhere, the file has 'valid values: 0-63'; dropping 'are' would make this more consistent.
docs/specs/qcow2.txt Snapshot table entry: · line 464
Quoted 12 lines
docs/specs/qcow2.txt +12
-0+ + Note: Qemu currently doesn't support granularity_bits + greater than 31. + + Granularity is calculated as + granularity = 1 << granularity_bits + + Granularity of the bitmap is how many bytes of the image + accounts for one bit of the bitmap. + + 18 - 19: name_size + Size of the bitmap name. Valid values: 1 - 1023.Should this be more like:
Must be non-zero. Note: Qemu currently doesn't support values greater than 1023.
Quoted 9 lines
docs/specs/qcow2.txt Snapshot table entry:
Quoted 4 lines
docs/specs/qcow2.txt +4
-0+=== Bitmap Data === + +As noted above, bitmap data is stored in several (or may be one, exactly +bitmap_table_size) separate clusters, described by Bitmap Table.
bitmap_table_sizewas documented as "Number of entries in the Bitmap Table of the bitmap", where each entry is 8 bytes. But this sounds likebitmap_table_size== 1 implies that the table is exactly 1 cluster (at least 512 bytes). I think you are trying to imply that the bitmap data occupiesceil(cluster size / 8 / bitmap_tablesize)clusters.
I don't understand.. No. Bitmap data occupies bitmap_table_size clusters. The last one may have some meaningless remaining bits. If bitmap_table_size = 1, than bitmap data is stored in "exactly 1" cluster. Bitmap table is like page table.
Quoted 6 lines
I also wonder if you need more text to cover what happens when the number of entries does not end on a cluster boundary. Must the remaining bits of the cluster containing the tail of the Bitmap be set to all 0, or is it garbage that must be ignored regardless of content?
Signature · 3 lines
Best regards, Vladimir * now, @virtuozzo.com instead of @parallels.com. Sorry for this inconvenience.
Quoted 71 lines · Vladimir Sementsov-Ogievskiy
Quoted 59 lines · Eric Blake
Quoted 20 lines · Vladimir Sementsov-Ogievskiy
The new feature for qcow2: storing bitmaps.
This patch adds new header extension to qcow2 - Bitmaps Extension. It provides an ability to store virtual disk related bitmaps in a qcow2 image. For now there is only one type of such bitmaps: Dirty Tracking Bitmap, which just tracks virtual disk changes from some moment.
Note: Only bitmaps, relative to the virtual disk, stored in qcow2 file, should be stored in this qcow2 file. The size of each bitmap (considering its granularity) is equal to virtual disk size.
Signed-off-by Vladimir Sementsov-Ogievskiy <[email protected]>---
(quoted diff) +0
-0@@ -166,6 +179,34 @@ the header extension data. Each entry look likethis:
terminated if it has full length)
+== Bitmaps extension ==(quoted diff) +2
-0+ +Bitmaps extension is an optional header extension. It provides anQuoted 6 lines
ability to
+store virtual disk related bitmaps in a qcow2 image. For now there is only one
+type of such bitmaps: Dirty Tracking Bitmap, which just tracks virtual disk
+changes from some moment.This is already the qcow2 spec, so 'in a qcow2 image' may be redundant.
Possible idea for nicer grammar:It provides the ability to store bitmaps related to a virtual disk. For now, there is only one bitmap type: Dirty Tracking Bitmap, which tracks virtual disk changes from some moment.
docs/specs/qcow2.txt Snapshot table entry: · line 452
Quoted 2 lines
docs/specs/qcow2.txt +2
-0+ 17: granularity_bits + Granularity bits. Valid values are: 0 - 63.Elsewhere, the file has 'valid values: 0-63'; dropping 'are' would make this more consistent.
Quoted 10 lines
(quoted diff) +2
-0+ + Note: Qemu currently doesn't support
granularity_bitsdocs/specs/qcow2.txt +6
-0+ greater than 31. + + Granularity is calculated as + granularity = 1 << granularity_bits + + Granularity of the bitmap is how many bytes ofthe image
docs/specs/qcow2.txt Snapshot table entry: · line 464
Quoted 4 lines
docs/specs/qcow2.txt +4
-0+ accounts for one bit of the bitmap. + + 18 - 19: name_size + Size of the bitmap name. Valid values: 1 - 1023.Should this be more like:
Must be non-zero. Note: Qemu currently doesn't support values greater than 1023.Quoted 10 lines
Quoted 5 lines
+=== Bitmap Data ===
(quoted diff) +2
-0+ +As noted above, bitmap data is stored in several (or may be one,exactly
+bitmap_table_size) separate clusters, described by Bitmap Table.
bitmap_table_sizewas documented as "Number of entries in the Bitmap Table of the bitmap", where each entry is 8 bytes. But this sounds likebitmap_table_size== 1 implies that the table is exactly 1 cluster (at least 512 bytes). I think you are trying to imply that the bitmap data occupiesceil(cluster size / 8 / bitmap_tablesize)clusters.
Quoted 5 lines
I don't understand.. No. Bitmap data occupies
bitmap_table_sizeclusters. The last one may have some meaningless remaining bits. Ifbitmap_table_size= 1, than bitmap data is stored in "exactly 1" cluster. Bitmap table is like page table.
Eric is referring to earlier in the spec where you state:
"bitmap_table_size" "Number of entries in the Bitmap Table of the bitmap."
But later on, it appears as if "bitmap_table_size" refers to a number of clusters:
"As noted above, bitmap data is stored in several (or may be one, exactly bitmap_table_size) separate clusters"
Here, one may read "bitmap_table_size" to be referring to a cluster count -- which is only indirectly true.
I think what is meant is this:
- bitmap_table_size refers to the number of bitmap table entries.
- each bitmap table entry indicates a cluster's worth of data.
- "bitmap_table_size := 0x01" implies eight bytes for the header, but an entire cluster for data.
So "indirectly," bitmap_table_size refers to the number of clusters that contain bitmap data, but to be accurately precise, it actually refers to the number of bitmap table entries.
Correct?
Quoted 8 lines
Quoted 6 lines
I also wonder if you need more text to cover what happens when the number of entries does not end on a cluster boundary. Must the remaining bits of the cluster containing the tail of the Bitmap be set to all 0, or is it garbage that must be ignored regardless of content?
Quoted 7 lines · Vladimir Sementsov-Ogievskiy
The new feature for qcow2: storing bitmaps.
This patch adds new header extension to qcow2 - Bitmaps Extension. It provides an ability to store virtual disk related bitmaps in a qcow2 image. For now there is only one type of such bitmaps: Dirty Tracking Bitmap, which just tracks virtual disk changes from some moment.
Quoted 6 lines
Note: Only bitmaps, relative to the virtual disk, stored in qcow2 file, should be stored in this qcow2 file. The size of each bitmap (considering its granularity) is equal to virtual disk size.
Signed-off-by Vladimir Sementsov-Ogievskiy <[email protected]>---
OK, keeping my eyes open for grammar etc.; here goes nothing:
Generally, most of the qcow2 specification does not consider structure names to be proper nouns, that is, they are generally written starting with lower letters (e.g. "refcount table", "L2 table", "image header").
I'd prefer this spelling for all the structures presented herein (e.g. "bitmaps extension", "bitmap directory", "dirty tracking bitmap", ...), too, but that is probably a personal preference.
Quoted 9 lines
docs/specs/qcow2.txt | 161 ++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 160 insertions(+), 1 deletion(-)docs/specs/qcow2.txt +0
-0@@ -103,7 +103,19 @@ in the description of a field. write to an image with unknown auto-clear features if it
docs/specs/qcow2.txt in the description of a field. · line 112
Quoted 10 lines
docs/specs/qcow2.txt +7
-1clears the respective bits from this field first. - Bits 0-63: Reserved (set to 0) + Bit 0: Bitmaps extension bit. + This bit is responsible for Bitmaps extension + consistency. + + If it is set, but there is no Bitmaps + extension, this should be considered as an + error.
Maybe correct (this is why a native speaker should be doing this...), but I'd omit the "as" (i.e. just "this should be considered an error").
docs/specs/qcow2.txt in the description of a field. · line 116
Quoted 4 lines
docs/specs/qcow2.txt +4
-0+ + If it is not set, but there is a Bitmaps + extension, its data should be considered as + inconsistent.
Same here.
Quoted 14 lines
docs/specs/qcow2.txt +3
-0+ + Bits 1-63: Reserved (set to 0) 96 - 99: refcount_order Describes the width of a reference count block entry (width@@ -123,6 +135,7 @@ be stored. Each extension has a structure like the following: 0x00000000 - End of the header extension area 0xE2792ACA - Backing file format name 0x6803f857 - Feature name table + 0x23852875 - Bitmaps extension other - Unknown header extension, can be safely ignored
docs/specs/qcow2.txt the header extension data. Each entry look like this: · line 184
Quoted 6 lines
docs/specs/qcow2.txt +3
-0@@ -166,6 +179,34 @@ the header extension data. Each entry look like this: terminated if it has full length) +== Bitmaps extension == + +Bitmaps extension is an optional header extension. It provides an ability to
"The Bitmaps extension..."
Also, while it may be correct as it is, "provides the ability" sounds better to me.
docs/specs/qcow2.txt the header extension data. Each entry look like this: · line 186
Quoted 2 lines
docs/specs/qcow2.txt +2
-0+store virtual disk related bitmaps in a qcow2 image. For now there is only one +type of such bitmaps: Dirty Tracking Bitmap, which just tracks virtual disk
I'd prefer "The Dirty Tracking Bitmap" or "Dirty Tracking Bitmaps".
docs/specs/qcow2.txt the header extension data. Each entry look like this: · line 187
Quoted 1 line
docs/specs/qcow2.txt +1
-0+changes from some moment.
I think, "moment" is rather used for a time span in English. So this should be "point in time" instead.
(Maybe even "a certain point in time" rather than "some point in time", but that would be a semantic change.)
docs/specs/qcow2.txt the header extension data. Each entry look like this: · line 189
Quoted 2 lines
docs/specs/qcow2.txt +2
-0+ +The data of the extension should be considered as consistent only if
Again, the "as" can be dropped (and maybe it should be).
Also, it should be "...only if the corresponding..." ("the" missing).
docs/specs/qcow2.txt the header extension data. Each entry look like this: · line 192
Quoted 3 lines
docs/specs/qcow2.txt +3
-0+corresponding auto-clear feature bit is set (see autoclear_features above). + +The fields of Bitmaps extension are:
"...of the Bitmaps..."
docs/specs/qcow2.txt the header extension data. Each entry look like this: · line 202
Quoted 10 lines
docs/specs/qcow2.txt +10
-0+ + 0 - 3: nb_bitmaps + The number of bitmaps contained in the image. Must be + greater or equal to 1. + + Note: Qemu currently only supports up to 65535 bitmaps per + image. + + 4 - 7: bitmap_directory_size + Size of the Bitmap Directory in bytes. It is a cumulative
"...It is the cumulative size..."
Quoted 11 lines
docs/specs/qcow2.txt +7
-0+ size of all (nb_bitmaps) bitmap headers. + + 8 - 15: bitmap_directory_offset + Offset into the image file at which the 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
docs/specs/qcow2.txt Snapshot table entry: · line 408
Quoted 8 lines
docs/specs/qcow2.txt +5
-0@@ -360,3 +401,121 @@ Snapshot table entry: variable: Padding to round up the snapshot table entry size to the next multiple of 8. + + +== Bitmaps == + +The feature supports storing bitmaps in a qcow2 image. All bitmaps are related
Maybe "This feature supports...".
docs/specs/qcow2.txt Snapshot table entry: · line 409
Quoted 1 line
docs/specs/qcow2.txt +1
-0+to the virtual disk, stored in this image.
The comma should be omitted.
docs/specs/qcow2.txt Snapshot table entry: · line 414
Quoted 5 lines
docs/specs/qcow2.txt +5
-0+ +=== Bitmap Directory === + +Each bitmap saved in the image is described in a Bitmap Directory entry. Bitmap +Directory is a contiguous area in the image file, whose starting offset and
"... The Bitmap Directory is..."
docs/specs/qcow2.txt Snapshot table entry: · line 415
Quoted 1 line
docs/specs/qcow2.txt +1
-0+length are given by the header extension fields bitmap_directory_offset and
"bitmap header extension fields" may be clearer, but that can be parsed both as "(bitmap (header extension)) fields" and "((bitmap header) extension) fields"; the first is what we want (the qcow2 header extension for bitmaps), the second would be an extension for a bitmap directory entry (which are "bitmap headers"), sooo... Probably it'll be best leaving this as it is.
docs/specs/qcow2.txt Snapshot table entry: · line 420
Quoted 5 lines
docs/specs/qcow2.txt +5
-0+bitmap_directory_size. The entries of the bitmap directory have variable +length, depending on the length of the bitmap name and extra data. These +entries are also called bitmap headers. + +Bitmap Directory Entry:
"entry" should be written starting with a lower letter, and a more verbose "Structure of a Bitmap Directory entry" may be nicer.
Quoted 31 lines
docs/specs/qcow2.txt +31
-0+ + Byte 0 - 7: bitmap_table_offset + Offset into the image file at which the Bitmap Table + (described below) for the bitmap starts. Must be aligned to + a cluster boundary. + + 8 - 11: bitmap_table_size + Number of entries in the Bitmap Table of the bitmap. + + 12 - 15: flags + Bit + 0: in_use + The bitmap was not saved correctly and may be + inconsistent. + + 1: auto + The bitmap must reflect all changes of the virtual + disk by any application that would write to this qcow2 + file (including writes, snapshot switching, etc.). The + type of this bitmap must be 'Dirty Tracking Bitmap'. + + Bits 2 - 31 are reserved and must be 0. + + 16: type + This field describes the sort of the bitmap. + Values: + 1: Dirty Tracking Bitmap + + Values 0, 2 - 255 are reserved. + + 17: granularity_bits
docs/specs/qcow2.txt Snapshot table entry: · line 461
Quoted 10 lines
docs/specs/qcow2.txt +10
-0+ Granularity bits. Valid values are: 0 - 63. + + Note: Qemu currently doesn't support granularity_bits + greater than 31. + + Granularity is calculated as + granularity = 1 << granularity_bits + + Granularity of the bitmap is how many bytes of the image + accounts for one bit of the bitmap.
I'd prefer "A bitmap's granularity" or at least "The granularity of the bitmap".
Quoted 7 lines
docs/specs/qcow2.txt +7
-0+ + 18 - 19: name_size + Size of the bitmap name. Valid values: 1 - 1023. + + 20 - 23: extra_data_size + Size of type-specific extra data. +
docs/specs/qcow2.txt Snapshot table entry: · line 478
Quoted 10 lines
docs/specs/qcow2.txt +10
-0+ For now, as no extra data is defined, extra_data_size is + reserved and must be zero. + + variable: Type-specific extra data for the bitmap. + + variable: The name of the bitmap (not null terminated). Must be + unique among all bitmap names within the Bitmaps extension. + + variable: Padding to round up the Bitmap Directory Entry size to the + next multiple of 8.
"...to round up this entry's size..." would be shorter. In any case, "Entry" should be written with a lower letter, I think (but frankly, I think that even "Bitmap Directory" should be written in lowercase, so make of that what you wish).
docs/specs/qcow2.txt Snapshot table entry: · line 483
Quoted 5 lines
docs/specs/qcow2.txt +5
-0+ +=== Bitmap Table === + +Bitmaps are stored using a one-level (not two-level like refcounts and guest +clusters mapping) structure for the mapping of bitmaps data to host clusters.
The sentence in the parantheses may be correct, but it sounds weird. Maybe "as opposed to two-level like for refcounts and..." would be better (but the plain "two-level" still sounds strange).
Also, probably s/bitmaps data/bitmap data/.
docs/specs/qcow2.txt Snapshot table entry: · line 484
Quoted 1 line
docs/specs/qcow2.txt +1
-0+It is called Bitmap Table.
I'd prefer either "...to host clusters, which is called a Bitmap Table." or "This structure is called a Bitmap Table.".
docs/specs/qcow2.txt Snapshot table entry: · line 487
Quoted 3 lines
docs/specs/qcow2.txt +3
-0+ +Each Bitmap Table has a variable size (stored in the Bitmap Directory Entry) +and may use multiple clusters, however it must be contiguous in the image file.
I'd put a comma after the "however", too.
docs/specs/qcow2.txt Snapshot table entry: · line 489
Quoted 2 lines
docs/specs/qcow2.txt +2
-0+ +Bitmap Table entry:
Again, a more verbose "Structure of a Bitmap Table entry" might be nicer, but this is completely optional.
docs/specs/qcow2.txt Snapshot table entry: · line 498
Quoted 9 lines
docs/specs/qcow2.txt +9
-0+ + Bit 0: Reserved and must be zero if bits 9 - 55 are non-zero. + If bits 9 - 55 are zero: + 0: Cluster should be read as all zeros. + 1: Cluster should be read as all ones. + + 1 - 8: Reserved and must be zero. + + 9 - 55: Bits 9 - 55 of host cluster offset. Must be aligned to a
"...of the host cluster offset."
docs/specs/qcow2.txt Snapshot table entry: · line 500
Quoted 2 lines
docs/specs/qcow2.txt +2
-0+ cluster boundary. If the offset is 0, the cluster is + unallocated, see bit 0 description.
"..., the custer is unallocated; in that case, see the description of/for bit 0.",
or:
"..., the cluster is unallocated; in that case, bit 0 determines how this cluster should be treated when read from."
docs/specs/qcow2.txt Snapshot table entry: · line 504
Quoted 4 lines
docs/specs/qcow2.txt +4
-0+ + 56 - 63: Reserved and must be zero. + +=== Bitmap Data ===
As you never use this as a proper noun anywhere, I think it's safe to make this a "Bitmap data".
docs/specs/qcow2.txt Snapshot table entry: · line 506
Quoted 2 lines
docs/specs/qcow2.txt +2
-0+ +As noted above, bitmap data is stored in several (or may be one, exactly
s/may be/maybe/
Alternatively, the common phrasing is: "...is stored in one or more (bitmap_table_size) separate clusters...".
docs/specs/qcow2.txt Snapshot table entry: · line 507
Quoted 1 line
docs/specs/qcow2.txt +1
-0+bitmap_table_size) separate clusters, described by Bitmap Table. Given an
"..., as described by the Bitmap Table."
docs/specs/qcow2.txt Snapshot table entry: · line 517
Quoted 10 lines
docs/specs/qcow2.txt +10
-0+offset (in bytes) into the bitmap data, the offset into the image file can be +obtained as follows: + + image_offset = + bitmap_table[bitmap_data_offset / cluster_size] + + (bitmap_data_offset % cluster_size) + +Taking into account the granularity of the bitmap, an offset in bits into the +image file, corresponding to byte number byte_nr of the virtual disk can be +calculated like this:
Probably the following is better:
Given an offset byte_nr into the virtual disk and the bitmap's granularity, the bit offset into the bitmap can be calculated like this:
docs/specs/qcow2.txt Snapshot table entry: · line 521
Quoted 5 lines
docs/specs/qcow2.txt +4
-0+ + bit_offset = + image_offset(byte_nr / granularity / 8) * 8 + + (byte_nr / granularity) % 8
Max
Since Max didn't offer a grammatical review, here's my attempt at some suggestions.
Quoted 45 lines · Vladimir Sementsov-Ogievskiy
The new feature for qcow2: storing bitmaps.
This patch adds new header extension to qcow2 - Bitmaps Extension. It provides an ability to store virtual disk related bitmaps in a qcow2 image. For now there is only one type of such bitmaps: Dirty Tracking Bitmap, which just tracks virtual disk changes from some moment.
Note: Only bitmaps, relative to the virtual disk, stored in qcow2 file, should be stored in this qcow2 file. The size of each bitmap (considering its granularity) is equal to virtual disk size.
Signed-off-by Vladimir Sementsov-Ogievskiy <[email protected]>---
v6:
- reword
bitmap_directory_sizedescription
- bitmap type: make 0 reserved
-extra_data_size: resize to 4bytes
Also, I've marked this field as "must be zero". We can always change it, if we decide allowing managing app to specify any extra data, by defining some magic value as a top of user extra data.. So, for now non zeorextra_data_sizeshould be considered as an error.
- swap name andextra_datato give good alignment toextra_data.v5:
- 'Dirty bitmaps' renamed to 'Bitmaps', as we may have several types of bitmaps.
- rewordings
- move upper bounds to "Notes about Qemu limits"
- s/should/must somewhere. (but not everywhere)
- movename_sizefield closer to name itself in bitmap header
- add extra data area to bitmap header
- move bitmap data description to separate sectiondocs/specs/qcow2.txt | 161 ++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 160 insertions(+), 1 deletion(-)docs/specs/qcow2.txt +0
-0
docs/specs/qcow2.txt in the description of a field. · line 106
Quoted 5 lines
docs/specs/qcow2.txt +1
-1@@ -103,7 +103,19 @@ 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: Bitmaps extension bit.
For consistency, no period after this.
docs/specs/qcow2.txt in the description of a field. · line 109
Quoted 3 lines
docs/specs/qcow2.txt +3
-0+ This bit is responsible for Bitmaps extension + consistency. +
I might phrase it as: "This bit indicates consistency for the Bitmaps extension data."
docs/specs/qcow2.txt in the description of a field. · line 113
Quoted 4 lines
docs/specs/qcow2.txt +4
-0+ If it is set, but there is no Bitmaps + extension, this should be considered as an + error. +
"This should be considered as an error" can be shortened to just "This is an error." This makes the sentence top-heavy though, so how about:
"It is an error if this bit is set without the Bitmaps extension present."
docs/specs/qcow2.txt in the description of a field. · line 117
Quoted 4 lines
docs/specs/qcow2.txt +4
-0+ If it is not set, but there is a Bitmaps + extension, its data should be considered as + inconsistent. +
Let's remove "considered" here. The data *is* inconsistent if this has happened.
"If the Bitmaps extension is present but this bit is unset, the Bitmaps extension data is inconsistent."
Quoted 13 lines
docs/specs/qcow2.txt +2
-0+ Bits 1-63: Reserved (set to 0) 96 - 99: refcount_order Describes the width of a reference count block entry (width@@ -123,6 +135,7 @@ be stored. Each extension has a structure like the following: 0x00000000 - End of the header extension area 0xE2792ACA - Backing file format name 0x6803f857 - Feature name table + 0x23852875 - Bitmaps extension other - Unknown header extension, can be safely ignored
docs/specs/qcow2.txt the header extension data. Each entry look like this: · line 188
Quoted 10 lines
docs/specs/qcow2.txt +7
-0@@ -166,6 +179,34 @@ the header extension data. Each entry look like this: terminated if it has full length) +== Bitmaps extension == + +Bitmaps extension is an optional header extension. It provides an ability to +store virtual disk related bitmaps in a qcow2 image. For now there is only one +type of such bitmaps: Dirty Tracking Bitmap, which just tracks virtual disk +changes from some moment. +
I think "Bitmaps extension" is awkward without "The" leading it, so:
"The Bitmaps extension is an optional header extension."
And from Eric's suggestion:
"It provides the ability to store bitmaps related to a virtual disk. For now, there is only one bitmap type: Dirty Tracking Bitmap, which tracks virtual disk changes from some moment."
docs/specs/qcow2.txt the header extension data. Each entry look like this: · line 191
Quoted 3 lines
docs/specs/qcow2.txt +3
-0+The data of the extension should be considered as consistent only if +corresponding auto-clear feature bit is set (see autoclear_features above). +
I might remove the parenthetical.
"The data in this extension should be considered consistent only if the corresponding auto-clear feature bit is set, see autoclear_features above."
docs/specs/qcow2.txt the header extension data. Each entry look like this: · line 193
Quoted 2 lines
docs/specs/qcow2.txt +2
-0+The fields of Bitmaps extension are: +
Adding 'the' again:
"The fields of the Bitmaps extension are:"
docs/specs/qcow2.txt the header extension data. Each entry look like this: · line 197
Quoted 4 lines
docs/specs/qcow2.txt +4
-0+ 0 - 3: nb_bitmaps + The number of bitmaps contained in the image. Must be + greater or equal to 1. +
"Greater than or equal to" is a common phrasing -- adding the 'than'.
Quoted 16 lines
docs/specs/qcow2.txt +12
-0+ Note: Qemu currently only supports up to 65535 bitmaps per + image. + + 4 - 7: bitmap_directory_size + Size of the Bitmap Directory in bytes. It is a cumulative + size of all (nb_bitmaps) bitmap headers. + + 8 - 15: bitmap_directory_offset + Offset into the image file at which the 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
docs/specs/qcow2.txt Snapshot table entry: · line 410
Quoted 10 lines
docs/specs/qcow2.txt +7
-0@@ -360,3 +401,121 @@ Snapshot table entry: variable: Padding to round up the snapshot table entry size to the next multiple of 8. + + +== Bitmaps == + +The feature supports storing bitmaps in a qcow2 image. All bitmaps are related +to the virtual disk, stored in this image. +
Maybe like Eric's earlier suggestion, we can avoid "in a qcow2 image" here. We can probably just repeat some of the earlier description here.
docs/specs/qcow2.txt Snapshot table entry: · line 413
Quoted 3 lines
docs/specs/qcow2.txt +3
-0+=== Bitmap Directory === + +Each bitmap saved in the image is described in a Bitmap Directory entry. Bitmap
"The Bitmap Directory"
Quoted 50 lines
docs/specs/qcow2.txt +50
-0+Directory is a contiguous area in the image file, whose starting offset and +length are given by the header extension fields bitmap_directory_offset and +bitmap_directory_size. The entries of the bitmap directory have variable +length, depending on the length of the bitmap name and extra data. These +entries are also called bitmap headers. + +Bitmap Directory Entry: + + Byte 0 - 7: bitmap_table_offset + Offset into the image file at which the Bitmap Table + (described below) for the bitmap starts. Must be aligned to + a cluster boundary. + + 8 - 11: bitmap_table_size + Number of entries in the Bitmap Table of the bitmap. + + 12 - 15: flags + Bit + 0: in_use + The bitmap was not saved correctly and may be + inconsistent. + + 1: auto + The bitmap must reflect all changes of the virtual + disk by any application that would write to this qcow2 + file (including writes, snapshot switching, etc.). The + type of this bitmap must be 'Dirty Tracking Bitmap'. + + Bits 2 - 31 are reserved and must be 0. + + 16: type + This field describes the sort of the bitmap. + Values: + 1: Dirty Tracking Bitmap + + Values 0, 2 - 255 are reserved. + + 17: granularity_bits + Granularity bits. Valid values are: 0 - 63. + + Note: Qemu currently doesn't support granularity_bits + greater than 31. + + Granularity is calculated as + granularity = 1 << granularity_bits + + Granularity of the bitmap is how many bytes of the image + accounts for one bit of the bitmap. + + 18 - 19: name_size
docs/specs/qcow2.txt Snapshot table entry: · line 473
Quoted 10 lines
docs/specs/qcow2.txt +10
-0+ Size of the bitmap name. Valid values: 1 - 1023. + + 20 - 23: extra_data_size + Size of type-specific extra data. + + For now, as no extra data is defined, extra_data_size is + reserved and must be zero. + + variable: Type-specific extra data for the bitmap. +
And I guess we don't have any definitions for the "Dirty Tracking" type, so this is zero.
Should we add a table of the bitmap types and their corresponding definitions for the "Type-specific extra data"?
e.g.
=== Bitmap Types ===
0: Reserved
extra_data_size: 0
This bitmap type is invalid and must not be used.
1: Dirty Tracking Bitmap
extra_data_size: 0
This bitmap type represents data changed since a point in time and has no extra data.
2: Lorem Ipsum Bitmap
extra_data_size: 4
Lorem ipsum, dolor sit amet...
This bitmap type has four byte of extra data:
0-1: Identifier
2-3: Padding
docs/specs/qcow2.txt Snapshot table entry: · line 485
Quoted 12 lines
docs/specs/qcow2.txt +12
-0+ variable: The name of the bitmap (not null terminated). Must be + unique among all bitmap names within the Bitmaps extension. + + variable: Padding to round up the Bitmap Directory Entry size to the + next multiple of 8. + +=== Bitmap Table === + +Bitmaps are stored using a one-level (not two-level like refcounts and guest +clusters mapping) structure for the mapping of bitmaps data to host clusters. +It is called Bitmap Table. +
I might add "the" before Bitmap Table above.
Quoted 27 lines
docs/specs/qcow2.txt +26
-0+Each Bitmap Table has a variable size (stored in the Bitmap Directory Entry) +and may use multiple clusters, however it must be contiguous in the image file. + +Bitmap Table entry: + + Bit 0: Reserved and must be zero if bits 9 - 55 are non-zero. + If bits 9 - 55 are zero: + 0: Cluster should be read as all zeros. + 1: Cluster should be read as all ones. + + 1 - 8: Reserved and must be zero. + + 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, see bit 0 description. + + 56 - 63: Reserved and must be zero. + +=== Bitmap Data === + +As noted above, bitmap data is stored in several (or may be one, exactly +bitmap_table_size) separate clusters, described by Bitmap Table. Given an +offset (in bytes) into the bitmap data, the offset into the image file can be +obtained as follows: + + image_offset =
docs/specs/qcow2.txt Snapshot table entry: · line 521
Quoted 10 lines
docs/specs/qcow2.txt +10
-0+ bitmap_table[bitmap_data_offset / cluster_size] + + (bitmap_data_offset % cluster_size) + +Taking into account the granularity of the bitmap, an offset in bits into the +image file, corresponding to byte number byte_nr of the virtual disk can be +calculated like this: + + bit_offset = + image_offset(byte_nr / granularity / 8) * 8 + + (byte_nr / granularity) % 8
That's all the language commentary I have on this. Hopefully not long before consensus.
Thank you,
--John
Quoted 238 lines · John Snow
Since Max didn't offer a grammatical review, here's my attempt at some suggestions.
Quoted 45 lines · Vladimir Sementsov-Ogievskiy
The new feature for qcow2: storing bitmaps.
This patch adds new header extension to qcow2 - Bitmaps Extension. It provides an ability to store virtual disk related bitmaps in a qcow2 image. For now there is only one type of such bitmaps: Dirty Tracking Bitmap, which just tracks virtual disk changes from some moment.
Note: Only bitmaps, relative to the virtual disk, stored in qcow2 file, should be stored in this qcow2 file. The size of each bitmap (considering its granularity) is equal to virtual disk size.
Signed-off-by Vladimir Sementsov-Ogievskiy <[email protected]>---
v6:
- reword
bitmap_directory_sizedescription
- bitmap type: make 0 reserved
-extra_data_size: resize to 4bytes
Also, I've marked this field as "must be zero". We can always change it, if we decide allowing managing app to specify any extra data, by defining some magic value as a top of user extra data.. So, for now non zeorextra_data_sizeshould be considered as an error.
- swap name andextra_datato give good alignment toextra_data.v5:
- 'Dirty bitmaps' renamed to 'Bitmaps', as we may have several types of bitmaps.
- rewordings
- move upper bounds to "Notes about Qemu limits"
- s/should/must somewhere. (but not everywhere)
- movename_sizefield closer to name itself in bitmap header
- add extra data area to bitmap header
- move bitmap data description to separate sectiondocs/specs/qcow2.txt | 161 ++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 160 insertions(+), 1 deletion(-)docs/specs/qcow2.txt +0
-0docs/specs/qcow2.txt in the description of a field. · line 106
Quoted 5 lines
docs/specs/qcow2.txt +1
-1@@ -103,7 +103,19 @@ 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: Bitmaps extension bit.For consistency, no period after this.
docs/specs/qcow2.txt in the description of a field. · line 109
Quoted 3 lines
docs/specs/qcow2.txt +3
-0+ This bit is responsible for Bitmaps extension + consistency. +I might phrase it as: "This bit indicates consistency for the Bitmaps extension data."
docs/specs/qcow2.txt in the description of a field. · line 113
Quoted 4 lines
docs/specs/qcow2.txt +4
-0+ If it is set, but there is no Bitmaps + extension, this should be considered as an + error. +"This should be considered as an error" can be shortened to just "This is an error." This makes the sentence top-heavy though, so how about:
"It is an error if this bit is set without the Bitmaps extension present."
docs/specs/qcow2.txt in the description of a field. · line 117
Quoted 4 lines
docs/specs/qcow2.txt +4
-0+ If it is not set, but there is a Bitmaps + extension, its data should be considered as + inconsistent. +Let's remove "considered" here. The data *is* inconsistent if this has happened.
"If the Bitmaps extension is present but this bit is unset, the Bitmaps extension data is inconsistent."
Quoted 13 lines
docs/specs/qcow2.txt +2
-0+ Bits 1-63: Reserved (set to 0) 96 - 99: refcount_order Describes the width of a reference count block entry (width@@ -123,6 +135,7 @@ be stored. Each extension has a structure like the following: 0x00000000 - End of the header extension area 0xE2792ACA - Backing file format name 0x6803f857 - Feature name table + 0x23852875 - Bitmaps extension other - Unknown header extension, can be safely ignoreddocs/specs/qcow2.txt the header extension data. Each entry look like this: · line 188
Quoted 10 lines
docs/specs/qcow2.txt +7
-0@@ -166,6 +179,34 @@ the header extension data. Each entry look like this: terminated if it has full length) +== Bitmaps extension == + +Bitmaps extension is an optional header extension. It provides an ability to +store virtual disk related bitmaps in a qcow2 image. For now there is only one +type of such bitmaps: Dirty Tracking Bitmap, which just tracks virtual disk +changes from some moment. +I think "Bitmaps extension" is awkward without "The" leading it, so:
"The Bitmaps extension is an optional header extension."
And from Eric's suggestion:
"It provides the ability to store bitmaps related to a virtual disk. For now, there is only one bitmap type: Dirty Tracking Bitmap, which tracks virtual disk changes from some moment."
docs/specs/qcow2.txt the header extension data. Each entry look like this: · line 191
Quoted 3 lines
docs/specs/qcow2.txt +3
-0+The data of the extension should be considered as consistent only if +corresponding auto-clear feature bit is set (see autoclear_features above). +I might remove the parenthetical.
"The data in this extension should be considered consistent only if the corresponding auto-clear feature bit is set, see
autoclear_featuresabove."docs/specs/qcow2.txt the header extension data. Each entry look like this: · line 193
Quoted 2 lines
docs/specs/qcow2.txt +2
-0+The fields of Bitmaps extension are: +Adding 'the' again:
"The fields of the Bitmaps extension are:"
docs/specs/qcow2.txt the header extension data. Each entry look like this: · line 197
Quoted 4 lines
docs/specs/qcow2.txt +4
-0+ 0 - 3: nb_bitmaps + The number of bitmaps contained in the image. Must be + greater or equal to 1. +"Greater than or equal to" is a common phrasing -- adding the 'than'.
Quoted 16 lines
docs/specs/qcow2.txt +12
-0+ Note: Qemu currently only supports up to 65535 bitmaps per + image. + + 4 - 7: bitmap_directory_size + Size of the Bitmap Directory in bytes. It is a cumulative + size of all (nb_bitmaps) bitmap headers. + + 8 - 15: bitmap_directory_offset + Offset into the image file at which the Bitmap Directory + starts. Must be aligned to a cluster boundary. + + == Host cluster management == qcow2 manages the allocation of host clusters by maintaining a reference countdocs/specs/qcow2.txt Snapshot table entry: · line 410
Quoted 10 lines
docs/specs/qcow2.txt +7
-0@@ -360,3 +401,121 @@ Snapshot table entry: variable: Padding to round up the snapshot table entry size to the next multiple of 8. + + +== Bitmaps == + +The feature supports storing bitmaps in a qcow2 image. All bitmaps are related +to the virtual disk, stored in this image. +Maybe like Eric's earlier suggestion, we can avoid "in a qcow2 image" here. We can probably just repeat some of the earlier description here.
docs/specs/qcow2.txt Snapshot table entry: · line 413
Quoted 3 lines
docs/specs/qcow2.txt +3
-0+=== Bitmap Directory === + +Each bitmap saved in the image is described in a Bitmap Directory entry. Bitmap"The Bitmap Directory"
Quoted 50 lines
docs/specs/qcow2.txt +50
-0+Directory is a contiguous area in the image file, whose starting offset and +length are given by the header extension fields bitmap_directory_offset and +bitmap_directory_size. The entries of the bitmap directory have variable +length, depending on the length of the bitmap name and extra data. These +entries are also called bitmap headers. + +Bitmap Directory Entry: + + Byte 0 - 7: bitmap_table_offset + Offset into the image file at which the Bitmap Table + (described below) for the bitmap starts. Must be aligned to + a cluster boundary. + + 8 - 11: bitmap_table_size + Number of entries in the Bitmap Table of the bitmap. + + 12 - 15: flags + Bit + 0: in_use + The bitmap was not saved correctly and may be + inconsistent. + + 1: auto + The bitmap must reflect all changes of the virtual + disk by any application that would write to this qcow2 + file (including writes, snapshot switching, etc.). The + type of this bitmap must be 'Dirty Tracking Bitmap'. + + Bits 2 - 31 are reserved and must be 0. + + 16: type + This field describes the sort of the bitmap. + Values: + 1: Dirty Tracking Bitmap + + Values 0, 2 - 255 are reserved. + + 17: granularity_bits + Granularity bits. Valid values are: 0 - 63. + + Note: Qemu currently doesn't support granularity_bits + greater than 31. + + Granularity is calculated as + granularity = 1 << granularity_bits + + Granularity of the bitmap is how many bytes of the image + accounts for one bit of the bitmap. + + 18 - 19: name_sizedocs/specs/qcow2.txt Snapshot table entry: · line 473
Quoted 10 lines
docs/specs/qcow2.txt +10
-0+ Size of the bitmap name. Valid values: 1 - 1023. + + 20 - 23: extra_data_size + Size of type-specific extra data. + + For now, as no extra data is defined, extra_data_size is + reserved and must be zero. + + variable: Type-specific extra data for the bitmap. +And I guess we don't have any definitions for the "Dirty Tracking" type, so this is zero.
Should we add a table of the bitmap types and their corresponding definitions for the "Type-specific extra data"?
e.g.
=== Bitmap Types ===
Quoted 7 lines
0: Reserved
extra_data_size: 0This bitmap type is invalid and must not be used.
1: Dirty Tracking Bitmap
extra_data_size: 0
Are you sure? What about creation\last change dates, file links, user data, etc?
For now, formally, current "For now, as no extra data is defined, extra_data_size is reserved and must be zero." is equal to such table, but provides more flexibility for future..
Quoted 69 lines
This bitmap type represents data changed since a point in time and has no extra data.
2: Lorem Ipsum Bitmap
extra_data_size: 4Lorem ipsum, dolor sit amet...
This bitmap type has four byte of extra data:0-1: Identifier
2-3: Paddingdocs/specs/qcow2.txt Snapshot table entry: · line 485
Quoted 12 lines
docs/specs/qcow2.txt +12
-0+ variable: The name of the bitmap (not null terminated). Must be + unique among all bitmap names within the Bitmaps extension. + + variable: Padding to round up the Bitmap Directory Entry size to the + next multiple of 8. + +=== Bitmap Table === + +Bitmaps are stored using a one-level (not two-level like refcounts and guest +clusters mapping) structure for the mapping of bitmaps data to host clusters. +It is called Bitmap Table. +I might add "the" before Bitmap Table above.
Quoted 27 lines
docs/specs/qcow2.txt +26
-0+Each Bitmap Table has a variable size (stored in the Bitmap Directory Entry) +and may use multiple clusters, however it must be contiguous in the image file. + +Bitmap Table entry: + + Bit 0: Reserved and must be zero if bits 9 - 55 are non-zero. + If bits 9 - 55 are zero: + 0: Cluster should be read as all zeros. + 1: Cluster should be read as all ones. + + 1 - 8: Reserved and must be zero. + + 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, see bit 0 description. + + 56 - 63: Reserved and must be zero. + +=== Bitmap Data === + +As noted above, bitmap data is stored in several (or may be one, exactly +bitmap_table_size) separate clusters, described by Bitmap Table. Given an +offset (in bytes) into the bitmap data, the offset into the image file can be +obtained as follows: + + image_offset =docs/specs/qcow2.txt Snapshot table entry: · line 521
Quoted 10 lines
docs/specs/qcow2.txt +10
-0+ bitmap_table[bitmap_data_offset / cluster_size] + + (bitmap_data_offset % cluster_size) + +Taking into account the granularity of the bitmap, an offset in bits into the +image file, corresponding to byte number byte_nr of the virtual disk can be +calculated like this: + + bit_offset = + image_offset(byte_nr / granularity / 8) * 8 + + (byte_nr / granularity) % 8That's all the language commentary I have on this. Hopefully not long before consensus.
Thank you,
--John
Signature · 3 lines
Best regards, Vladimir * now, @virtuozzo.com instead of @parallels.com. Sorry for this inconvenience.
Quoted 6 lines · Vladimir Sementsov-Ogievskiy
Are you sure? What about creation\last change dates, file links, user data, etc?
For now, formally, current "For now, as no extra data is defined,extra_data_sizeis reserved and must be zero." is equal to such table, but provides more flexibility for future..
Oh, I see what you're trying to do.
In this case, perhaps we need a versioning system for the type-specific data? We won't be able to just add data arbitrarily, we need to change some field somewhere.
Maybe we can say something like...
"If extra_data_size is 0, there is no type-specific data and the version of that data layout is 0. If extra_data_size is non-zero, the first byte of the type-specific-data must be a version number greater than 0 that indicates the layout of the data to follow.
For the Dirty Tracking bitmap type, only version 0 is currently valid."
This way it's explicit that data *could* show up for dirty tracking in the future, but currently it does not.
--js
Quoted 20 lines · John Snow
Quoted 5 lines · Vladimir Sementsov-Ogievskiy
Are you sure? What about creation\last change dates, file links, user data, etc?
For now, formally, current "For now, as no extra data is defined,extra_data_sizeis reserved and must be zero." is equal to such table, but provides more flexibility for future..Oh, I see what you're trying to do.
In this case, perhaps we need a versioning system for the type-specific data? We won't be able to just add data arbitrarily, we need to change some field somewhere.
Maybe we can say something like...
"If
extra_data_sizeis 0, there is no type-specific data and the version of that data layout is 0. Ifextra_data_sizeis non-zero, the first byte of the type-specific-data must be a version number greater than 0 that indicates the layout of the data to follow.
Quoted 6 lines
For the Dirty Tracking bitmap type, only version 0 is currently valid."
This way it's explicit that data *could* show up for dirty tracking in the future, but currently it does not.
--js
It's ok for me.
Signature · 3 lines
Best regards, Vladimir * now, @virtuozzo.com instead of @parallels.com. Sorry for this inconvenience.