[qemu.git] / docs / specs / parallels.txt

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