| 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) |
