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