a99f5f9beafecc01a19c3a33a0eb54baf4acf9a0
[pve-qemu.git] / 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