]>
Commit | Line | Data |
---|---|---|
03feae73 KW |
1 | == General == |
2 | ||
3 | A 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, | |
5 | both for actual guest data and for image metadata. | |
6 | ||
7 | Likewise, the virtual disk as seen by the guest is divided into (guest) | |
8 | clusters of the same size. | |
9 | ||
10 | All numbers in qcow2 are stored in Big Endian byte order. | |
11 | ||
12 | ||
13 | == Header == | |
14 | ||
15 | The 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 | |
4fabffc1 | 21 | Version number (valid values are 2 and 3) |
03feae73 KW |
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 | 32 - 35: crypt_method | |
46 | 0 for no encryption | |
47 | 1 for AES encryption | |
48 | ||
49 | 36 - 39: l1_size | |
50 | Number of entries in the active L1 table | |
51 | ||
52 | 40 - 47: l1_table_offset | |
53 | Offset into the image file at which the active L1 table | |
54 | starts. Must be aligned to a cluster boundary. | |
55 | ||
56 | 48 - 55: refcount_table_offset | |
57 | Offset into the image file at which the refcount table | |
58 | starts. Must be aligned to a cluster boundary. | |
59 | ||
60 | 56 - 59: refcount_table_clusters | |
61 | Number of clusters that the refcount table occupies | |
62 | ||
63 | 60 - 63: nb_snapshots | |
64 | Number of snapshots contained in the image | |
65 | ||
66 | 64 - 71: snapshots_offset | |
67 | Offset into the image file at which the snapshot table | |
68 | starts. Must be aligned to a cluster boundary. | |
69 | ||
4fabffc1 KW |
70 | If the version is 3 or higher, the header has the following additional fields. |
71 | For version 2, the values are assumed to be zero, unless specified otherwise | |
72 | in the description of a field. | |
73 | ||
74 | 72 - 79: incompatible_features | |
75 | Bitmask of incompatible features. An implementation must | |
76 | fail to open an image if an unknown bit is set. | |
77 | ||
0f6d767a SH |
78 | Bit 0: Dirty bit. If this bit is set then refcounts |
79 | may be inconsistent, make sure to scan L1/L2 | |
80 | tables to repair refcounts before accessing the | |
81 | image. | |
82 | ||
69c98726 MR |
83 | Bit 1: Corrupt bit. If this bit is set then any data |
84 | structure may be corrupt and the image must not | |
85 | be written to (unless for regaining | |
86 | consistency). | |
87 | ||
88 | Bits 2-63: Reserved (set to 0) | |
4fabffc1 KW |
89 | |
90 | 80 - 87: compatible_features | |
91 | Bitmask of compatible features. An implementation can | |
92 | safely ignore any unknown bits that are set. | |
93 | ||
dae8796d SH |
94 | Bit 0: Lazy refcounts bit. If this bit is set then |
95 | lazy refcount updates can be used. This means | |
96 | marking the image file dirty and postponing | |
97 | refcount metadata updates. | |
98 | ||
99 | Bits 1-63: Reserved (set to 0) | |
4fabffc1 KW |
100 | |
101 | 88 - 95: autoclear_features | |
102 | Bitmask of auto-clear features. An implementation may only | |
103 | write to an image with unknown auto-clear features if it | |
104 | clears the respective bits from this field first. | |
105 | ||
106 | Bits 0-63: Reserved (set to 0) | |
107 | ||
108 | 96 - 99: refcount_order | |
109 | Describes the width of a reference count block entry (width | |
110 | in bits = 1 << refcount_order). For version 2 images, the | |
111 | order is always assumed to be 4 (i.e. the width is 16 bits). | |
112 | ||
113 | 100 - 103: header_length | |
114 | Length of the header structure in bytes. For version 2 | |
115 | images, the length is always assumed to be 72 bytes. | |
116 | ||
03feae73 KW |
117 | Directly after the image header, optional sections called header extensions can |
118 | be stored. Each extension has a structure like the following: | |
119 | ||
120 | Byte 0 - 3: Header extension type: | |
121 | 0x00000000 - End of the header extension area | |
122 | 0xE2792ACA - Backing file format name | |
4fabffc1 | 123 | 0x6803f857 - Feature name table |
03feae73 KW |
124 | other - Unknown header extension, can be safely |
125 | ignored | |
126 | ||
127 | 4 - 7: Length of the header extension data | |
128 | ||
129 | 8 - n: Header extension data | |
130 | ||
131 | n - m: Padding to round up the header extension size to the next | |
132 | multiple of 8. | |
133 | ||
4fabffc1 KW |
134 | Unless stated otherwise, each header extension type shall appear at most once |
135 | in the same image. | |
136 | ||
03feae73 | 137 | The remaining space between the end of the header extension area and the end of |
4fabffc1 KW |
138 | the first cluster can be used for the backing file name. It is not allowed to |
139 | store other data here, so that an implementation can safely modify the header | |
140 | and add extensions without harming data of compatible features that it | |
141 | doesn't support. Compatible features that need space for additional data can | |
142 | use a header extension. | |
143 | ||
144 | ||
145 | == Feature name table == | |
146 | ||
147 | The feature name table is an optional header extension that contains the name | |
148 | for features used by the image. It can be used by applications that don't know | |
149 | the respective feature (e.g. because the feature was introduced only later) to | |
150 | display a useful error message. | |
151 | ||
152 | The number of entries in the feature name table is determined by the length of | |
153 | the header extension data. Each entry look like this: | |
154 | ||
155 | Byte 0: Type of feature (select feature bitmap) | |
156 | 0: Incompatible feature | |
157 | 1: Compatible feature | |
158 | 2: Autoclear feature | |
159 | ||
160 | 1: Bit number within the selected feature bitmap (valid | |
161 | values: 0-63) | |
162 | ||
163 | 2 - 47: Feature name (padded with zeros, but not necessarily null | |
164 | terminated if it has full length) | |
03feae73 KW |
165 | |
166 | ||
167 | == Host cluster management == | |
168 | ||
169 | qcow2 manages the allocation of host clusters by maintaining a reference count | |
170 | for each host cluster. A refcount of 0 means that the cluster is free, 1 means | |
171 | that it is used, and >= 2 means that it is used and any write access must | |
172 | perform a COW (copy on write) operation. | |
173 | ||
174 | The refcounts are managed in a two-level table. The first level is called | |
175 | refcount table and has a variable size (which is stored in the header). The | |
176 | refcount table can cover multiple clusters, however it needs to be contiguous | |
177 | in the image file. | |
178 | ||
179 | It contains pointers to the second level structures which are called refcount | |
180 | blocks and are exactly one cluster in size. | |
181 | ||
182 | Given a offset into the image file, the refcount of its cluster can be obtained | |
183 | as follows: | |
184 | ||
185 | refcount_block_entries = (cluster_size / sizeof(uint16_t)) | |
186 | ||
3789985f ZYW |
187 | refcount_block_index = (offset / cluster_size) % refcount_block_entries |
188 | refcount_table_index = (offset / cluster_size) / refcount_block_entries | |
03feae73 KW |
189 | |
190 | refcount_block = load_cluster(refcount_table[refcount_table_index]); | |
191 | return refcount_block[refcount_block_index]; | |
192 | ||
193 | Refcount table entry: | |
194 | ||
195 | Bit 0 - 8: Reserved (set to 0) | |
196 | ||
197 | 9 - 63: Bits 9-63 of the offset into the image file at which the | |
198 | refcount block starts. Must be aligned to a cluster | |
199 | boundary. | |
200 | ||
201 | If this is 0, the corresponding refcount block has not yet | |
202 | been allocated. All refcounts managed by this refcount block | |
203 | are 0. | |
204 | ||
4fabffc1 | 205 | Refcount block entry (x = refcount_bits - 1): |
03feae73 | 206 | |
4fabffc1 KW |
207 | Bit 0 - x: Reference count of the cluster. If refcount_bits implies a |
208 | sub-byte width, note that bit 0 means the least significant | |
209 | bit in this context. | |
03feae73 KW |
210 | |
211 | ||
212 | == Cluster mapping == | |
213 | ||
214 | Just as for refcounts, qcow2 uses a two-level structure for the mapping of | |
215 | guest clusters to host clusters. They are called L1 and L2 table. | |
216 | ||
217 | The L1 table has a variable size (stored in the header) and may use multiple | |
218 | clusters, however it must be contiguous in the image file. L2 tables are | |
219 | exactly one cluster in size. | |
220 | ||
221 | Given a offset into the virtual disk, the offset into the image file can be | |
222 | obtained as follows: | |
223 | ||
224 | l2_entries = (cluster_size / sizeof(uint64_t)) | |
225 | ||
226 | l2_index = (offset / cluster_size) % l2_entries | |
227 | l1_index = (offset / cluster_size) / l2_entries | |
228 | ||
229 | l2_table = load_cluster(l1_table[l1_index]); | |
230 | cluster_offset = l2_table[l2_index]; | |
231 | ||
232 | return cluster_offset + (offset % cluster_size) | |
233 | ||
234 | L1 table entry: | |
235 | ||
236 | Bit 0 - 8: Reserved (set to 0) | |
237 | ||
238 | 9 - 55: Bits 9-55 of the offset into the image file at which the L2 | |
239 | table starts. Must be aligned to a cluster boundary. If the | |
240 | offset is 0, the L2 table and all clusters described by this | |
241 | L2 table are unallocated. | |
242 | ||
243 | 56 - 62: Reserved (set to 0) | |
244 | ||
245 | 63: 0 for an L2 table that is unused or requires COW, 1 if its | |
246 | refcount is exactly one. This information is only accurate | |
247 | in the active L1 table. | |
248 | ||
4fabffc1 | 249 | L2 table entry: |
03feae73 | 250 | |
4fabffc1 KW |
251 | Bit 0 - 61: Cluster descriptor |
252 | ||
253 | 62: 0 for standard clusters | |
254 | 1 for compressed clusters | |
255 | ||
256 | 63: 0 for a cluster that is unused or requires COW, 1 if its | |
257 | refcount is exactly one. This information is only accurate | |
258 | in L2 tables that are reachable from the the active L1 | |
259 | table. | |
260 | ||
261 | Standard Cluster Descriptor: | |
262 | ||
263 | Bit 0: If set to 1, the cluster reads as all zeros. The host | |
264 | cluster offset can be used to describe a preallocation, | |
265 | but it won't be used for reading data from this cluster, | |
266 | nor is data read from the backing file if the cluster is | |
267 | unallocated. | |
268 | ||
269 | With version 2, this is always 0. | |
270 | ||
271 | 1 - 8: Reserved (set to 0) | |
03feae73 KW |
272 | |
273 | 9 - 55: Bits 9-55 of host cluster offset. Must be aligned to a | |
274 | cluster boundary. If the offset is 0, the cluster is | |
275 | unallocated. | |
276 | ||
277 | 56 - 61: Reserved (set to 0) | |
278 | ||
03feae73 | 279 | |
bf3f363a | 280 | Compressed Clusters Descriptor (x = 62 - (cluster_bits - 8)): |
03feae73 KW |
281 | |
282 | Bit 0 - x: Host cluster offset. This is usually _not_ aligned to a | |
283 | cluster boundary! | |
284 | ||
285 | x+1 - 61: Compressed size of the images in sectors of 512 bytes | |
286 | ||
03feae73 | 287 | If a cluster is unallocated, read requests shall read the data from the backing |
4fabffc1 KW |
288 | file (except if bit 0 in the Standard Cluster Descriptor is set). If there is |
289 | no backing file or the backing file is smaller than the image, they shall read | |
290 | zeros for all parts that are not covered by the backing file. | |
03feae73 KW |
291 | |
292 | ||
293 | == Snapshots == | |
294 | ||
295 | qcow2 supports internal snapshots. Their basic principle of operation is to | |
296 | switch the active L1 table, so that a different set of host clusters are | |
297 | exposed to the guest. | |
298 | ||
299 | When creating a snapshot, the L1 table should be copied and the refcount of all | |
3789985f | 300 | L2 tables and clusters reachable from this L1 table must be increased, so that |
03feae73 KW |
301 | a write causes a COW and isn't visible in other snapshots. |
302 | ||
303 | When loading a snapshot, bit 63 of all entries in the new active L1 table and | |
304 | all L2 tables referenced by it must be reconstructed from the refcount table | |
305 | as it doesn't need to be accurate in inactive L1 tables. | |
306 | ||
307 | A directory of all snapshots is stored in the snapshot table, a contiguous area | |
308 | in the image file, whose starting offset and length are given by the header | |
309 | fields snapshots_offset and nb_snapshots. The entries of the snapshot table | |
310 | have variable length, depending on the length of ID, name and extra data. | |
311 | ||
312 | Snapshot table entry: | |
313 | ||
314 | Byte 0 - 7: Offset into the image file at which the L1 table for the | |
315 | snapshot starts. Must be aligned to a cluster boundary. | |
316 | ||
317 | 8 - 11: Number of entries in the L1 table of the snapshots | |
318 | ||
319 | 12 - 13: Length of the unique ID string describing the snapshot | |
320 | ||
321 | 14 - 15: Length of the name of the snapshot | |
322 | ||
323 | 16 - 19: Time at which the snapshot was taken in seconds since the | |
324 | Epoch | |
325 | ||
326 | 20 - 23: Subsecond part of the time at which the snapshot was taken | |
327 | in nanoseconds | |
328 | ||
329 | 24 - 31: Time that the guest was running until the snapshot was | |
330 | taken in nanoseconds | |
331 | ||
332 | 32 - 35: Size of the VM state in bytes. 0 if no VM state is saved. | |
333 | If there is VM state, it starts at the first cluster | |
334 | described by first L1 table entry that doesn't describe a | |
335 | regular guest cluster (i.e. VM state is stored like guest | |
336 | disk content, except that it is stored at offsets that are | |
337 | larger than the virtual disk presented to the guest) | |
338 | ||
339 | 36 - 39: Size of extra data in the table entry (used for future | |
340 | extensions of the format) | |
341 | ||
c2c9a466 KW |
342 | variable: Extra data for future extensions. Unknown fields must be |
343 | ignored. Currently defined are (offset relative to snapshot | |
344 | table entry): | |
345 | ||
346 | Byte 40 - 47: Size of the VM state in bytes. 0 if no VM | |
347 | state is saved. If this field is present, | |
348 | the 32-bit value in bytes 32-35 is ignored. | |
03feae73 | 349 | |
4fabffc1 KW |
350 | Byte 48 - 55: Virtual disk size of the snapshot in bytes |
351 | ||
352 | Version 3 images must include extra data at least up to | |
353 | byte 55. | |
354 | ||
03feae73 KW |
355 | variable: Unique ID string for the snapshot (not null terminated) |
356 | ||
357 | variable: Name of the snapshot (not null terminated) | |
f2520804 MR |
358 | |
359 | variable: Padding to round up the snapshot table entry size to the | |
360 | next multiple of 8. |