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