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