From: Vladimir Sementsov-Ogievskiy <vsement...@virtuozzo.com> This specifies Parallels image format as implemented in Parallels Cloud Server 6.10
Signed-off-by: Vladimir Sementsov-Ogievskiy <vsement...@virtuozzo.com> Signed-off-by: Denis V. Lunev <d...@openvz.org> CC: John Snow <js...@redhat.com> CC: Stefan Hajnoczi <stefa...@redhat.com> --- MAINTAINERS | 1 + docs/specs/parallels.txt | 218 +++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 219 insertions(+) create mode 100644 docs/specs/parallels.txt diff --git a/MAINTAINERS b/MAINTAINERS index 9e1fa72..23441e1 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -1471,6 +1471,7 @@ M: Denis V. Lunev <d...@openvz.org> L: qemu-bl...@nongnu.org S: Supported F: block/parallels.c +F: docs/specs/parallels.txt qed M: Stefan Hajnoczi <stefa...@redhat.com> diff --git a/docs/specs/parallels.txt b/docs/specs/parallels.txt new file mode 100644 index 0000000..56c716a --- /dev/null +++ b/docs/specs/parallels.txt @@ -0,0 +1,218 @@ += 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: + + char magic[16] + Must contain "WithoutFreeSpace" or "WithouFreSpacExt". + + uint32 version + Must be 2. + + uint32 heads + Disk geometry parameter for guest. + + uint32 cylinders + Disk geometry parameter for guest. + + uint32 tracks + Cluster size, in sectors. + + uint32 nb_bat_entries + Disk size, in clusters (BAT size). + + uint64 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. + + uint32 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. + + uint32 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. + + uint32 flags + Miscellaneous flags. + + Bit 0: Empty Image bit. If set, the image should be + considered clear. + + Bits 2-31: Unused. + + uint64 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: + + uint64 magic + Must be 0xAB234CEF23DCEA87 + + uint8 m_CheckSum[16] + 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: + + uint64 magic + The identifier of the feature: + 0x0000000000000000 - End of features + 0x20385FAE252CB34A - Dirty bitmap + + uint64 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. + + uint32 data_size + The size of the following feature data, in bytes. + + uint32 unused32 + Align header to 8 bytes boundary. + + uint8 data[data_size] + + 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: + + uint64 size + The bitmap size, should be equal to disk size in sectors. + + uint8 id[16] + An identifier for backup consistency checking. + + uint32 granularity + Bitmap granularity, in sectors. I.e., the number of sectors + corresponding to one bit of the bitmap. + + uint32 l1_size + The number of entries in the L1 table of the bitmap. + + uint64 l1[l1_size] + 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 into the bitmap, 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. -- 2.1.4