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