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