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