d59157ea05
This is for the future interoperability & management guide. It includes the QAPI docs, including the automatically generated ones, other socket protocols (vhost-user, VNC), and the qcow2 file format. Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
229 lines
7.5 KiB
Plaintext
229 lines
7.5 KiB
Plaintext
= 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.
|