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