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