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