vma_spec.txt

   1 = Virtual Machine Archive format (VMA) =
   2
   3 This format contains a header which includes the VM configuration as
   4 binary blobs, and a list of devices (dev_id, name).
   5
   6 The actual VM image data is stored inside extents. An extent contains
   7 up to 64 clusters, and start with a 512 byte header containing
   8 additional information for those clusters.
   9
  10 We use a cluster size of 65536, and use 8 bytes for each
  11 cluster in the header to store the following information:
  12
  13 * 1 byte dev_id (to identity the drive)
  14 * 1 byte not used (reserved)
  15 * 2 bytes zero indicator (mark zero regions (16x4096))
  16 * 4 bytes cluster number
  17
  18 We only store non-zero blocks (such block is 4096 bytes).
  19
  20 Each archive is marked with a uuid. The archive header and all
  21 extent headers includes that uuid and a MD5 checksum (over header
  22 data).
  23
  24 All numbers in VMA archive are stored in Big Endian byte order.
  25
  26 == VMA Header ==
  27
  28     Byte  0 -  3:   magic
  29                     VMA magic string ("VMA\x00")
  30
  31           4 -  7:   version
  32                     Version number (valid value is 1)
  33
  34           8 - 23:   uuid
  35                     Unique ID, Same uuid is used to mark extents.
  36
  37          24 - 31:   ctime
  38                     Backup time stamp (seconds since epoch)
  39
  40          32 - 47:   md5sum
  41                     Header checksum (from byte 0 to header_size). This field
  42                     is filled with zero to generate the checksum.
  43
  44          48 - 51:   blob_buffer_offset
  45                     Start of blob buffer (multiple of 512)
  46
  47          52 - 55:   blob_buffer_size
  48                     Size of blob buffer (multiple of 512)
  49
  50          56 - 59:   header_size
  51                     Overall size of this header (multiple of 512)
  52
  53          60 - 2043: reserved
  54
  55        2044 - 3067: uint32_t config_names[256]
  56                     Offsets into blob_buffer table
  57
  58        3068 - 4091: uint32_t config_data[256]
  59                     Offsets into blob_buffer table
  60
  61        4092 - 4095: reserved
  62
  63       4096 - 12287: VmaDeviceInfoHeader dev_info[256]
  64                     The offset in this table is used as 'dev_id' inside
  65                     the data streams.
  66
  67       12288 - header_size: Blob buffer
  68
  69
  70 === Devive Info Header (VmaDeviceInfoHeader) ===
  71
  72 This is use to store details about the contained disk images.
  73
  74     Byte  0 -  3:   devive name (offsets into blob_buffer table)
  75
  76           4 -  7:   reserved
  77
  78           8 - 15:   device size in bytes
  79
  80          16 - 31:   reserved
  81
  82 Note: Devive name 'vmstate' is reserved to store VM RAM state.
  83
  84 === Blob buffer ===
  85
  86 The blob buffer is used to store both configuration file names and
  87 configuration data.
  88
  89 This region contain a list of binary data blobs. Each blob starts with
  90 a 2 byte size field, followed by the actual data.
  91
  92 == Image Data Streams ==
  93
  94 The VMA header is followed by the image data stream. Image data is grouped
  95 with extents, which contains up to 59 clusters from different images.
  96
  97 === VMA Extent Header ===
  98
  99     Byte  0 -  3:   magic
 100                     VMA extent magic string ("VMAE")
 101
 102           4 -  5:   reserved
 103
 104           6 -  7:   block_count
 105                     Overall number of contained 4K block
 106
 107           8 - 23:   uuid
 108                     Unique ID, Same uuid as used in the VMA header.
 109
 110          24 - 39:   md5sum
 111                     Header checksum (from byte 0 to header_size). This field
 112                     is filled with zero to generate the checksum.
 113
 114         40 - 511:   blockinfo[59]
 115
 116
 117 Each 'blockinfo' (8 bytes) give further details about contained clusters:
 118
 119     Byte  0 - 1:   mask
 120                    Bitmap used to indicate non-zero 4K blocks inside the
 121                    cluster.
 122
 123               2:   reserved
 124
 125               3:   dev_id
 126                    Device ID (offset into dev_info table)
 127
 128           4 - 7:   cluster_num
 129
 130 The extend header if followed by the actual cluster data, where we only
 131 store non-zero 4K blocks.
 132