1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
|
= License =
Copyright (c) 2015 Denis Lunev
Copyright (c) 2015 Vladimir Sementsov-Ogievskiy
This work is licensed under the terms of the GNU GPL, version 2 or later.
See the COPYING file in the top-level directory.
= Parallels Expandable Image File Format =
A Parallels expandable image file consists of three consecutive parts:
* header
* BAT
* data area
All numbers in a Parallels expandable image are stored in little-endian byte
order.
== Definitions ==
Sector A 512-byte data chunk.
Cluster A data chunk of the size specified in the image header.
Currently, the default size is 1MiB (2048 sectors). In previous
versions, cluster sizes of 63 sectors, 256 and 252 kilobytes were
used.
BAT Block Allocation Table, an entity that contains information for
guest-to-host I/O data address translation.
== Header ==
The header is placed at the start of an image and contains the following
fields:
Bytes:
0 - 15: magic
Must contain "WithoutFreeSpace" or "WithouFreSpacExt".
16 - 19: version
Must be 2.
20 - 23: heads
Disk geometry parameter for guest.
24 - 27: cylinders
Disk geometry parameter for guest.
28 - 31: tracks
Cluster size, in sectors.
32 - 35: nb_bat_entries
Disk size, in clusters (BAT size).
36 - 43: nb_sectors
Disk size, in sectors.
For "WithoutFreeSpace" images:
Only the lowest 4 bytes are used. The highest 4 bytes must be
cleared in this case.
For "WithouFreSpacExt" images, there are no such
restrictions.
44 - 47: in_use
Set to 0x746F6E59 when the image is opened by software in R/W
mode; set to 0x312e3276 when the image is closed.
A zero in this field means that the image was opened by an old
version of the software that doesn't support Format Extension
(see below).
Other values are not allowed.
48 - 51: data_off
An offset, in sectors, from the start of the file to the start of
the data area.
For "WithoutFreeSpace" images:
- If data_off is zero, the offset is calculated as the end of BAT
table plus some padding to ensure sector size alignment.
- If data_off is non-zero, the offset should be aligned to sector
size. However it is recommended to align it to cluster size for
newly created images.
For "WithouFreSpacExt" images:
data_off must be non-zero and aligned to cluster size.
52 - 55: flags
Miscellaneous flags.
Bit 0: Empty Image bit. If set, the image should be
considered clear.
Bits 2-31: Unused.
56 - 63: ext_off
Format Extension offset, an offset, in sectors, from the start of
the file to the start of the Format Extension Cluster.
ext_off must meet the same requirements as cluster offsets
defined by BAT entries (see below).
== BAT ==
BAT is placed immediately after the image header. In the file, BAT is a
contiguous array of 32-bit unsigned little-endian integers with
(bat_entries * 4) bytes size.
Each BAT entry contains an offset from the start of the file to the
corresponding cluster. The offset set in clusters for "WithouFreSpacExt" images
and in sectors for "WithoutFreeSpace" images.
If a BAT entry is zero, the corresponding cluster is not allocated and should
be considered as filled with zeroes.
Cluster offsets specified by BAT entries must meet the following requirements:
- the value must not be lower than data offset (provided by header.data_off
or calculated as specified above),
- the value must be lower than the desired file size,
- the value must be unique among all BAT entries,
- the result of (cluster offset - data offset) must be aligned to cluster
size.
== Data Area ==
The data area is an area from the data offset (provided by header.data_off or
calculated as specified above) to the end of the file. It represents a
contiguous array of clusters. Most of them are allocated by the BAT, some may
be allocated by the ext_off field in the header while other may be allocated by
extensions. All clusters allocated by ext_off and extensions should meet the
same requirements as clusters specified by BAT entries.
== Format Extension ==
The Format Extension is an area 1 cluster in size that provides additional
format features. This cluster is addressed by the ext_off field in the header.
The format of the Format Extension area is the following:
0 - 7: magic
Must be 0xAB234CEF23DCEA87
8 - 23: m_CheckSum
The MD5 checksum of the entire Header Extension cluster except
the first 24 bytes.
The above are followed by feature sections or "extensions". The last
extension must be "End of features" (see below).
Each feature section has the following format:
0 - 7: magic
The identifier of the feature:
0x0000000000000000 - End of features
0x20385FAE252CB34A - Dirty bitmap
8 - 15: flags
External flags for extension:
Bit 0: NECESSARY
If the software cannot load the extension (due to an
unknown magic number or error), the file should not be
changed. If this flag is unset and there is an error on
loading the extension, said extension should be dropped.
Bit 1: TRANSIT
If there is an unknown extension with this flag set,
said extension should be left as is.
If neither NECESSARY nor TRANSIT are set, the extension should be
dropped.
16 - 19: data_size
The size of the following feature data, in bytes.
20 - 23: unused32
Align header to 8 bytes boundary.
variable: data (data_size bytes)
The above is followed by padding to the next 8 bytes boundary, then the
next extension starts.
The last extension must be "End of features" with all the fields set to 0.
=== Dirty bitmaps feature ===
This feature provides a way of storing dirty bitmaps in the image. The fields
of its data area are:
0 - 7: size
The bitmap size, should be equal to disk size in sectors.
8 - 23: id
An identifier for backup consistency checking.
24 - 27: granularity
Bitmap granularity, in sectors. I.e., the number of sectors
corresponding to one bit of the bitmap. Granularity must be
a power of 2.
28 - 31: l1_size
The number of entries in the L1 table of the bitmap.
variable: l1 (64 * l1_size bytes)
L1 offset table (in bytes)
A dirty bitmap is stored using a one-level structure for the mapping to host
clusters - an L1 table.
Given an offset in bytes into the bitmap data, the offset in bytes into the
image file can be obtained as follows:
offset = l1_table[offset / cluster_size] + (offset % cluster_size)
If an L1 table entry is 0, the corresponding cluster of the bitmap is assumed
to be zero.
If an L1 table entry is 1, the corresponding cluster of the bitmap is assumed
to have all bits set.
If an L1 table entry is not 0 or 1, it allocates a cluster from the data area.
|
