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.
7 Likewise, the virtual disk as seen by the guest is divided into (guest)
8 clusters of the same size.
10 All numbers in qcow2 are stored in Big Endian byte order.
15 The first cluster of a qcow2 image contains the file header:
18 QCOW magic string ("QFI\xfb")
21 Version number (valid values are 2 and 3)
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.
28 Note: backing files are incompatible with raw external data
29 files (auto-clear feature bit 1).
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
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).
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.
45 Note: if the image has Extended L2 Entries then cluster_bits
46 must be at least 14 (i.e. 16384 byte clusters).
49 Virtual disk size in bytes.
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
68 Number of entries in the active L1 table
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.
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.
78 56 - 59: refcount_table_clusters
79 Number of clusters that the refcount table occupies
82 Number of snapshots contained in the image
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.
88 For version 2, the header is exactly 72 bytes in length, and finishes here.
89 For version 3 or higher, the header length is at least 104 bytes, including
90 the next fields through header_length.
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.
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
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
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.
115 An External Data File Name header extension may
116 be present if this bit is set.
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.
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.
128 Bits 5-63: Reserved (set to 0)
130 80 - 87: compatible_features
131 Bitmask of compatible features. An implementation can
132 safely ignore any unknown bits that are set.
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.
139 Bits 1-63: Reserved (set to 0)
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.
146 Bit 0: Bitmaps extension bit
147 This bit indicates consistency for the bitmaps
150 It is an error if this bit is set without the
151 bitmaps extension present.
153 If the bitmaps extension is present but this
154 bit is unset, the bitmaps extension data must be
155 considered inconsistent.
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.
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.
168 This bit may only be set if the External Data
169 File bit (incompatible feature bit 1) is also
172 Bits 2-63: Reserved (set to 0)
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).
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
188 === Additional fields (version 3 and higher) ===
190 In general, these fields are optional and may be safely ignored by the software,
191 as well as filled by zeros (which is equal to field absence), if software needs
192 to set field B, but does not care about field A which precedes B. More
193 formally, additional fields have the following compatibility rules:
195 1. If the value of the additional field must not be ignored for correct
196 handling of the file, it will be accompanied by a corresponding incompatible
199 2. If there are no unrecognized incompatible feature bits set, an unknown
200 additional field may be safely ignored other than preserving its value when
201 rewriting the image header.
203 3. An explicit value of 0 will have the same behavior as when the field is not
204 present*, if not altered by a specific incompatible bit.
206 *. A field is considered not present when header_length is less than or equal
207 to the field's offset. Also, all additional fields are not present for
210 104: compression_type
212 Defines the compression method used for compressed clusters.
213 All compressed clusters in an image use the same compression
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).
221 Available compression type values:
222 0: deflate <https://www.ietf.org/rfc/rfc1951.txt>
223 1: zstd <http://github.com/facebook/zstd>
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.
229 105 - 111: Padding, contents defined below.
231 === Header padding ===
233 @header_length must be a multiple of 8, which means that if the end of the last
234 additional field is not aligned, some padding is needed. This padding must be
235 zeroed, so that if some existing (or future) additional field will fall into
236 the padding, it will be interpreted accordingly to point [3.] of the previous
237 paragraph, i.e. in the same manner as when this field is not present.
240 === Header extensions ===
242 Directly after the image header, optional sections called header extensions can
243 be stored. Each extension has a structure like the following:
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
255 4 - 7: Length of the header extension data
257 8 - n: Header extension data
259 n - m: Padding to round up the header extension size to the next
262 Unless stated otherwise, each header extension type shall appear at most once
265 If the image has a backing file then the backing file name should be stored in
266 the remaining space between the end of the header extension area and the end of
267 the first cluster. It is not allowed to store other data here, so that an
268 implementation can safely modify the header and add extensions without harming
269 data of compatible features that it doesn't support. Compatible features that
270 need space for additional data can use a header extension.
273 == String header extensions ==
275 Some header extensions (such as the backing file format name and the external
276 data file name) are just a single string. In this case, the header extension
277 length is the string length and the string is not '\0' terminated. (The header
278 extension padding can make it look like a string is '\0' terminated, but
279 neither is padding always necessary nor is there a guarantee that zero bytes
280 are used for padding.)
283 == Feature name table ==
285 The feature name table is an optional header extension that contains the name
286 for features used by the image. It can be used by applications that don't know
287 the respective feature (e.g. because the feature was introduced only later) to
288 display a useful error message.
290 The number of entries in the feature name table is determined by the length of
291 the header extension data. Each entry look like this:
293 Byte 0: Type of feature (select feature bitmap)
294 0: Incompatible feature
295 1: Compatible feature
298 1: Bit number within the selected feature bitmap (valid
301 2 - 47: Feature name (padded with zeros, but not necessarily null
302 terminated if it has full length)
305 == Bitmaps extension ==
307 The bitmaps extension is an optional header extension. It provides the ability
308 to store bitmaps related to a virtual disk. For now, there is only one bitmap
309 type: the dirty tracking bitmap, which tracks virtual disk changes from some
312 The data of the extension should be considered consistent only if the
313 corresponding auto-clear feature bit is set, see autoclear_features above.
315 The fields of the bitmaps extension are:
317 Byte 0 - 3: nb_bitmaps
318 The number of bitmaps contained in the image. Must be
319 greater than or equal to 1.
321 Note: QEMU currently only supports up to 65535 bitmaps per
324 4 - 7: Reserved, must be zero.
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.
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.
334 == Full disk encryption header pointer ==
336 The full disk encryption header must be present if, and only if, the
337 'crypt_method' header requires metadata. Currently this is only true
338 of the 'LUKS' crypt method. The header extension must be absent for
341 This header provides the offset at which the crypt method can store
342 its additional data, as well as the length of such data.
344 Byte 0 - 7: Offset into the image file at which the encryption
345 header starts in bytes. Must be aligned to a cluster
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
354 For the LUKS crypt method, the encryption header works as follows.
356 The first 592 bytes of the header clusters will contain the LUKS
357 partition header. This is then followed by the key material data areas.
358 The size of the key material data areas is determined by the number of
359 stripes in the key slot and key size. Refer to the LUKS format
360 specification ('docs/on-disk-format.pdf' in the cryptsetup source
361 package) for details of the LUKS partition header format.
363 In the LUKS partition header, the "payload-offset" field will be
364 calculated as normal for the LUKS spec. ie the size of the LUKS
365 header, plus key material regions, plus padding, relative to the
366 start of the LUKS header. This offset value is not required to be
367 qcow2 cluster aligned. Its value is currently never used in the
368 context of qcow2, since the qcow2 file format itself defines where
369 the real payload offset is, but none the less a valid payload offset
370 should always be present.
372 In the LUKS key slots header, the "key-material-offset" is relative
373 to the start of the LUKS header clusters in the qcow2 container,
374 not the start of the qcow2 file.
376 Logically the layout looks like
378 +-----------------------------+
380 | QCow2 header extension X |
381 | QCow2 header extension FDE |
382 | QCow2 header extension ... |
383 | QCow2 header extension Z |
384 +-----------------------------+
385 | ....other QCow2 tables.... |
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 |
406 +-----------------------------+
408 == Data encryption ==
410 When an encryption method is requested in the header, the image payload
411 data must be encrypted/decrypted on every write/read. The image headers
412 and metadata are never encrypted.
414 The algorithms used for encryption vary depending on the method
418 The AES cipher, in CBC mode, with 256 bit keys.
420 Initialization vectors generated using plain64 method, with
421 the virtual disk sector as the input tweak.
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
430 The algorithms are specified in the LUKS header.
432 Initialization vectors generated using the method specified
433 in the LUKS header, with the physical disk sector as the
436 == Host cluster management ==
438 qcow2 manages the allocation of host clusters by maintaining a reference count
439 for each host cluster. A refcount of 0 means that the cluster is free, 1 means
440 that it is used, and >= 2 means that it is used and any write access must
441 perform a COW (copy on write) operation.
443 The refcounts are managed in a two-level table. The first level is called
444 refcount table and has a variable size (which is stored in the header). The
445 refcount table can cover multiple clusters, however it needs to be contiguous
448 It contains pointers to the second level structures which are called refcount
449 blocks and are exactly one cluster in size.
451 Although a large enough refcount table can reserve clusters past 64 PB
452 (56 bits) (assuming the underlying protocol can even be sized that
453 large), note that some qcow2 metadata such as L1/L2 tables must point
454 to clusters prior to that point.
456 Note: qemu has an implementation limit of 8 MB as the maximum refcount
457 table size. With a 2 MB cluster size and a default refcount_order of
458 4, it is unable to reference host resources beyond 2 EB (61 bits); in
459 the worst case, with a 512 cluster size and refcount_order of 6, it is
460 unable to access beyond 32 GB (35 bits).
462 Given an offset into the image file, the refcount of its cluster can be
465 refcount_block_entries = (cluster_size * 8 / refcount_bits)
467 refcount_block_index = (offset / cluster_size) % refcount_block_entries
468 refcount_table_index = (offset / cluster_size) / refcount_block_entries
470 refcount_block = load_cluster(refcount_table[refcount_table_index]);
471 return refcount_block[refcount_block_index];
473 Refcount table entry:
475 Bit 0 - 8: Reserved (set to 0)
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
481 If this is 0, the corresponding refcount block has not yet
482 been allocated. All refcounts managed by this refcount block
485 Refcount block entry (x = refcount_bits - 1):
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
492 == Cluster mapping ==
494 Just as for refcounts, qcow2 uses a two-level structure for the mapping of
495 guest clusters to host clusters. They are called L1 and L2 table.
497 The L1 table has a variable size (stored in the header) and may use multiple
498 clusters, however it must be contiguous in the image file. L2 tables are
499 exactly one cluster in size.
501 The L1 and L2 tables have implications on the maximum virtual file
502 size; for a given L1 table size, a larger cluster size is required for
503 the guest to have access to more space. Furthermore, a virtual
504 cluster must currently map to a host offset below 64 PB (56 bits)
505 (although this limit could be relaxed by putting reserved bits into
506 use). Additionally, as cluster size increases, the maximum host
507 offset for a compressed cluster is reduced (a 2M cluster size requires
508 compressed clusters to reside below 512 TB (49 bits), and this limit
509 cannot be relaxed without an incompatible layout change).
511 Given an offset into the virtual disk, the offset into the image file can be
514 l2_entries = (cluster_size / sizeof(uint64_t)) [*]
516 l2_index = (offset / cluster_size) % l2_entries
517 l1_index = (offset / cluster_size) / l2_entries
519 l2_table = load_cluster(l1_table[l1_index]);
520 cluster_offset = l2_table[l2_index];
522 return cluster_offset + (offset % cluster_size)
524 [*] this changes if Extended L2 Entries are enabled, see next section
528 Bit 0 - 8: Reserved (set to 0)
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.
535 56 - 62: Reserved (set to 0)
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.
543 Bit 0 - 61: Cluster descriptor
545 62: 0 for standard clusters
546 1 for compressed clusters
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.
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.
558 Standard Cluster Descriptor:
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
566 With version 2 or with extended L2 entries (see the next
567 section), this is always 0.
569 1 - 8: Reserved (set to 0)
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.
577 56 - 61: Reserved (set to 0)
580 Compressed Clusters Descriptor (x = 62 - (cluster_bits - 8)):
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.
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.
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.
596 Another compressed cluster may map to the tail of the final
597 sector used by this compressed cluster.
599 If a cluster is unallocated, read requests shall read the data from the backing
600 file (except if bit 0 in the Standard Cluster Descriptor is set). If there is
601 no backing file or the backing file is smaller than the image, they shall read
602 zeros for all parts that are not covered by the backing file.
604 == Extended L2 Entries ==
606 An image uses Extended L2 Entries if bit 4 is set on the incompatible_features
609 In these images standard data clusters are divided into 32 subclusters of the
610 same size. They are contiguous and start from the beginning of the cluster.
611 Subclusters can be allocated independently and the L2 entry contains information
612 indicating the status of each one of them. Compressed data clusters don't have
613 subclusters so they are treated the same as in images without this feature.
615 The size of an extended L2 entry is 128 bits so the number of entries per table
616 is calculated using this formula:
618 l2_entries = (cluster_size / (2 * sizeof(uint64_t)))
620 The first 64 bits have the same format as the standard L2 table entry described
621 in the previous section, with the exception of bit 0 of the standard cluster
624 The last 64 bits contain a subcluster allocation bitmap with this format:
626 Subcluster Allocation Bitmap (for standard clusters):
628 Bit 0 - 31: Allocation status (one bit per subcluster)
630 1: the subcluster is allocated. In this case the
631 host cluster offset field must contain a valid
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.
637 Bits are assigned starting from the least significant
638 one (i.e. bit x is used for subcluster x).
640 32 - 63 Subcluster reads as zeros (one bit per subcluster)
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.
647 Bits are assigned starting from the least significant
648 one (i.e. bit x is used for subcluster x - 32).
650 Subcluster Allocation Bitmap (for compressed clusters):
652 Bit 0 - 63: Reserved (set to 0)
653 Compressed clusters don't have subclusters,
654 so this field is not used.
658 qcow2 supports internal snapshots. Their basic principle of operation is to
659 switch the active L1 table, so that a different set of host clusters are
660 exposed to the guest.
662 When creating a snapshot, the L1 table should be copied and the refcount of all
663 L2 tables and clusters reachable from this L1 table must be increased, so that
664 a write causes a COW and isn't visible in other snapshots.
666 When loading a snapshot, bit 63 of all entries in the new active L1 table and
667 all L2 tables referenced by it must be reconstructed from the refcount table
668 as it doesn't need to be accurate in inactive L1 tables.
670 A directory of all snapshots is stored in the snapshot table, a contiguous area
671 in the image file, whose starting offset and length are given by the header
672 fields snapshots_offset and nb_snapshots. The entries of the snapshot table
673 have variable length, depending on the length of ID, name and extra data.
675 Snapshot table entry:
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.
680 8 - 11: Number of entries in the L1 table of the snapshots
682 12 - 13: Length of the unique ID string describing the snapshot
684 14 - 15: Length of the name of the snapshot
686 16 - 19: Time at which the snapshot was taken in seconds since the
689 20 - 23: Subsecond part of the time at which the snapshot was taken
692 24 - 31: Time that the guest was running until the snapshot was
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)
702 36 - 39: Size of extra data in the table entry (used for future
703 extensions of the format)
705 variable: Extra data for future extensions. Unknown fields must be
706 ignored. Currently defined are (offset relative to snapshot
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.
713 Byte 48 - 55: Virtual disk size of the snapshot in bytes
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
720 Version 3 images must include extra data at least up to
723 variable: Unique ID string for the snapshot (not null terminated)
725 variable: Name of the snapshot (not null terminated)
727 variable: Padding to round up the snapshot table entry size to the
733 As mentioned above, the bitmaps extension provides the ability to store bitmaps
734 related to a virtual disk. This section describes how these bitmaps are stored.
736 All stored bitmaps are related to the virtual disk stored in the same image, so
737 each bitmap size is equal to the virtual disk size.
739 Each bit of the bitmap is responsible for strictly defined range of the virtual
740 disk. For bit number bit_nr the corresponding range (in bytes) will be:
742 [bit_nr * bitmap_granularity .. (bit_nr + 1) * bitmap_granularity - 1]
744 Granularity is a property of the concrete bitmap, see below.
747 === Bitmap directory ===
749 Each bitmap saved in the image is described in a bitmap directory entry. The
750 bitmap directory is a contiguous area in the image file, whose starting offset
751 and length are given by the header extension fields bitmap_directory_offset and
752 bitmap_directory_size. The entries of the bitmap directory have variable
753 length, depending on the lengths of the bitmap name and extra data.
755 Structure of a bitmap directory entry:
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
762 8 - 11: bitmap_table_size
763 Number of entries in the bitmap table of the bitmap.
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.
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'.
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
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.
789 Bits 3 - 31 are reserved and must be 0.
792 This field describes the sort of the bitmap.
794 1: Dirty tracking bitmap
796 Values 0, 2 - 255 are reserved.
799 Granularity bits. Valid values: 0 - 63.
801 Note: QEMU currently supports only values 9 - 31.
803 Granularity is calculated as
804 granularity = 1 << granularity_bits
806 A bitmap's granularity is how many bytes of the image
807 accounts for one bit of the bitmap.
810 Size of the bitmap name. Must be non-zero.
812 Note: QEMU currently doesn't support values greater than
815 20 - 23: extra_data_size
816 Size of type-specific extra data.
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.
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.
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.
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.
838 Each bitmap is stored using a one-level structure (as opposed to two-level
839 structures like for refcounts and guest clusters mapping) for the mapping of
840 bitmap data to host clusters. This structure is called the bitmap table.
842 Each bitmap table has a variable size (stored in the bitmap directory entry)
843 and may use multiple clusters, however, it must be contiguous in the image
846 Structure of a bitmap table entry:
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.
853 1 - 8: Reserved and must be zero.
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.
860 56 - 63: Reserved and must be zero.
865 As noted above, bitmap data is stored in separate clusters, described by the
866 bitmap table. Given an offset (in bytes) into the bitmap data, the offset into
867 the image file can be obtained as follows:
869 image_offset(bitmap_data_offset) =
870 bitmap_table[bitmap_data_offset / cluster_size] +
871 (bitmap_data_offset % cluster_size)
873 This offset is not defined if bits 9 - 55 of bitmap table entry are zero (see
876 Given an offset byte_nr into the virtual disk and the bitmap's granularity, the
877 bit offset into the image file to the corresponding bit of the bitmap can be
878 calculated like this:
880 bit_offset(byte_nr) =
881 image_offset(byte_nr / granularity / 8) * 8 +
882 (byte_nr / granularity) % 8
884 If the size of the bitmap data is not a multiple of the cluster size then the
885 last cluster of the bitmap data contains some unused tail bits. These bits must
889 === Dirty tracking bitmaps ===
891 Bitmaps with 'type' field equal to one are dirty tracking bitmaps.
893 When 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
895 should be reflected in the bitmap. A set bit in the bitmap means that the
896 corresponding range of the virtual disk (see above) was written to while the
897 bitmap was 'enabled'. An unset bit means that this range was not written to.
899 The software doesn't have to sync the bitmap in the image file with its
900 representation in RAM after each write or metadata change. Flag 'in_use'
901 should be set while the bitmap is not synced.
903 In the image file the 'enabled' state is reflected by the 'auto' flag. If this
904 flag is set, the software must consider the bitmap as 'enabled' and start
905 tracking virtual disk changes to this bitmap from the first write to the
906 virtual disk. If this flag is not set then the bitmap is disabled.