| Parallels Expandable Image File Format | |
| ====================================== | |
| .. | |
| 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. | |
| 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 offset table (l1_table), size: 8 * l1_size bytes | |
| The dirty bitmap described by this feature extension is stored in a set of | |
| clusters inside the Parallels image file. The offsets of these clusters are | |
| saved in the L1 offset table specified by the feature extension. Each L1 table | |
| entry is a 64 bit integer as described below: | |
| Given an offset in bytes into the bitmap data, corresponding L1 entry is:: | |
| l1_table[offset / cluster_size] | |
| If an L1 table entry is 0, all bits in the corresponding cluster of the bitmap | |
| are assumed to be 0. | |
| If an L1 table entry is 1, all bits in the corresponding cluster of the bitmap | |
| are assumed to be 1. | |
| If an L1 table entry is not 0 or 1, it contains the corresponding cluster | |
| offset (in 512b sectors). 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] * 512 + (offset % cluster_size) |