The virtual disk is cut into guest clusters, the file into host clusters of the same size. A two-level table, L1 then L2, says which host cluster holds each guest cluster. A separate two-level refcount structure counts how many times each host cluster is used, so that snapshots can share clusters. All table entries are big-endian 64-bit numbers; bit 0 is the least significant.
Finding a byte
With c = cluster size and n = L2 entries per table (c ÷ 8, or c ÷ 16 with extended L2), for a guest byte offset x:
- L1 index = x ÷ (c × n); read that L1 entry to find the L2 table.
- L2 index = (x ÷ c) mod n; read that L2 entry to find the host cluster.
- The byte is at host cluster offset + (x mod c).
An unallocated cluster is read from the backing file if there is one (and the offset is within it); otherwise, or if the zero flag is set, it reads as zeros.
Refcounts
A refcount of 0 means the host cluster is free, 1 that it is used once, 2 or more that it is shared and must be copied before it is written (copy on write). The refcount table lists refcount blocks; each block is a cluster of refcounts, each 2refcount_order bits wide.
| Bits | Refcount table entry |
|---|---|
| 0–8 | Reserved, 0. |
| 9–63 | Offset of the refcount block, on a cluster boundary. 0: the block is not allocated, and all its refcounts are 0. |
Refcounts per block = c × 8 ÷ refcount bits. For host cluster number h: table index = h ÷ refcounts per block, and index in block = h mod refcounts per block.
L1 entries
| Bits | Meaning |
|---|---|
| 0–8 | Reserved, 0. |
| 9–55 | Offset of the L2 table, on a cluster boundary. 0: no L2 table, so every cluster it would cover is unallocated. |
| 56–62 | Reserved, 0. |
| 63 | Set when the L2 table’s refcount is exactly 1, so it can be written in place. Kept accurate only in the active L1 table. |
L2 entries
Bit 62 says whether the cluster is stored normally or compressed.
| Bits | Standard cluster |
|---|---|
| 0 | Zero flag: the cluster reads as zeros. Version 3 only; always 0 in version 2 and with extended L2 entries. |
| 1–8 | Reserved, 0. |
| 9–55 | Offset of the host cluster, on a cluster boundary. 0 (with bit 63 clear) means unallocated; with an external data file, 0 with bit 63 set is offset 0. |
| 56–61 | Reserved, 0. |
| 62 | 0: standard cluster. |
| 63 | Set when the cluster’s refcount is exactly 1 (and for every allocated cluster with an external data file). |
| Bits | Compressed cluster (with x = 62 − (cluster_bits − 8)) |
|---|---|
| 0 to x − 1 | Byte offset in the file where the compressed data starts; not aligned. Bits above 55 must be 0. |
| x to 61 | Number of additional 512-byte sectors the compressed data covers, beyond the first (the data may run into the next host cluster). |
| 62 | 1: compressed. |
| 63 | 0. |
Compressed data is deflate without a zlib header, or zstd if the header’s
compression_type is 1. A reader decompresses until it has a whole cluster;
the last sector may be shared with the next compressed cluster. For 64 KiB clusters,
x is 54: bits 0–53 are the offset and bits 54–61 the sector count.
Extended L2 entries
With incompatible feature bit 4, each L2 entry is 128 bits: the 64-bit entry above (without the zero flag), then a 64-bit subcluster bitmap. Each cluster is split into 32 equal subclusters.
| Bits of the second word | Meaning (standard clusters) |
|---|---|
| 0–31 | Allocation: bit s set means subcluster s is allocated in this image; clear means it is read from the backing file or as zeros. |
| 32–63 | Reads as zero: bit 32 + s set means subcluster s reads as zeros. Only allowed with its allocation bit clear. |
For compressed clusters the second word is reserved and 0; compressed clusters have no subclusters.