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