[qemu.git] / docs / interop / prl-xml.txt

= License =

Copyright (c) 2015-2017, Virtuozzo, Inc.
Authors:
        2015 Denis Lunev <[email protected]>
        2015 Vladimir Sementsov-Ogievskiy <[email protected]>
        2016-2017 Klim Kireev <[email protected]>
        2016-2017 Edgar Kaziakhmedov <[email protected]>

This work is licensed under the terms of the GNU GPL, version 2 or later.
See the COPYING file in the top-level directory.

This specification contains minimal information about Parallels Disk Format,
which is enough to proper work with QEMU. Nevertheless, Parallels Cloud Server
and Parallels Desktop are able to add some unspecified nodes to xml and use
them, but they are for internal work and don't affect functionality. Also it
uses auxiliary xml "Snapshot.xml", which allows to store optional snapshot
information, but it doesn't influence open/read/write functionality. QEMU and
other software should not use fields not covered in this document and
Snapshot.xml file and must leave them as is.

= Parallels Disk Format =

Parallels disk consists of two parts: the set of snapshots and the disk
descriptor file, which stores information about all files and snapshots.

== Definitions ==
    Snapshot       a record of the contents captured at a particular time,
                   capable of storing current state. A snapshot has UUID and
                   parent UUID.

 Snapshot image    an overlay representing the difference between this
                   snapshot and some earlier snapshot.

    Overlay        an image storing the different sectors between two captured
                   states.

   Root image      snapshot image with no parent, the root of snapshot tree.

    Storage        the backing storage for a subset of the virtual disk. When
                   there is more than one storage in a Parallels disk then that
                   is referred to as a split image. In this case every storage
                   covers specific address space area of the disk and has its
                   particular root image. Split images are not considered here
                   and are not supported. Each storage consists of disk
                   parameters and a list of images. The list of images always
                   contains a root image and may also contain overlays. The
                   root image can be an expandable Parallels image file or
                   plain. Overlays must be expandable.

  Description      DiskDescriptor.xml stores information about disk parameters,
     file          snapshots, storages.

     Top           The overlay between actual state and some previous snapshot.
   Snapshot        It is not a snapshot in the classical sense because it
                   serves as the active image that the guest writes to.

    Sector         a 512-byte data chunk.

== Description file ==
All information is placed in a single XML element Parallels_disk_image.
The element has only one attribute "Version", that must be 1.0.
Schema of DiskDescriptor.xml:

<Parallels_disk_image Version="1.0">
    <Disk_Parameters>
        ...
    </Disk_Parameters>
    <StorageData>
        ...
    </StorageData>
    <Snapshots>
        ...
    </Snapshots>
</Parallels_disk_image>

== Disk_Parameters element ==
The Disk_Parameters element describes the physical layout of the virtual disk
and some general settings.

The Disk_Parameters element MUST contain the following child elements:
    * Disk_size - number of sectors in the disk,
                  desired size of the disk.
    * Cylinders - number of the disk cylinders.
    * Heads     - number of the disk heads.
    * Sectors   - number of the disk sectors per cylinder
                  (sector size is 512 bytes)
                  Limitation: Product of the Heads, Sectors and Cylinders
                  values MUST be equal to the value of the Disk_size parameter.
    * Padding   - must be 0. Parallels Cloud Server and Parallels Desktop may
                  use padding set to 1, however this case is not covered
                  by this spec, QEMU and other software should not open
                  such disks and should not create them.

== StorageData element ==
This element of the file describes the root image and all snapshot images.

The StorageData element consists of the Storage child element, as shown below:
<StorageData>
    <Storage>
        ...
    </Storage>
</StorageData>

A Storage element has following child elements:
    * Start     - start sector of the storage, in case of non split storage
                  equals to 0.
    * End       - number of sector following the last sector, in case of non
                  split storage equals to Disk_size.
    * Blocksize - storage cluster size, number of sectors per one cluster.
                  Cluster size for each "Compressed" (see below) image in
                  parallels disk must be equal to this field. Note: cluster
                  size for Parallels Expandable Image is in 'tracks' field of
                  its header (see docs/interop/parallels.txt).
    * Several Image child elements.

Each Image element has following child elements:
    * GUID - image identifier, UUID in curly brackets.
             For instance, {12345678-9abc-def1-2345-6789abcdef12}.
             The GUID is used by the Snapshots element to reference images
             (see below)
    * Type - image type of the element. It can be:
             "Plain" for raw files.
             "Compressed" for expanding disks.
    * File - path to image file. Path can be relative to DiskDecriptor.xml or
             absolute.

== Snapshots element ==
The Snapshots element describes the snapshot relations with the snapshot tree.

The element contains the set of Shot child elements, as shown below:
<Snapshots>
    <TopGUID> ... </TopGUID> /* Optional child element */
    <Shot>
        ...
    </Shot>
    <Shot>
        ...
    </Shot>
    ...
</Snapshots>

Each Shot element contains the following child elements:
    * GUID       - an image GUID.
    * ParentGUID - GUID of the image of the parent snapshot.

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