af5711e5337191d2c01932b0b3d07566b389f2c2
[qemu.git] / docs / interop / qcow2.txt
1 == General ==
2
3 A qcow2 image file is organized in units of constant size, which are called
4 (host) clusters. A cluster is the unit in which all allocations are done,
5 both for actual guest data and for image metadata.
6
7 Likewise, the virtual disk as seen by the guest is divided into (guest)
8 clusters of the same size.
9
10 All numbers in qcow2 are stored in Big Endian byte order.
11
12
13 == Header ==
14
15 The first cluster of a qcow2 image contains the file header:
16
17     Byte  0 -  3:   magic
18                     QCOW magic string ("QFI\xfb")
19
20           4 -  7:   version
21                     Version number (valid values are 2 and 3)
22
23           8 - 15:   backing_file_offset
24                     Offset into the image file at which the backing file name
25                     is stored (NB: The string is not null terminated). 0 if the
26                     image doesn't have a backing file.
27
28          16 - 19:   backing_file_size
29                     Length of the backing file name in bytes. Must not be
30                     longer than 1023 bytes. Undefined if the image doesn't have
31                     a backing file.
32
33          20 - 23:   cluster_bits
34                     Number of bits that are used for addressing an offset
35                     within a cluster (1 << cluster_bits is the cluster size).
36                     Must not be less than 9 (i.e. 512 byte clusters).
37
38                     Note: qemu as of today has an implementation limit of 2 MB
39                     as the maximum cluster size and won't be able to open images
40                     with larger cluster sizes.
41
42          24 - 31:   size
43                     Virtual disk size in bytes.
44
45                     Note: qemu has an implementation limit of 32 MB as
46                     the maximum L1 table size.  With a 2 MB cluster
47                     size, it is unable to populate a virtual cluster
48                     beyond 2 EB (61 bits); with a 512 byte cluster
49                     size, it is unable to populate a virtual size
50                     larger than 128 GB (37 bits).  Meanwhile, L1/L2
51                     table layouts limit an image to no more than 64 PB
52                     (56 bits) of populated clusters, and an image may
53                     hit other limits first (such as a file system's
54                     maximum size).
55
56          32 - 35:   crypt_method
57                     0 for no encryption
58                     1 for AES encryption
59                     2 for LUKS encryption
60
61          36 - 39:   l1_size
62                     Number of entries in the active L1 table
63
64          40 - 47:   l1_table_offset
65                     Offset into the image file at which the active L1 table
66                     starts. Must be aligned to a cluster boundary.
67
68          48 - 55:   refcount_table_offset
69                     Offset into the image file at which the refcount table
70                     starts. Must be aligned to a cluster boundary.
71
72          56 - 59:   refcount_table_clusters
73                     Number of clusters that the refcount table occupies
74
75          60 - 63:   nb_snapshots
76                     Number of snapshots contained in the image
77
78          64 - 71:   snapshots_offset
79                     Offset into the image file at which the snapshot table
80                     starts. Must be aligned to a cluster boundary.
81
82 If the version is 3 or higher, the header has the following additional fields.
83 For version 2, the values are assumed to be zero, unless specified otherwise
84 in the description of a field.
85
86          72 -  79:  incompatible_features
87                     Bitmask of incompatible features. An implementation must
88                     fail to open an image if an unknown bit is set.
89
90                     Bit 0:      Dirty bit.  If this bit is set then refcounts
91                                 may be inconsistent, make sure to scan L1/L2
92                                 tables to repair refcounts before accessing the
93                                 image.
94
95                     Bit 1:      Corrupt bit.  If this bit is set then any data
96                                 structure may be corrupt and the image must not
97                                 be written to (unless for regaining
98                                 consistency).
99
100                     Bit 2:      External data file bit.  If this bit is set, an
101                                 external data file is used. Guest clusters are
102                                 then stored in the external data file. For such
103                                 images, clusters in the external data file are
104                                 not refcounted. The offset field in the
105                                 Standard Cluster Descriptor must match the
106                                 guest offset and neither compressed clusters
107                                 nor internal snapshots are supported.
108
109                                 An External Data File Name header extension may
110                                 be present if this bit is set.
111
112                     Bits 3-63:  Reserved (set to 0)
113
114          80 -  87:  compatible_features
115                     Bitmask of compatible features. An implementation can
116                     safely ignore any unknown bits that are set.
117
118                     Bit 0:      Lazy refcounts bit.  If this bit is set then
119                                 lazy refcount updates can be used.  This means
120                                 marking the image file dirty and postponing
121                                 refcount metadata updates.
122
123                     Bits 1-63:  Reserved (set to 0)
124
125          88 -  95:  autoclear_features
126                     Bitmask of auto-clear features. An implementation may only
127                     write to an image with unknown auto-clear features if it
128                     clears the respective bits from this field first.
129
130                     Bit 0:      Bitmaps extension bit
131                                 This bit indicates consistency for the bitmaps
132                                 extension data.
133
134                                 It is an error if this bit is set without the
135                                 bitmaps extension present.
136
137                                 If the bitmaps extension is present but this
138                                 bit is unset, the bitmaps extension data must be
139                                 considered inconsistent.
140
141                     Bit 1:      If this bit is set, the external data file can
142                                 be read as a consistent standalone raw image
143                                 without looking at the qcow2 metadata.
144
145                                 Setting this bit has a performance impact for
146                                 some operations on the image (e.g. writing
147                                 zeros requires writing to the data file instead
148                                 of only setting the zero flag in the L2 table
149                                 entry) and conflicts with backing files.
150
151                                 This bit may only be set if the External Data
152                                 File bit (incompatible feature bit 1) is also
153                                 set.
154
155                     Bits 2-63:  Reserved (set to 0)
156
157          96 -  99:  refcount_order
158                     Describes the width of a reference count block entry (width
159                     in bits: refcount_bits = 1 << refcount_order). For version 2
160                     images, the order is always assumed to be 4
161                     (i.e. refcount_bits = 16).
162                     This value may not exceed 6 (i.e. refcount_bits = 64).
163
164         100 - 103:  header_length
165                     Length of the header structure in bytes. For version 2
166                     images, the length is always assumed to be 72 bytes.
167
168 Directly after the image header, optional sections called header extensions can
169 be stored. Each extension has a structure like the following:
170
171     Byte  0 -  3:   Header extension type:
172                         0x00000000 - End of the header extension area
173                         0xE2792ACA - Backing file format name string
174                         0x6803f857 - Feature name table
175                         0x23852875 - Bitmaps extension
176                         0x0537be77 - Full disk encryption header pointer
177                         0x44415441 - External data file name string
178                         other      - Unknown header extension, can be safely
179                                      ignored
180
181           4 -  7:   Length of the header extension data
182
183           8 -  n:   Header extension data
184
185           n -  m:   Padding to round up the header extension size to the next
186                     multiple of 8.
187
188 Unless stated otherwise, each header extension type shall appear at most once
189 in the same image.
190
191 If the image has a backing file then the backing file name should be stored in
192 the remaining space between the end of the header extension area and the end of
193 the first cluster. It is not allowed to store other data here, so that an
194 implementation can safely modify the header and add extensions without harming
195 data of compatible features that it doesn't support. Compatible features that
196 need space for additional data can use a header extension.
197
198
199 == String header extensions ==
200
201 Some header extensions (such as the backing file format name and the external
202 data file name) are just a single string. In this case, the header extension
203 length is the string length and the string is not '\0' terminated. (The header
204 extension padding can make it look like a string is '\0' terminated, but
205 neither is padding always necessary nor is there a guarantee that zero bytes
206 are used for padding.)
207
208
209 == Feature name table ==
210
211 The feature name table is an optional header extension that contains the name
212 for features used by the image. It can be used by applications that don't know
213 the respective feature (e.g. because the feature was introduced only later) to
214 display a useful error message.
215
216 The number of entries in the feature name table is determined by the length of
217 the header extension data. Each entry look like this:
218
219     Byte       0:   Type of feature (select feature bitmap)
220                         0: Incompatible feature
221                         1: Compatible feature
222                         2: Autoclear feature
223
224                1:   Bit number within the selected feature bitmap (valid
225                     values: 0-63)
226
227           2 - 47:   Feature name (padded with zeros, but not necessarily null
228                     terminated if it has full length)
229
230
231 == Bitmaps extension ==
232
233 The bitmaps extension is an optional header extension. It provides the ability
234 to store bitmaps related to a virtual disk. For now, there is only one bitmap
235 type: the dirty tracking bitmap, which tracks virtual disk changes from some
236 point in time.
237
238 The data of the extension should be considered consistent only if the
239 corresponding auto-clear feature bit is set, see autoclear_features above.
240
241 The fields of the bitmaps extension are:
242
243     Byte  0 -  3:  nb_bitmaps
244                    The number of bitmaps contained in the image. Must be
245                    greater than or equal to 1.
246
247                    Note: Qemu currently only supports up to 65535 bitmaps per
248                    image.
249
250           4 -  7:  Reserved, must be zero.
251
252           8 - 15:  bitmap_directory_size
253                    Size of the bitmap directory in bytes. It is the cumulative
254                    size of all (nb_bitmaps) bitmap directory entries.
255
256          16 - 23:  bitmap_directory_offset
257                    Offset into the image file at which the bitmap directory
258                    starts. Must be aligned to a cluster boundary.
259
260 == Full disk encryption header pointer ==
261
262 The full disk encryption header must be present if, and only if, the
263 'crypt_method' header requires metadata. Currently this is only true
264 of the 'LUKS' crypt method. The header extension must be absent for
265 other methods.
266
267 This header provides the offset at which the crypt method can store
268 its additional data, as well as the length of such data.
269
270     Byte  0 -  7:   Offset into the image file at which the encryption
271                     header starts in bytes. Must be aligned to a cluster
272                     boundary.
273     Byte  8 - 15:   Length of the written encryption header in bytes.
274                     Note actual space allocated in the qcow2 file may
275                     be larger than this value, since it will be rounded
276                     to the nearest multiple of the cluster size. Any
277                     unused bytes in the allocated space will be initialized
278                     to 0.
279
280 For the LUKS crypt method, the encryption header works as follows.
281
282 The first 592 bytes of the header clusters will contain the LUKS
283 partition header. This is then followed by the key material data areas.
284 The size of the key material data areas is determined by the number of
285 stripes in the key slot and key size. Refer to the LUKS format
286 specification ('docs/on-disk-format.pdf' in the cryptsetup source
287 package) for details of the LUKS partition header format.
288
289 In the LUKS partition header, the "payload-offset" field will be
290 calculated as normal for the LUKS spec. ie the size of the LUKS
291 header, plus key material regions, plus padding, relative to the
292 start of the LUKS header. This offset value is not required to be
293 qcow2 cluster aligned. Its value is currently never used in the
294 context of qcow2, since the qcow2 file format itself defines where
295 the real payload offset is, but none the less a valid payload offset
296 should always be present.
297
298 In the LUKS key slots header, the "key-material-offset" is relative
299 to the start of the LUKS header clusters in the qcow2 container,
300 not the start of the qcow2 file.
301
302 Logically the layout looks like
303
304   +-----------------------------+
305   | QCow2 header                |
306   | QCow2 header extension X    |
307   | QCow2 header extension FDE  |
308   | QCow2 header extension ...  |
309   | QCow2 header extension Z    |
310   +-----------------------------+
311   | ....other QCow2 tables....  |
312   .                             .
313   .                             .
314   +-----------------------------+
315   | +-------------------------+ |
316   | | LUKS partition header   | |
317   | +-------------------------+ |
318   | | LUKS key material 1     | |
319   | +-------------------------+ |
320   | | LUKS key material 2     | |
321   | +-------------------------+ |
322   | | LUKS key material ...   | |
323   | +-------------------------+ |
324   | | LUKS key material 8     | |
325   | +-------------------------+ |
326   +-----------------------------+
327   | QCow2 cluster payload       |
328   .                             .
329   .                             .
330   .                             .
331   |                             |
332   +-----------------------------+
333
334 == Data encryption ==
335
336 When an encryption method is requested in the header, the image payload
337 data must be encrypted/decrypted on every write/read. The image headers
338 and metadata are never encrypted.
339
340 The algorithms used for encryption vary depending on the method
341
342  - AES:
343
344    The AES cipher, in CBC mode, with 256 bit keys.
345
346    Initialization vectors generated using plain64 method, with
347    the virtual disk sector as the input tweak.
348
349    This format is no longer supported in QEMU system emulators, due
350    to a number of design flaws affecting its security. It is only
351    supported in the command line tools for the sake of back compatibility
352    and data liberation.
353
354  - LUKS:
355
356    The algorithms are specified in the LUKS header.
357
358    Initialization vectors generated using the method specified
359    in the LUKS header, with the physical disk sector as the
360    input tweak.
361
362 == Host cluster management ==
363
364 qcow2 manages the allocation of host clusters by maintaining a reference count
365 for each host cluster. A refcount of 0 means that the cluster is free, 1 means
366 that it is used, and >= 2 means that it is used and any write access must
367 perform a COW (copy on write) operation.
368
369 The refcounts are managed in a two-level table. The first level is called
370 refcount table and has a variable size (which is stored in the header). The
371 refcount table can cover multiple clusters, however it needs to be contiguous
372 in the image file.
373
374 It contains pointers to the second level structures which are called refcount
375 blocks and are exactly one cluster in size.
376
377 Although a large enough refcount table can reserve clusters past 64 PB
378 (56 bits) (assuming the underlying protocol can even be sized that
379 large), note that some qcow2 metadata such as L1/L2 tables must point
380 to clusters prior to that point.
381
382 Note: qemu has an implementation limit of 8 MB as the maximum refcount
383 table size.  With a 2 MB cluster size and a default refcount_order of
384 4, it is unable to reference host resources beyond 2 EB (61 bits); in
385 the worst case, with a 512 cluster size and refcount_order of 6, it is
386 unable to access beyond 32 GB (35 bits).
387
388 Given an offset into the image file, the refcount of its cluster can be
389 obtained as follows:
390
391     refcount_block_entries = (cluster_size * 8 / refcount_bits)
392
393     refcount_block_index = (offset / cluster_size) % refcount_block_entries
394     refcount_table_index = (offset / cluster_size) / refcount_block_entries
395
396     refcount_block = load_cluster(refcount_table[refcount_table_index]);
397     return refcount_block[refcount_block_index];
398
399 Refcount table entry:
400
401     Bit  0 -  8:    Reserved (set to 0)
402
403          9 - 63:    Bits 9-63 of the offset into the image file at which the
404                     refcount block starts. Must be aligned to a cluster
405                     boundary.
406
407                     If this is 0, the corresponding refcount block has not yet
408                     been allocated. All refcounts managed by this refcount block
409                     are 0.
410
411 Refcount block entry (x = refcount_bits - 1):
412
413     Bit  0 -  x:    Reference count of the cluster. If refcount_bits implies a
414                     sub-byte width, note that bit 0 means the least significant
415                     bit in this context.
416
417
418 == Cluster mapping ==
419
420 Just as for refcounts, qcow2 uses a two-level structure for the mapping of
421 guest clusters to host clusters. They are called L1 and L2 table.
422
423 The L1 table has a variable size (stored in the header) and may use multiple
424 clusters, however it must be contiguous in the image file. L2 tables are
425 exactly one cluster in size.
426
427 The L1 and L2 tables have implications on the maximum virtual file
428 size; for a given L1 table size, a larger cluster size is required for
429 the guest to have access to more space.  Furthermore, a virtual
430 cluster must currently map to a host offset below 64 PB (56 bits)
431 (although this limit could be relaxed by putting reserved bits into
432 use).  Additionally, as cluster size increases, the maximum host
433 offset for a compressed cluster is reduced (a 2M cluster size requires
434 compressed clusters to reside below 512 TB (49 bits), and this limit
435 cannot be relaxed without an incompatible layout change).
436
437 Given an offset into the virtual disk, the offset into the image file can be
438 obtained as follows:
439
440     l2_entries = (cluster_size / sizeof(uint64_t))
441
442     l2_index = (offset / cluster_size) % l2_entries
443     l1_index = (offset / cluster_size) / l2_entries
444
445     l2_table = load_cluster(l1_table[l1_index]);
446     cluster_offset = l2_table[l2_index];
447
448     return cluster_offset + (offset % cluster_size)
449
450 L1 table entry:
451
452     Bit  0 -  8:    Reserved (set to 0)
453
454          9 - 55:    Bits 9-55 of the offset into the image file at which the L2
455                     table starts. Must be aligned to a cluster boundary. If the
456                     offset is 0, the L2 table and all clusters described by this
457                     L2 table are unallocated.
458
459         56 - 62:    Reserved (set to 0)
460
461              63:    0 for an L2 table that is unused or requires COW, 1 if its
462                     refcount is exactly one. This information is only accurate
463                     in the active L1 table.
464
465 L2 table entry:
466
467     Bit  0 -  61:   Cluster descriptor
468
469               62:   0 for standard clusters
470                     1 for compressed clusters
471
472               63:   0 for clusters that are unused, compressed or require COW.
473                     1 for standard clusters whose refcount is exactly one.
474                     This information is only accurate in L2 tables
475                     that are reachable from the active L1 table.
476
477                     With external data files, all guest clusters have an
478                     implicit refcount of 1 (because of the fixed host = guest
479                     mapping for guest cluster offsets), so this bit should be 1
480                     for all allocated clusters.
481
482 Standard Cluster Descriptor:
483
484     Bit       0:    If set to 1, the cluster reads as all zeros. The host
485                     cluster offset can be used to describe a preallocation,
486                     but it won't be used for reading data from this cluster,
487                     nor is data read from the backing file if the cluster is
488                     unallocated.
489
490                     With version 2, this is always 0.
491
492          1 -  8:    Reserved (set to 0)
493
494          9 - 55:    Bits 9-55 of host cluster offset. Must be aligned to a
495                     cluster boundary. If the offset is 0 and bit 63 is clear,
496                     the cluster is unallocated. The offset may only be 0 with
497                     bit 63 set (indicating a host cluster offset of 0) when an
498                     external data file is used.
499
500         56 - 61:    Reserved (set to 0)
501
502
503 Compressed Clusters Descriptor (x = 62 - (cluster_bits - 8)):
504
505     Bit  0 - x-1:   Host cluster offset. This is usually _not_ aligned to a
506                     cluster or sector boundary!  If cluster_bits is
507                     small enough that this field includes bits beyond
508                     55, those upper bits must be set to 0.
509
510          x - 61:    Number of additional 512-byte sectors used for the
511                     compressed data, beyond the sector containing the offset
512                     in the previous field. Some of these sectors may reside
513                     in the next contiguous host cluster.
514
515                     Note that the compressed data does not necessarily occupy
516                     all of the bytes in the final sector; rather, decompression
517                     stops when it has produced a cluster of data.
518
519                     Another compressed cluster may map to the tail of the final
520                     sector used by this compressed cluster.
521
522 If a cluster is unallocated, read requests shall read the data from the backing
523 file (except if bit 0 in the Standard Cluster Descriptor is set). If there is
524 no backing file or the backing file is smaller than the image, they shall read
525 zeros for all parts that are not covered by the backing file.
526
527
528 == Snapshots ==
529
530 qcow2 supports internal snapshots. Their basic principle of operation is to
531 switch the active L1 table, so that a different set of host clusters are
532 exposed to the guest.
533
534 When creating a snapshot, the L1 table should be copied and the refcount of all
535 L2 tables and clusters reachable from this L1 table must be increased, so that
536 a write causes a COW and isn't visible in other snapshots.
537
538 When loading a snapshot, bit 63 of all entries in the new active L1 table and
539 all L2 tables referenced by it must be reconstructed from the refcount table
540 as it doesn't need to be accurate in inactive L1 tables.
541
542 A directory of all snapshots is stored in the snapshot table, a contiguous area
543 in the image file, whose starting offset and length are given by the header
544 fields snapshots_offset and nb_snapshots. The entries of the snapshot table
545 have variable length, depending on the length of ID, name and extra data.
546
547 Snapshot table entry:
548
549     Byte 0 -  7:    Offset into the image file at which the L1 table for the
550                     snapshot starts. Must be aligned to a cluster boundary.
551
552          8 - 11:    Number of entries in the L1 table of the snapshots
553
554         12 - 13:    Length of the unique ID string describing the snapshot
555
556         14 - 15:    Length of the name of the snapshot
557
558         16 - 19:    Time at which the snapshot was taken in seconds since the
559                     Epoch
560
561         20 - 23:    Subsecond part of the time at which the snapshot was taken
562                     in nanoseconds
563
564         24 - 31:    Time that the guest was running until the snapshot was
565                     taken in nanoseconds
566
567         32 - 35:    Size of the VM state in bytes. 0 if no VM state is saved.
568                     If there is VM state, it starts at the first cluster
569                     described by first L1 table entry that doesn't describe a
570                     regular guest cluster (i.e. VM state is stored like guest
571                     disk content, except that it is stored at offsets that are
572                     larger than the virtual disk presented to the guest)
573
574         36 - 39:    Size of extra data in the table entry (used for future
575                     extensions of the format)
576
577         variable:   Extra data for future extensions. Unknown fields must be
578                     ignored. Currently defined are (offset relative to snapshot
579                     table entry):
580
581                     Byte 40 - 47:   Size of the VM state in bytes. 0 if no VM
582                                     state is saved. If this field is present,
583                                     the 32-bit value in bytes 32-35 is ignored.
584
585                     Byte 48 - 55:   Virtual disk size of the snapshot in bytes
586
587                     Version 3 images must include extra data at least up to
588                     byte 55.
589
590         variable:   Unique ID string for the snapshot (not null terminated)
591
592         variable:   Name of the snapshot (not null terminated)
593
594         variable:   Padding to round up the snapshot table entry size to the
595                     next multiple of 8.
596
597
598 == Bitmaps ==
599
600 As mentioned above, the bitmaps extension provides the ability to store bitmaps
601 related to a virtual disk. This section describes how these bitmaps are stored.
602
603 All stored bitmaps are related to the virtual disk stored in the same image, so
604 each bitmap size is equal to the virtual disk size.
605
606 Each bit of the bitmap is responsible for strictly defined range of the virtual
607 disk. For bit number bit_nr the corresponding range (in bytes) will be:
608
609     [bit_nr * bitmap_granularity .. (bit_nr + 1) * bitmap_granularity - 1]
610
611 Granularity is a property of the concrete bitmap, see below.
612
613
614 === Bitmap directory ===
615
616 Each bitmap saved in the image is described in a bitmap directory entry. The
617 bitmap directory is a contiguous area in the image file, whose starting offset
618 and length are given by the header extension fields bitmap_directory_offset and
619 bitmap_directory_size. The entries of the bitmap directory have variable
620 length, depending on the lengths of the bitmap name and extra data.
621
622 Structure of a bitmap directory entry:
623
624     Byte 0 -  7:    bitmap_table_offset
625                     Offset into the image file at which the bitmap table
626                     (described below) for the bitmap starts. Must be aligned to
627                     a cluster boundary.
628
629          8 - 11:    bitmap_table_size
630                     Number of entries in the bitmap table of the bitmap.
631
632         12 - 15:    flags
633                     Bit
634                       0: in_use
635                          The bitmap was not saved correctly and may be
636                          inconsistent. Although the bitmap metadata is still
637                          well-formed from a qcow2 perspective, the metadata
638                          (such as the auto flag or bitmap size) or data
639                          contents may be outdated.
640
641                       1: auto
642                          The bitmap must reflect all changes of the virtual
643                          disk by any application that would write to this qcow2
644                          file (including writes, snapshot switching, etc.). The
645                          type of this bitmap must be 'dirty tracking bitmap'.
646
647                       2: extra_data_compatible
648                          This flags is meaningful when the extra data is
649                          unknown to the software (currently any extra data is
650                          unknown to Qemu).
651                          If it is set, the bitmap may be used as expected, extra
652                          data must be left as is.
653                          If it is not set, the bitmap must not be used, but
654                          both it and its extra data be left as is.
655
656                     Bits 3 - 31 are reserved and must be 0.
657
658              16:    type
659                     This field describes the sort of the bitmap.
660                     Values:
661                       1: Dirty tracking bitmap
662
663                     Values 0, 2 - 255 are reserved.
664
665              17:    granularity_bits
666                     Granularity bits. Valid values: 0 - 63.
667
668                     Note: Qemu currently supports only values 9 - 31.
669
670                     Granularity is calculated as
671                         granularity = 1 << granularity_bits
672
673                     A bitmap's granularity is how many bytes of the image
674                     accounts for one bit of the bitmap.
675
676         18 - 19:    name_size
677                     Size of the bitmap name. Must be non-zero.
678
679                     Note: Qemu currently doesn't support values greater than
680                     1023.
681
682         20 - 23:    extra_data_size
683                     Size of type-specific extra data.
684
685                     For now, as no extra data is defined, extra_data_size is
686                     reserved and should be zero. If it is non-zero the
687                     behavior is defined by extra_data_compatible flag.
688
689         variable:   extra_data
690                     Extra data for the bitmap, occupying extra_data_size bytes.
691                     Extra data must never contain references to clusters or in
692                     some other way allocate additional clusters.
693
694         variable:   name
695                     The name of the bitmap (not null terminated), occupying
696                     name_size bytes. Must be unique among all bitmap names
697                     within the bitmaps extension.
698
699         variable:   Padding to round up the bitmap directory entry size to the
700                     next multiple of 8. All bytes of the padding must be zero.
701
702
703 === Bitmap table ===
704
705 Each bitmap is stored using a one-level structure (as opposed to two-level
706 structures like for refcounts and guest clusters mapping) for the mapping of
707 bitmap data to host clusters. This structure is called the bitmap table.
708
709 Each bitmap table has a variable size (stored in the bitmap directory entry)
710 and may use multiple clusters, however, it must be contiguous in the image
711 file.
712
713 Structure of a bitmap table entry:
714
715     Bit       0:    Reserved and must be zero if bits 9 - 55 are non-zero.
716                     If bits 9 - 55 are zero:
717                       0: Cluster should be read as all zeros.
718                       1: Cluster should be read as all ones.
719
720          1 -  8:    Reserved and must be zero.
721
722          9 - 55:    Bits 9 - 55 of the host cluster offset. Must be aligned to
723                     a cluster boundary. If the offset is 0, the cluster is
724                     unallocated; in that case, bit 0 determines how this
725                     cluster should be treated during reads.
726
727         56 - 63:    Reserved and must be zero.
728
729
730 === Bitmap data ===
731
732 As noted above, bitmap data is stored in separate clusters, described by the
733 bitmap table. Given an offset (in bytes) into the bitmap data, the offset into
734 the image file can be obtained as follows:
735
736     image_offset(bitmap_data_offset) =
737         bitmap_table[bitmap_data_offset / cluster_size] +
738             (bitmap_data_offset % cluster_size)
739
740 This offset is not defined if bits 9 - 55 of bitmap table entry are zero (see
741 above).
742
743 Given an offset byte_nr into the virtual disk and the bitmap's granularity, the
744 bit offset into the image file to the corresponding bit of the bitmap can be
745 calculated like this:
746
747     bit_offset(byte_nr) =
748         image_offset(byte_nr / granularity / 8) * 8 +
749             (byte_nr / granularity) % 8
750
751 If the size of the bitmap data is not a multiple of the cluster size then the
752 last cluster of the bitmap data contains some unused tail bits. These bits must
753 be zero.
754
755
756 === Dirty tracking bitmaps ===
757
758 Bitmaps with 'type' field equal to one are dirty tracking bitmaps.
759
760 When the virtual disk is in use dirty tracking bitmap may be 'enabled' or
761 'disabled'. While the bitmap is 'enabled', all writes to the virtual disk
762 should be reflected in the bitmap. A set bit in the bitmap means that the
763 corresponding range of the virtual disk (see above) was written to while the
764 bitmap was 'enabled'. An unset bit means that this range was not written to.
765
766 The software doesn't have to sync the bitmap in the image file with its
767 representation in RAM after each write or metadata change. Flag 'in_use'
768 should be set while the bitmap is not synced.
769
770 In the image file the 'enabled' state is reflected by the 'auto' flag. If this
771 flag is set, the software must consider the bitmap as 'enabled' and start
772 tracking virtual disk changes to this bitmap from the first write to the
773 virtual disk. If this flag is not set then the bitmap is disabled.