@@ -40,7 +40,17 @@ The first cluster of a qcow2 image contains the file header:
with larger cluster sizes.
24 - 31: size
- Virtual disk size in bytes
+ Virtual disk size in bytes.
+
+ Note: with a 2 MB cluster size, the maximum
+ virtual size is 2 EB (61 bits) for a sparse file,
+ but other sizing limitations in refcount and L1/L2
+ tables mean that an image cannot have more than 64
+ PB (56 bits) of populated clusters (assuming the
+ image does not first hit other limits such as a
+ file system's maximum size). With a 512 byte
+ cluster size, the maximum virtual size drops to
+ 128 GB (37 bits).
32 - 35: crypt_method
0 for no encryption
@@ -326,6 +336,15 @@ in the image file.
It contains pointers to the second level structures which are called refcount
blocks and are exactly one cluster in size.
+All qcow2 metadata, including the refcount table and refcount blocks,
+must currently reside at host offsets below 64 PB (56 bits) (if the
+underlying protocol can even be sized that large); this limit could be
+enlarged by putting reserved bits into use, but only if a similar
+limit on L1/L2 tables is revisited at the same time. While a larger
+cluster size theoretically allows the refcount table to cover more
+host offsets, in practice, other inherent limits will constrain the
+maximum image size before the refcount table is full.
+
Given a offset into the image file, the refcount of its cluster can be obtained
as follows:
@@ -341,7 +360,7 @@ 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
+ 9 - 55: Bits 9-55 of the offset into the image file at which the
refcount block starts. Must be aligned to a cluster
boundary.
@@ -349,6 +368,8 @@ Refcount table entry:
been allocated. All refcounts managed by this refcount block
are 0.
+ 56 - 63: Reserved (set to 0)
+
Refcount block entry (x = refcount_bits - 1):
Bit 0 - x: Reference count of the cluster. If refcount_bits implies a
@@ -365,6 +386,17 @@ 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; 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) (this limit could be enlarged by
+putting reserved bits into use, but only if a similar limit on
+refcount tables is revisited at the same time). Additionally, with
+larger cluster sizes, compressed clusters have a smaller limit on host
+cluster mappings (a 2M cluster size requires compressed clusters to
+reside below 512 TB (49 bits), where enlarging this would require an
+incompatible layout change).
+
Given a offset into the virtual disk, the offset into the image file can be
obtained as follows:
@@ -427,7 +459,9 @@ Standard Cluster Descriptor:
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!
+ 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