e88153ea9a
Be more specific about the string representation in header extensions. Suggested-by: Stefan Hajnoczi <stefanha@redhat.com> Signed-off-by: Kevin Wolf <kwolf@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com> Reviewed-by: Stefan Hajnoczi <stefanha@redhat.com>
771 lines
32 KiB
Plaintext
771 lines
32 KiB
Plaintext
== General ==
|
|
|
|
A qcow2 image file is organized in units of constant size, which are called
|
|
(host) clusters. A cluster is the unit in which all allocations are done,
|
|
both for actual guest data and for image metadata.
|
|
|
|
Likewise, the virtual disk as seen by the guest is divided into (guest)
|
|
clusters of the same size.
|
|
|
|
All numbers in qcow2 are stored in Big Endian byte order.
|
|
|
|
|
|
== Header ==
|
|
|
|
The first cluster of a qcow2 image contains the file header:
|
|
|
|
Byte 0 - 3: magic
|
|
QCOW magic string ("QFI\xfb")
|
|
|
|
4 - 7: version
|
|
Version number (valid values are 2 and 3)
|
|
|
|
8 - 15: backing_file_offset
|
|
Offset into the image file at which the backing file name
|
|
is stored (NB: The string is not null terminated). 0 if the
|
|
image doesn't have a backing file.
|
|
|
|
16 - 19: backing_file_size
|
|
Length of the backing file name in bytes. Must not be
|
|
longer than 1023 bytes. Undefined if the image doesn't have
|
|
a backing file.
|
|
|
|
20 - 23: cluster_bits
|
|
Number of bits that are used for addressing an offset
|
|
within a cluster (1 << cluster_bits is the cluster size).
|
|
Must not be less than 9 (i.e. 512 byte clusters).
|
|
|
|
Note: qemu as of today has an implementation limit of 2 MB
|
|
as the maximum cluster size and won't be able to open images
|
|
with larger cluster sizes.
|
|
|
|
24 - 31: size
|
|
Virtual disk size in bytes.
|
|
|
|
Note: qemu has an implementation limit of 32 MB as
|
|
the maximum L1 table size. With a 2 MB cluster
|
|
size, it is unable to populate a virtual cluster
|
|
beyond 2 EB (61 bits); with a 512 byte cluster
|
|
size, it is unable to populate a virtual size
|
|
larger than 128 GB (37 bits). Meanwhile, L1/L2
|
|
table layouts limit an image to no more than 64 PB
|
|
(56 bits) of populated clusters, and an image may
|
|
hit other limits first (such as a file system's
|
|
maximum size).
|
|
|
|
32 - 35: crypt_method
|
|
0 for no encryption
|
|
1 for AES encryption
|
|
2 for LUKS encryption
|
|
|
|
36 - 39: l1_size
|
|
Number of entries in the active L1 table
|
|
|
|
40 - 47: l1_table_offset
|
|
Offset into the image file at which the active L1 table
|
|
starts. Must be aligned to a cluster boundary.
|
|
|
|
48 - 55: refcount_table_offset
|
|
Offset into the image file at which the refcount table
|
|
starts. Must be aligned to a cluster boundary.
|
|
|
|
56 - 59: refcount_table_clusters
|
|
Number of clusters that the refcount table occupies
|
|
|
|
60 - 63: nb_snapshots
|
|
Number of snapshots contained in the image
|
|
|
|
64 - 71: snapshots_offset
|
|
Offset into the image file at which the snapshot table
|
|
starts. Must be aligned to a cluster boundary.
|
|
|
|
If the version is 3 or higher, the header has the following additional fields.
|
|
For version 2, the values are assumed to be zero, unless specified otherwise
|
|
in the description of a field.
|
|
|
|
72 - 79: incompatible_features
|
|
Bitmask of incompatible features. An implementation must
|
|
fail to open an image if an unknown bit is set.
|
|
|
|
Bit 0: Dirty bit. If this bit is set then refcounts
|
|
may be inconsistent, make sure to scan L1/L2
|
|
tables to repair refcounts before accessing the
|
|
image.
|
|
|
|
Bit 1: Corrupt bit. If this bit is set then any data
|
|
structure may be corrupt and the image must not
|
|
be written to (unless for regaining
|
|
consistency).
|
|
|
|
Bit 2: External data file bit. If this bit is set, an
|
|
external data file is used. Guest clusters are
|
|
then stored in the external data file. For such
|
|
images, clusters in the external data file are
|
|
not refcounted. The offset field in the
|
|
Standard Cluster Descriptor must match the
|
|
guest offset and neither compressed clusters
|
|
nor internal snapshots are supported.
|
|
|
|
An External Data File Name header extension may
|
|
be present if this bit is set.
|
|
|
|
Bits 3-63: Reserved (set to 0)
|
|
|
|
80 - 87: compatible_features
|
|
Bitmask of compatible features. An implementation can
|
|
safely ignore any unknown bits that are set.
|
|
|
|
Bit 0: Lazy refcounts bit. If this bit is set then
|
|
lazy refcount updates can be used. This means
|
|
marking the image file dirty and postponing
|
|
refcount metadata updates.
|
|
|
|
Bits 1-63: Reserved (set to 0)
|
|
|
|
88 - 95: autoclear_features
|
|
Bitmask of auto-clear features. An implementation may only
|
|
write to an image with unknown auto-clear features if it
|
|
clears the respective bits from this field first.
|
|
|
|
Bit 0: Bitmaps extension bit
|
|
This bit indicates consistency for the bitmaps
|
|
extension data.
|
|
|
|
It is an error if this bit is set without the
|
|
bitmaps extension present.
|
|
|
|
If the bitmaps extension is present but this
|
|
bit is unset, the bitmaps extension data must be
|
|
considered inconsistent.
|
|
|
|
Bit 1: If this bit is set, the external data file can
|
|
be read as a consistent standalone raw image
|
|
without looking at the qcow2 metadata.
|
|
|
|
Setting this bit has a performance impact for
|
|
some operations on the image (e.g. writing
|
|
zeros requires writing to the data file instead
|
|
of only setting the zero flag in the L2 table
|
|
entry) and conflicts with backing files.
|
|
|
|
This bit may only be set if the External Data
|
|
File bit (incompatible feature bit 1) is also
|
|
set.
|
|
|
|
Bits 2-63: Reserved (set to 0)
|
|
|
|
96 - 99: refcount_order
|
|
Describes the width of a reference count block entry (width
|
|
in bits: refcount_bits = 1 << refcount_order). For version 2
|
|
images, the order is always assumed to be 4
|
|
(i.e. refcount_bits = 16).
|
|
This value may not exceed 6 (i.e. refcount_bits = 64).
|
|
|
|
100 - 103: header_length
|
|
Length of the header structure in bytes. For version 2
|
|
images, the length is always assumed to be 72 bytes.
|
|
|
|
Directly after the image header, optional sections called header extensions can
|
|
be stored. Each extension has a structure like the following:
|
|
|
|
Byte 0 - 3: Header extension type:
|
|
0x00000000 - End of the header extension area
|
|
0xE2792ACA - Backing file format name string
|
|
0x6803f857 - Feature name table
|
|
0x23852875 - Bitmaps extension
|
|
0x0537be77 - Full disk encryption header pointer
|
|
0x44415441 - External data file name string
|
|
other - Unknown header extension, can be safely
|
|
ignored
|
|
|
|
4 - 7: Length of the header extension data
|
|
|
|
8 - n: Header extension data
|
|
|
|
n - m: Padding to round up the header extension size to the next
|
|
multiple of 8.
|
|
|
|
Unless stated otherwise, each header extension type shall appear at most once
|
|
in the same image.
|
|
|
|
If the image has a backing file then the backing file name should be stored in
|
|
the remaining space between the end of the header extension area and the end of
|
|
the first cluster. It is not allowed to store other data here, so that an
|
|
implementation can safely modify the header and add extensions without harming
|
|
data of compatible features that it doesn't support. Compatible features that
|
|
need space for additional data can use a header extension.
|
|
|
|
|
|
== String header extensions ==
|
|
|
|
Some header extensions (such as the backing file format name and the external
|
|
data file name) are just a single string. In this case, the header extension
|
|
length is the string length and the string is not '\0' terminated. (The header
|
|
extension padding can make it look like a string is '\0' terminated, but
|
|
neither is padding always necessary nor is there a guarantee that zero bytes
|
|
are used for padding.)
|
|
|
|
|
|
== Feature name table ==
|
|
|
|
The feature name table is an optional header extension that contains the name
|
|
for features used by the image. It can be used by applications that don't know
|
|
the respective feature (e.g. because the feature was introduced only later) to
|
|
display a useful error message.
|
|
|
|
The number of entries in the feature name table is determined by the length of
|
|
the header extension data. Each entry look like this:
|
|
|
|
Byte 0: Type of feature (select feature bitmap)
|
|
0: Incompatible feature
|
|
1: Compatible feature
|
|
2: Autoclear feature
|
|
|
|
1: Bit number within the selected feature bitmap (valid
|
|
values: 0-63)
|
|
|
|
2 - 47: Feature name (padded with zeros, but not necessarily null
|
|
terminated if it has full length)
|
|
|
|
|
|
== Bitmaps extension ==
|
|
|
|
The bitmaps extension is an optional header extension. It provides the ability
|
|
to store bitmaps related to a virtual disk. For now, there is only one bitmap
|
|
type: the dirty tracking bitmap, which tracks virtual disk changes from some
|
|
point in time.
|
|
|
|
The data of the extension should be considered consistent only if the
|
|
corresponding auto-clear feature bit is set, see autoclear_features above.
|
|
|
|
The fields of the bitmaps extension are:
|
|
|
|
Byte 0 - 3: nb_bitmaps
|
|
The number of bitmaps contained in the image. Must be
|
|
greater than or equal to 1.
|
|
|
|
Note: Qemu currently only supports up to 65535 bitmaps per
|
|
image.
|
|
|
|
4 - 7: Reserved, must be zero.
|
|
|
|
8 - 15: bitmap_directory_size
|
|
Size of the bitmap directory in bytes. It is the cumulative
|
|
size of all (nb_bitmaps) bitmap directory entries.
|
|
|
|
16 - 23: bitmap_directory_offset
|
|
Offset into the image file at which the bitmap directory
|
|
starts. Must be aligned to a cluster boundary.
|
|
|
|
== Full disk encryption header pointer ==
|
|
|
|
The full disk encryption header must be present if, and only if, the
|
|
'crypt_method' header requires metadata. Currently this is only true
|
|
of the 'LUKS' crypt method. The header extension must be absent for
|
|
other methods.
|
|
|
|
This header provides the offset at which the crypt method can store
|
|
its additional data, as well as the length of such data.
|
|
|
|
Byte 0 - 7: Offset into the image file at which the encryption
|
|
header starts in bytes. Must be aligned to a cluster
|
|
boundary.
|
|
Byte 8 - 15: Length of the written encryption header in bytes.
|
|
Note actual space allocated in the qcow2 file may
|
|
be larger than this value, since it will be rounded
|
|
to the nearest multiple of the cluster size. Any
|
|
unused bytes in the allocated space will be initialized
|
|
to 0.
|
|
|
|
For the LUKS crypt method, the encryption header works as follows.
|
|
|
|
The first 592 bytes of the header clusters will contain the LUKS
|
|
partition header. This is then followed by the key material data areas.
|
|
The size of the key material data areas is determined by the number of
|
|
stripes in the key slot and key size. Refer to the LUKS format
|
|
specification ('docs/on-disk-format.pdf' in the cryptsetup source
|
|
package) for details of the LUKS partition header format.
|
|
|
|
In the LUKS partition header, the "payload-offset" field will be
|
|
calculated as normal for the LUKS spec. ie the size of the LUKS
|
|
header, plus key material regions, plus padding, relative to the
|
|
start of the LUKS header. This offset value is not required to be
|
|
qcow2 cluster aligned. Its value is currently never used in the
|
|
context of qcow2, since the qcow2 file format itself defines where
|
|
the real payload offset is, but none the less a valid payload offset
|
|
should always be present.
|
|
|
|
In the LUKS key slots header, the "key-material-offset" is relative
|
|
to the start of the LUKS header clusters in the qcow2 container,
|
|
not the start of the qcow2 file.
|
|
|
|
Logically the layout looks like
|
|
|
|
+-----------------------------+
|
|
| QCow2 header |
|
|
| QCow2 header extension X |
|
|
| QCow2 header extension FDE |
|
|
| QCow2 header extension ... |
|
|
| QCow2 header extension Z |
|
|
+-----------------------------+
|
|
| ....other QCow2 tables.... |
|
|
. .
|
|
. .
|
|
+-----------------------------+
|
|
| +-------------------------+ |
|
|
| | LUKS partition header | |
|
|
| +-------------------------+ |
|
|
| | LUKS key material 1 | |
|
|
| +-------------------------+ |
|
|
| | LUKS key material 2 | |
|
|
| +-------------------------+ |
|
|
| | LUKS key material ... | |
|
|
| +-------------------------+ |
|
|
| | LUKS key material 8 | |
|
|
| +-------------------------+ |
|
|
+-----------------------------+
|
|
| QCow2 cluster payload |
|
|
. .
|
|
. .
|
|
. .
|
|
| |
|
|
+-----------------------------+
|
|
|
|
== Data encryption ==
|
|
|
|
When an encryption method is requested in the header, the image payload
|
|
data must be encrypted/decrypted on every write/read. The image headers
|
|
and metadata are never encrypted.
|
|
|
|
The algorithms used for encryption vary depending on the method
|
|
|
|
- AES:
|
|
|
|
The AES cipher, in CBC mode, with 256 bit keys.
|
|
|
|
Initialization vectors generated using plain64 method, with
|
|
the virtual disk sector as the input tweak.
|
|
|
|
This format is no longer supported in QEMU system emulators, due
|
|
to a number of design flaws affecting its security. It is only
|
|
supported in the command line tools for the sake of back compatibility
|
|
and data liberation.
|
|
|
|
- LUKS:
|
|
|
|
The algorithms are specified in the LUKS header.
|
|
|
|
Initialization vectors generated using the method specified
|
|
in the LUKS header, with the physical disk sector as the
|
|
input tweak.
|
|
|
|
== Host cluster management ==
|
|
|
|
qcow2 manages the allocation of host clusters by maintaining a reference count
|
|
for each host cluster. A refcount of 0 means that the cluster is free, 1 means
|
|
that it is used, and >= 2 means that it is used and any write access must
|
|
perform a COW (copy on write) operation.
|
|
|
|
The refcounts are managed in a two-level table. The first level is called
|
|
refcount table and has a variable size (which is stored in the header). The
|
|
refcount table can cover multiple clusters, however it needs to be contiguous
|
|
in the image file.
|
|
|
|
It contains pointers to the second level structures which are called refcount
|
|
blocks and are exactly one cluster in size.
|
|
|
|
Although a large enough refcount table can reserve clusters past 64 PB
|
|
(56 bits) (assuming the underlying protocol can even be sized that
|
|
large), note that some qcow2 metadata such as L1/L2 tables must point
|
|
to clusters prior to that point.
|
|
|
|
Note: qemu has an implementation limit of 8 MB as the maximum refcount
|
|
table size. With a 2 MB cluster size and a default refcount_order of
|
|
4, it is unable to reference host resources beyond 2 EB (61 bits); in
|
|
the worst case, with a 512 cluster size and refcount_order of 6, it is
|
|
unable to access beyond 32 GB (35 bits).
|
|
|
|
Given an offset into the image file, the refcount of its cluster can be
|
|
obtained as follows:
|
|
|
|
refcount_block_entries = (cluster_size * 8 / refcount_bits)
|
|
|
|
refcount_block_index = (offset / cluster_size) % refcount_block_entries
|
|
refcount_table_index = (offset / cluster_size) / refcount_block_entries
|
|
|
|
refcount_block = load_cluster(refcount_table[refcount_table_index]);
|
|
return refcount_block[refcount_block_index];
|
|
|
|
Refcount table entry:
|
|
|
|
Bit 0 - 8: Reserved (set to 0)
|
|
|
|
9 - 63: Bits 9-63 of the offset into the image file at which the
|
|
refcount block starts. Must be aligned to a cluster
|
|
boundary.
|
|
|
|
If this is 0, the corresponding refcount block has not yet
|
|
been allocated. All refcounts managed by this refcount block
|
|
are 0.
|
|
|
|
Refcount block entry (x = refcount_bits - 1):
|
|
|
|
Bit 0 - x: Reference count of the cluster. If refcount_bits implies a
|
|
sub-byte width, note that bit 0 means the least significant
|
|
bit in this context.
|
|
|
|
|
|
== Cluster mapping ==
|
|
|
|
Just as for refcounts, qcow2 uses a two-level structure for the mapping of
|
|
guest clusters to host clusters. They are called L1 and L2 table.
|
|
|
|
The L1 table has a variable size (stored in the header) and may use multiple
|
|
clusters, however it must be contiguous in the image file. L2 tables are
|
|
exactly one cluster in size.
|
|
|
|
The L1 and L2 tables have implications on the maximum virtual file
|
|
size; for a given L1 table size, a larger cluster size is required for
|
|
the guest to have access to more space. Furthermore, a virtual
|
|
cluster must currently map to a host offset below 64 PB (56 bits)
|
|
(although this limit could be relaxed by putting reserved bits into
|
|
use). Additionally, as cluster size increases, the maximum host
|
|
offset for a compressed cluster is reduced (a 2M cluster size requires
|
|
compressed clusters to reside below 512 TB (49 bits), and this limit
|
|
cannot be relaxed without an incompatible layout change).
|
|
|
|
Given an offset into the virtual disk, the offset into the image file can be
|
|
obtained as follows:
|
|
|
|
l2_entries = (cluster_size / sizeof(uint64_t))
|
|
|
|
l2_index = (offset / cluster_size) % l2_entries
|
|
l1_index = (offset / cluster_size) / l2_entries
|
|
|
|
l2_table = load_cluster(l1_table[l1_index]);
|
|
cluster_offset = l2_table[l2_index];
|
|
|
|
return cluster_offset + (offset % cluster_size)
|
|
|
|
L1 table entry:
|
|
|
|
Bit 0 - 8: Reserved (set to 0)
|
|
|
|
9 - 55: Bits 9-55 of the offset into the image file at which the L2
|
|
table starts. Must be aligned to a cluster boundary. If the
|
|
offset is 0, the L2 table and all clusters described by this
|
|
L2 table are unallocated.
|
|
|
|
56 - 62: Reserved (set to 0)
|
|
|
|
63: 0 for an L2 table that is unused or requires COW, 1 if its
|
|
refcount is exactly one. This information is only accurate
|
|
in the active L1 table.
|
|
|
|
L2 table entry:
|
|
|
|
Bit 0 - 61: Cluster descriptor
|
|
|
|
62: 0 for standard clusters
|
|
1 for compressed clusters
|
|
|
|
63: 0 for clusters that are unused, compressed or require COW.
|
|
1 for standard clusters whose refcount is exactly one.
|
|
This information is only accurate in L2 tables
|
|
that are reachable from the active L1 table.
|
|
|
|
With external data files, all guest clusters have an
|
|
implicit refcount of 1 (because of the fixed host = guest
|
|
mapping for guest cluster offsets), so this bit should be 1
|
|
for all allocated clusters.
|
|
|
|
Standard Cluster Descriptor:
|
|
|
|
Bit 0: If set to 1, the cluster reads as all zeros. The host
|
|
cluster offset can be used to describe a preallocation,
|
|
but it won't be used for reading data from this cluster,
|
|
nor is data read from the backing file if the cluster is
|
|
unallocated.
|
|
|
|
With version 2, this is always 0.
|
|
|
|
1 - 8: Reserved (set to 0)
|
|
|
|
9 - 55: Bits 9-55 of host cluster offset. Must be aligned to a
|
|
cluster boundary. If the offset is 0 and bit 63 is clear,
|
|
the cluster is unallocated. The offset may only be 0 with
|
|
bit 63 set (indicating a host cluster offset of 0) when an
|
|
external data file is used.
|
|
|
|
56 - 61: Reserved (set to 0)
|
|
|
|
|
|
Compressed Clusters Descriptor (x = 62 - (cluster_bits - 8)):
|
|
|
|
Bit 0 - x-1: Host cluster offset. This is usually _not_ aligned to a
|
|
cluster or sector boundary! If cluster_bits is
|
|
small enough that this field includes bits beyond
|
|
55, those upper bits must be set to 0.
|
|
|
|
x - 61: Number of additional 512-byte sectors used for the
|
|
compressed data, beyond the sector containing the offset
|
|
in the previous field. Some of these sectors may reside
|
|
in the next contiguous host cluster.
|
|
|
|
Note that the compressed data does not necessarily occupy
|
|
all of the bytes in the final sector; rather, decompression
|
|
stops when it has produced a cluster of data.
|
|
|
|
Another compressed cluster may map to the tail of the final
|
|
sector used by this compressed cluster.
|
|
|
|
If a cluster is unallocated, read requests shall read the data from the backing
|
|
file (except if bit 0 in the Standard Cluster Descriptor is set). If there is
|
|
no backing file or the backing file is smaller than the image, they shall read
|
|
zeros for all parts that are not covered by the backing file.
|
|
|
|
|
|
== Snapshots ==
|
|
|
|
qcow2 supports internal snapshots. Their basic principle of operation is to
|
|
switch the active L1 table, so that a different set of host clusters are
|
|
exposed to the guest.
|
|
|
|
When creating a snapshot, the L1 table should be copied and the refcount of all
|
|
L2 tables and clusters reachable from this L1 table must be increased, so that
|
|
a write causes a COW and isn't visible in other snapshots.
|
|
|
|
When loading a snapshot, bit 63 of all entries in the new active L1 table and
|
|
all L2 tables referenced by it must be reconstructed from the refcount table
|
|
as it doesn't need to be accurate in inactive L1 tables.
|
|
|
|
A directory of all snapshots is stored in the snapshot table, a contiguous area
|
|
in the image file, whose starting offset and length are given by the header
|
|
fields snapshots_offset and nb_snapshots. The entries of the snapshot table
|
|
have variable length, depending on the length of ID, name and extra data.
|
|
|
|
Snapshot table entry:
|
|
|
|
Byte 0 - 7: Offset into the image file at which the L1 table for the
|
|
snapshot starts. Must be aligned to a cluster boundary.
|
|
|
|
8 - 11: Number of entries in the L1 table of the snapshots
|
|
|
|
12 - 13: Length of the unique ID string describing the snapshot
|
|
|
|
14 - 15: Length of the name of the snapshot
|
|
|
|
16 - 19: Time at which the snapshot was taken in seconds since the
|
|
Epoch
|
|
|
|
20 - 23: Subsecond part of the time at which the snapshot was taken
|
|
in nanoseconds
|
|
|
|
24 - 31: Time that the guest was running until the snapshot was
|
|
taken in nanoseconds
|
|
|
|
32 - 35: Size of the VM state in bytes. 0 if no VM state is saved.
|
|
If there is VM state, it starts at the first cluster
|
|
described by first L1 table entry that doesn't describe a
|
|
regular guest cluster (i.e. VM state is stored like guest
|
|
disk content, except that it is stored at offsets that are
|
|
larger than the virtual disk presented to the guest)
|
|
|
|
36 - 39: Size of extra data in the table entry (used for future
|
|
extensions of the format)
|
|
|
|
variable: Extra data for future extensions. Unknown fields must be
|
|
ignored. Currently defined are (offset relative to snapshot
|
|
table entry):
|
|
|
|
Byte 40 - 47: Size of the VM state in bytes. 0 if no VM
|
|
state is saved. If this field is present,
|
|
the 32-bit value in bytes 32-35 is ignored.
|
|
|
|
Byte 48 - 55: Virtual disk size of the snapshot in bytes
|
|
|
|
Version 3 images must include extra data at least up to
|
|
byte 55.
|
|
|
|
variable: Unique ID string for the snapshot (not null terminated)
|
|
|
|
variable: Name of the snapshot (not null terminated)
|
|
|
|
variable: Padding to round up the snapshot table entry size to the
|
|
next multiple of 8.
|
|
|
|
|
|
== Bitmaps ==
|
|
|
|
As mentioned above, the bitmaps extension provides the ability to store bitmaps
|
|
related to a virtual disk. This section describes how these bitmaps are stored.
|
|
|
|
All stored bitmaps are related to the virtual disk stored in the same image, so
|
|
each bitmap size is equal to the virtual disk size.
|
|
|
|
Each bit of the bitmap is responsible for strictly defined range of the virtual
|
|
disk. For bit number bit_nr the corresponding range (in bytes) will be:
|
|
|
|
[bit_nr * bitmap_granularity .. (bit_nr + 1) * bitmap_granularity - 1]
|
|
|
|
Granularity is a property of the concrete bitmap, see below.
|
|
|
|
|
|
=== Bitmap directory ===
|
|
|
|
Each bitmap saved in the image is described in a bitmap directory entry. The
|
|
bitmap directory is a contiguous area in the image file, whose starting offset
|
|
and length are given by the header extension fields bitmap_directory_offset and
|
|
bitmap_directory_size. The entries of the bitmap directory have variable
|
|
length, depending on the lengths of the bitmap name and extra data.
|
|
|
|
Structure of a bitmap directory entry:
|
|
|
|
Byte 0 - 7: bitmap_table_offset
|
|
Offset into the image file at which the bitmap table
|
|
(described below) for the bitmap starts. Must be aligned to
|
|
a cluster boundary.
|
|
|
|
8 - 11: bitmap_table_size
|
|
Number of entries in the bitmap table of the bitmap.
|
|
|
|
12 - 15: flags
|
|
Bit
|
|
0: in_use
|
|
The bitmap was not saved correctly and may be
|
|
inconsistent.
|
|
|
|
1: auto
|
|
The bitmap must reflect all changes of the virtual
|
|
disk by any application that would write to this qcow2
|
|
file (including writes, snapshot switching, etc.). The
|
|
type of this bitmap must be 'dirty tracking bitmap'.
|
|
|
|
2: extra_data_compatible
|
|
This flags is meaningful when the extra data is
|
|
unknown to the software (currently any extra data is
|
|
unknown to Qemu).
|
|
If it is set, the bitmap may be used as expected, extra
|
|
data must be left as is.
|
|
If it is not set, the bitmap must not be used, but
|
|
both it and its extra data be left as is.
|
|
|
|
Bits 3 - 31 are reserved and must be 0.
|
|
|
|
16: type
|
|
This field describes the sort of the bitmap.
|
|
Values:
|
|
1: Dirty tracking bitmap
|
|
|
|
Values 0, 2 - 255 are reserved.
|
|
|
|
17: granularity_bits
|
|
Granularity bits. Valid values: 0 - 63.
|
|
|
|
Note: Qemu currently supports only values 9 - 31.
|
|
|
|
Granularity is calculated as
|
|
granularity = 1 << granularity_bits
|
|
|
|
A bitmap's granularity is how many bytes of the image
|
|
accounts for one bit of the bitmap.
|
|
|
|
18 - 19: name_size
|
|
Size of the bitmap name. Must be non-zero.
|
|
|
|
Note: Qemu currently doesn't support values greater than
|
|
1023.
|
|
|
|
20 - 23: extra_data_size
|
|
Size of type-specific extra data.
|
|
|
|
For now, as no extra data is defined, extra_data_size is
|
|
reserved and should be zero. If it is non-zero the
|
|
behavior is defined by extra_data_compatible flag.
|
|
|
|
variable: extra_data
|
|
Extra data for the bitmap, occupying extra_data_size bytes.
|
|
Extra data must never contain references to clusters or in
|
|
some other way allocate additional clusters.
|
|
|
|
variable: name
|
|
The name of the bitmap (not null terminated), occupying
|
|
name_size bytes. Must be unique among all bitmap names
|
|
within the bitmaps extension.
|
|
|
|
variable: Padding to round up the bitmap directory entry size to the
|
|
next multiple of 8. All bytes of the padding must be zero.
|
|
|
|
|
|
=== Bitmap table ===
|
|
|
|
Each bitmap is stored using a one-level structure (as opposed to two-level
|
|
structures like for refcounts and guest clusters mapping) for the mapping of
|
|
bitmap data to host clusters. This structure is called the bitmap table.
|
|
|
|
Each bitmap table has a variable size (stored in the bitmap directory entry)
|
|
and may use multiple clusters, however, it must be contiguous in the image
|
|
file.
|
|
|
|
Structure of a bitmap table entry:
|
|
|
|
Bit 0: Reserved and must be zero if bits 9 - 55 are non-zero.
|
|
If bits 9 - 55 are zero:
|
|
0: Cluster should be read as all zeros.
|
|
1: Cluster should be read as all ones.
|
|
|
|
1 - 8: Reserved and must be zero.
|
|
|
|
9 - 55: Bits 9 - 55 of the host cluster offset. Must be aligned to
|
|
a cluster boundary. If the offset is 0, the cluster is
|
|
unallocated; in that case, bit 0 determines how this
|
|
cluster should be treated during reads.
|
|
|
|
56 - 63: Reserved and must be zero.
|
|
|
|
|
|
=== Bitmap data ===
|
|
|
|
As noted above, bitmap data is stored in separate clusters, described by the
|
|
bitmap table. Given an offset (in bytes) into the bitmap data, the offset into
|
|
the image file can be obtained as follows:
|
|
|
|
image_offset(bitmap_data_offset) =
|
|
bitmap_table[bitmap_data_offset / cluster_size] +
|
|
(bitmap_data_offset % cluster_size)
|
|
|
|
This offset is not defined if bits 9 - 55 of bitmap table entry are zero (see
|
|
above).
|
|
|
|
Given an offset byte_nr into the virtual disk and the bitmap's granularity, the
|
|
bit offset into the image file to the corresponding bit of the bitmap can be
|
|
calculated like this:
|
|
|
|
bit_offset(byte_nr) =
|
|
image_offset(byte_nr / granularity / 8) * 8 +
|
|
(byte_nr / granularity) % 8
|
|
|
|
If the size of the bitmap data is not a multiple of the cluster size then the
|
|
last cluster of the bitmap data contains some unused tail bits. These bits must
|
|
be zero.
|
|
|
|
|
|
=== Dirty tracking bitmaps ===
|
|
|
|
Bitmaps with 'type' field equal to one are dirty tracking bitmaps.
|
|
|
|
When the virtual disk is in use dirty tracking bitmap may be 'enabled' or
|
|
'disabled'. While the bitmap is 'enabled', all writes to the virtual disk
|
|
should be reflected in the bitmap. A set bit in the bitmap means that the
|
|
corresponding range of the virtual disk (see above) was written to while the
|
|
bitmap was 'enabled'. An unset bit means that this range was not written to.
|
|
|
|
The software doesn't have to sync the bitmap in the image file with its
|
|
representation in RAM after each write. Flag 'in_use' should be set while the
|
|
bitmap is not synced.
|
|
|
|
In the image file the 'enabled' state is reflected by the 'auto' flag. If this
|
|
flag is set, the software must consider the bitmap as 'enabled' and start
|
|
tracking virtual disk changes to this bitmap from the first write to the
|
|
virtual disk. If this flag is not set then the bitmap is disabled.
|