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