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