xref: /openbmc/qemu/docs/interop/prl-xml.rst (revision 05caa062)
1Parallels Disk Format
2=====================
3
4..
5   Copyright (c) 2015-2017, Virtuozzo, Inc.
6   Authors:
7        2015 Denis Lunev <den@openvz.org>
8        2015 Vladimir Sementsov-Ogievskiy <vsementsov@virtuozzo.com>
9        2016-2017 Klim Kireev <klim.kireev@virtuozzo.com>
10        2016-2017 Edgar Kaziakhmedov <edgar.kaziakhmedov@virtuozzo.com>
11
12   This work is licensed under the terms of the GNU GPL, version 2 or later.
13   See the COPYING file in the top-level directory.
14
15This specification contains minimal information about Parallels Disk Format,
16which is enough to properly work with QEMU. Nevertheless, Parallels Cloud Server
17and Parallels Desktop are able to add some unspecified nodes to the xml and use
18them, but they are for internal work and don't affect functionality. Also it
19uses auxiliary xml ``Snapshot.xml``, which allows storage of optional snapshot
20information, but this doesn't influence open/read/write functionality. QEMU and
21other software should not use fields not covered in this document or the
22``Snapshot.xml`` file, and must leave them as is.
23
24A Parallels disk consists of two parts: the set of snapshots and the disk
25descriptor file, which stores information about all files and snapshots.
26
27Definitions
28-----------
29
30Snapshot
31  a record of the contents captured at a particular time, capable
32  of storing current state. A snapshot has a UUID and a parent UUID.
33
34Snapshot image
35  an overlay representing the difference between this
36  snapshot and some earlier snapshot.
37
38Overlay
39  an image storing the different sectors between two captured states.
40
41Root image
42  a snapshot image with no parent, the root of the snapshot tree.
43
44Storage
45  the backing storage for a subset of the virtual disk. When
46  there is more than one storage in a Parallels disk then that
47  is referred to as a split image. In this case every storage
48  covers a specific address space area of the disk and has its
49  particular root image. Split images are not considered here
50  and are not supported. Each storage consists of disk
51  parameters and a list of images. The list of images always
52  contains a root image and may also contain overlays. The
53  root image can be an expandable Parallels image file or
54  plain. Overlays must be expandable.
55
56Description file
57  ``DiskDescriptor.xml`` stores information about disk parameters,
58  snapshots, and storages.
59
60Top Snapshot
61  The overlay between actual state and some previous snapshot.
62  It is not a snapshot in the classical sense because it
63  serves as the active image that the guest writes to.
64
65Sector
66  a 512-byte data chunk.
67
68Description file
69----------------
70
71All information is placed in a single XML element
72``Parallels_disk_image``.
73The element has only one attribute, ``Version``, which must be ``1.0``.
74
75The schema of ``DiskDescriptor.xml``::
76
77 <Parallels_disk_image Version="1.0">
78    <Disk_Parameters>
79        ...
80    </Disk_Parameters>
81    <StorageData>
82        ...
83    </StorageData>
84    <Snapshots>
85        ...
86    </Snapshots>
87 </Parallels_disk_image>
88
89``Disk_Parameters`` element
90^^^^^^^^^^^^^^^^^^^^^^^^^^^
91
92The ``Disk_Parameters`` element describes the physical layout of the
93virtual disk and some general settings.
94
95The ``Disk_Parameters`` element MUST contain the following child elements:
96
97* ``Disk_size`` - number of sectors in the disk,
98  desired size of the disk.
99* ``Cylinders`` - number of the disk cylinders.
100* ``Heads``     - number of the disk heads.
101* ``Sectors``   - number of the disk sectors per cylinder
102  (sector size is 512 bytes)
103  Limitation: The product of the ``Heads``, ``Sectors`` and ``Cylinders``
104  values MUST be equal to the value of the Disk_size parameter.
105* ``Padding``   - must be 0. Parallels Cloud Server and Parallels Desktop may
106  use padding set to 1; however this case is not covered
107  by this specification. QEMU and other software should not open
108  such disks and should not create them.
109
110``StorageData`` element
111^^^^^^^^^^^^^^^^^^^^^^^
112
113This element of the file describes the root image and all snapshot images.
114
115The ``StorageData`` element consists of the ``Storage`` child element,
116as shown below::
117
118 <StorageData>
119    <Storage>
120        ...
121    </Storage>
122 </StorageData>
123
124A ``Storage`` element has the following child elements:
125
126* ``Start``     - start sector of the storage, in case of non split storage
127  equals to 0.
128* ``End``       - number of sector following the last sector, in case of non
129  split storage equals to ``Disk_size``.
130* ``Blocksize`` - storage cluster size, number of sectors per one cluster.
131  The cluster size for each "Compressed" (see below) image in
132  a parallels disk must be equal to this field. Note: the cluster
133  size for a Parallels Expandable Image is in the ``tracks`` field of
134  its header (see :doc:`parallels`).
135* Several ``Image`` child elements.
136
137Each ``Image`` element has the following child elements:
138
139* ``GUID`` - image identifier, UUID in curly brackets.
140  For instance, ``{12345678-9abc-def1-2345-6789abcdef12}.``
141  The GUID is used by the Snapshots element to reference images
142  (see below)
143* ``Type`` - image type of the element. It can be:
144
145  * ``Plain`` for raw files.
146  * ``Compressed`` for expanding disks.
147
148* ``File`` - path to image file. The path can be relative to
149  ``DiskDescriptor.xml`` or absolute.
150
151``Snapshots`` element
152^^^^^^^^^^^^^^^^^^^^^
153
154The ``Snapshots`` element describes the snapshot relations with the snapshot tree.
155
156The element contains the set of ``Shot`` child elements, as shown below::
157
158 <Snapshots>
159    <TopGUID> ... </TopGUID> /* Optional child element */
160    <Shot>
161        ...
162    </Shot>
163    <Shot>
164        ...
165    </Shot>
166    ...
167 </Snapshots>
168
169Each ``Shot`` element contains the following child elements:
170
171* ``GUID``       - an image GUID.
172* ``ParentGUID`` - GUID of the image of the parent snapshot.
173
174The software may traverse snapshots from child to parent using the
175``<ParentGUID>`` field as reference. The ``ParentGUID`` of the root
176snapshot is ``{00000000-0000-0000-0000-000000000000}``.
177There should be only one root snapshot.
178
179The Top snapshot could be
180described via two ways: via the ``TopGUID`` child
181element of the ``Snapshots`` element, or via the predefined GUID
182``{5fbaabe3-6958-40ff-92a7-860e329aab41}``. If ``TopGUID`` is defined,
183the predefined GUID is interpreted as a normal GUID. All snapshot images
184(except the Top Snapshot) should be
185opened read-only.
186
187There is another predefined GUID,
188``BackupID = {704718e1-2314-44c8-9087-d78ed36b0f4e}``, which is used by
189original and some third-party software for backup. QEMU and other
190software may operate with images with ``GUID = BackupID`` as usual.
191However, it is not recommended to use this
192GUID for new disks. The Top snapshot cannot have this GUID.
193