A QCOW2 image can hold internal snapshots of the disk (and of the running machine), and persistent bitmaps that record which parts of the disk have changed, for incremental backups. All numbers are big-endian.
Snapshots
A snapshot is a saved copy of the L1 table. Taking one copies the active L1 table and
raises the refcount of every cluster it reaches, so the snapshot and the live disk share
clusters until one of them is written. The snapshot table, at
snapshots_offset, holds nb_snapshots entries one after
another, each padded to a multiple of 8 bytes.
| Offset | Size | Type | Name | Description |
|---|---|---|---|---|
0 | 8 | uint64 | L1 table offset | The snapshot’s L1 table, on a cluster boundary. |
8 | 4 | uint32 | L1 size | Entries in it. |
12 | 2 | uint16 | ID length | Length of the unique ID string. |
14 | 2 | uint16 | Name length | Length of the name. |
16 | 4 | uint32 | Date, seconds | When the snapshot was taken, in seconds since 1970. |
20 | 4 | uint32 | Date, nanoseconds | The fraction of that second. |
24 | 8 | uint64 | VM clock | The guest’s running time, in nanoseconds. |
32 | 4 | uint32 | VM state size | Bytes of saved machine state; ignored when the 64-bit field below is present. |
36 | 4 | uint32 | Extra data size | Bytes of extra data that follow. |
40 | 8 | uint64 | VM state size (64-bit) | Extra data: bytes of machine state. |
48 | 8 | uint64 | Disk size | Extra data: the virtual disk size when the snapshot was taken. Version 3 needs extra data at least this far. |
56 | 8 | int64 | icount | Extra data: the instruction counter for record and replay, or −1 when that was off. |
| 40 + extra | ID length | text | Unique ID | Not zero-terminated. |
| … | name length | text | Name | Not zero-terminated; then padding to a multiple of 8. |
Machine state, when saved, is stored after the guest disk’s clusters in the snapshot’s own mapping: it starts at the first cluster past the end of the virtual disk. Bit 63 of the snapshot’s L1 and L2 entries is not kept accurate and must be recomputed when the snapshot is loaded.
Bitmaps
The bitmaps extension points to a bitmap directory: one entry per bitmap, each padded to a multiple of 8 bytes.
| Offset | Size | Type | Name | Description |
|---|---|---|---|---|
0 | 8 | uint64 | bitmap_table_offset | Where the bitmap table is, on a cluster boundary. |
8 | 4 | uint32 | bitmap_table_size | Entries in the bitmap table. |
12 | 4 | bits | flags | Bit 0 in_use: the bitmap may be out of date (it was open for writing). Bit 1 auto: the bitmap is enabled and tracks every write. Bit 2 extra_data_compatible: the bitmap can be used even if its extra data is not understood. Bits 3–31 reserved. |
16 | 1 | uint8 | type | 1: dirty tracking bitmap. Others reserved. |
17 | 1 | uint8 | granularity_bits | Each bit covers 2granularity_bits bytes of disk; QEMU supports 9 to 31. |
18 | 2 | uint16 | name_size | Length of the name, not 0; QEMU allows up to 1,023. |
20 | 4 | uint32 | extra_data_size | Reserved for now: 0. |
24 | varies | bytes | Extra data, then name | The name is not zero-terminated; then zero padding to a multiple of 8. |
| Bits | Bitmap table entry |
|---|---|
| 0 | When bits 9–55 are 0: 0 means that cluster of the bitmap reads as all zeros, 1 as all ones. Must be 0 when an offset is given. |
| 1–8 | Reserved, 0. |
| 9–55 | Offset of a cluster of bitmap data; 0 when not allocated. |
| 56–63 | Reserved, 0. |
Bitmap data is one bit per granule of the disk, in order: the bit for guest byte x is bit number x ÷ granularity, found in byte (bit number ÷ 8) of the bitmap data, which the table maps to clusters. A set bit means that part of the disk was written while the bitmap was enabled. Unused bits at the end of the last cluster are 0.