| 1 | Parallels 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 | |
| 12 | A Parallels expandable image file consists of three consecutive parts: |
| 13 | |
| 14 | * header |
| 15 | * BAT |
| 16 | * data area |
| 17 | |
| 18 | All numbers in a Parallels expandable image are stored in little-endian byte |
| 19 | order. |
| 20 | |
| 21 | |
| 22 | Definitions |
| 23 | ----------- |
| 24 | |
| 25 | Sector |
| 26 | A 512-byte data chunk. |
| 27 | |
| 28 | Cluster |
| 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 | |
| 33 | BAT |
| 34 | Block Allocation Table, an entity that contains information for |
| 35 | guest-to-host I/O data address translation. |
| 36 | |
| 37 | Header |
| 38 | ------ |
| 39 | |
| 40 | The header is placed at the start of an image and contains the following |
| 41 | fields:: |
| 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 | |
| 111 | BAT |
| 112 | --- |
| 113 | |
| 114 | BAT is placed immediately after the image header. In the file, BAT is a |
| 115 | contiguous array of 32-bit unsigned little-endian integers with |
| 116 | ``(bat_entries * 4)`` bytes size. |
| 117 | |
| 118 | Each BAT entry contains an offset from the start of the file to the |
| 119 | corresponding cluster. The offset set in clusters for ``WithouFreSpacExt`` |
| 120 | images and in sectors for ``WithoutFreeSpace`` images. |
| 121 | |
| 122 | If a BAT entry is zero, the corresponding cluster is not allocated and should |
| 123 | be considered as filled with zeroes. |
| 124 | |
| 125 | Cluster 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 | |
| 134 | Data Area |
| 135 | --------- |
| 136 | |
| 137 | The data area is an area from the data offset (provided by ``header.data_off`` |
| 138 | or calculated as specified above) to the end of the file. It represents a |
| 139 | contiguous array of clusters. Most of them are allocated by the BAT, some may |
| 140 | be allocated by the ``ext_off`` field in the header while other may be |
| 141 | allocated by extensions. All clusters allocated by ``ext_off`` and extensions |
| 142 | should meet the same requirements as clusters specified by BAT entries. |
| 143 | |
| 144 | |
| 145 | Format Extension |
| 146 | ---------------- |
| 147 | |
| 148 | The Format Extension is an area 1 cluster in size that provides additional |
| 149 | format features. This cluster is addressed by the ext_off field in the header. |
| 150 | The 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 | |
| 159 | The above are followed by feature sections or "extensions". The last |
| 160 | extension must be "End of features" (see below). |
| 161 | |
| 162 | Each 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 | |
| 193 | The above is followed by padding to the next 8 bytes boundary, then the |
| 194 | next extension starts. |
| 195 | |
| 196 | The last extension must be "End of features" with all the fields set to 0. |
| 197 | |
| 198 | |
| 199 | Dirty bitmaps feature |
| 200 | --------------------- |
| 201 | |
| 202 | This feature provides a way of storing dirty bitmaps in the image. The fields |
| 203 | of 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 | |
| 221 | The dirty bitmap described by this feature extension is stored in a set of |
| 222 | clusters inside the Parallels image file. The offsets of these clusters are |
| 223 | saved in the L1 offset table specified by the feature extension. Each L1 table |
| 224 | entry is a 64 bit integer as described below: |
| 225 | |
| 226 | Given an offset in bytes into the bitmap data, corresponding L1 entry is:: |
| 227 | |
| 228 | l1_table[offset / cluster_size] |
| 229 | |
| 230 | If an L1 table entry is 0, all bits in the corresponding cluster of the bitmap |
| 231 | are assumed to be 0. |
| 232 | |
| 233 | If an L1 table entry is 1, all bits in the corresponding cluster of the bitmap |
| 234 | are assumed to be 1. |
| 235 | |
| 236 | If an L1 table entry is not 0 or 1, it contains the corresponding cluster |
| 237 | offset (in 512b sectors). Given an offset in bytes into the bitmap data the |
| 238 | offset in bytes into the image file can be obtained as follows:: |
| 239 | |
| 240 | offset = l1_table[offset / cluster_size] * 512 + (offset % cluster_size) |