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