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