docs/interop/parallels.txt

   1 = License =
   2
   3 Copyright (c) 2015 Denis Lunev
   4 Copyright (c) 2015 Vladimir Sementsov-Ogievskiy
   5
   6 This work is licensed under the terms of the GNU GPL, version 2 or later.
   7 See the COPYING file in the top-level directory.
   8
   9 = Parallels Expandable Image File Format =
  10
  11 A Parallels expandable image file consists of three consecutive parts:
  12     * header
  13     * BAT
  14     * data area
  15
  16 All numbers in a Parallels expandable image are stored in little-endian byte
  17 order.
  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
  35 The header is placed at the start of an image and contains the following
  36 fields:
  37
  38 Bytes:
  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
 109 BAT is placed immediately after the image header. In the file, BAT is a
 110 contiguous array of 32-bit unsigned little-endian integers with
 111 (bat_entries * 4) bytes size.
 112
 113 Each BAT entry contains an offset from the start of the file to the
 114 corresponding cluster. The offset set in clusters for "WithouFreSpacExt" images
 115 and in sectors for "WithoutFreeSpace" images.
 116
 117 If a BAT entry is zero, the corresponding cluster is not allocated and should
 118 be considered as filled with zeroes.
 119
 120 Cluster 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
 131 The data area is an area from the data offset (provided by header.data_off or
 132 calculated as specified above) to the end of the file. It represents a
 133 contiguous array of clusters. Most of them are allocated by the BAT, some may
 134 be allocated by the ext_off field in the header while other may be allocated by
 135 extensions. All clusters allocated by ext_off and extensions should meet the
 136 same requirements as clusters specified by BAT entries.
 137
 138
 139 == Format Extension ==
 140
 141 The Format Extension is an area 1 cluster in size that provides additional
 142 format features. This cluster is addressed by the ext_off field in the header.
 143 The 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
 155 Each 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
 194 This feature provides a way of storing dirty bitmaps in the image. The fields
 195 of 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 (64 * l1_size bytes)
 212               L1 offset table (in bytes)
 213
 214 A dirty bitmap is stored using a one-level structure for the mapping to host
 215 clusters - an L1 table.
 216
 217 Given an offset in bytes into the bitmap data, the offset in bytes into the
 218 image file can be obtained as follows:
 219
 220     offset = l1_table[offset / cluster_size] + (offset % cluster_size)
 221
 222 If an L1 table entry is 0, the corresponding cluster of the bitmap is assumed
 223 to be zero.
 224
 225 If an L1 table entry is 1, the corresponding cluster of the bitmap is assumed
 226 to have all bits set.
 227
 228 If an L1 table entry is not 0 or 1, it allocates a cluster from the data area.