docs/interop/prl-xml.txt: Convert to rST
Convert prl-xml.txt to rST format. Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Reviewed-by: Richard Henderson <richard.henderson@linaro.org> Reviewed-by: Eric Blake <eblake@redhat.com> Message-id: 20240801170131.3977807-5-peter.maydell@linaro.org
This commit is contained in:
Peter Maydell
parent
1bc0fc0a0b
commit
7d9fc7e74d
@ -3965,6 +3965,7 @@ S: Supported
|
|||||||
F: block/parallels.c
|
F: block/parallels.c
|
||||||
F: block/parallels-ext.c
|
F: block/parallels-ext.c
|
||||||
F: docs/interop/parallels.rst
|
F: docs/interop/parallels.rst
|
||||||
|
F: docs/interop/prl-xml.rst
|
||||||
T: git https://src.openvz.org/scm/~den/qemu.git parallels
|
T: git https://src.openvz.org/scm/~den/qemu.git parallels
|
||||||
|
|
||||||
qed
|
qed
|
||||||
|
|||||||
@ -16,6 +16,7 @@ are useful for making QEMU interoperate with other software.
|
|||||||
live-block-operations
|
live-block-operations
|
||||||
nbd
|
nbd
|
||||||
parallels
|
parallels
|
||||||
|
prl-xml
|
||||||
pr-helper
|
pr-helper
|
||||||
qmp-spec
|
qmp-spec
|
||||||
qemu-ga
|
qemu-ga
|
||||||
|
|||||||
187
docs/interop/prl-xml.rst
Normal file
187
docs/interop/prl-xml.rst
Normal file
@ -0,0 +1,187 @@
|
|||||||
|
Parallels Disk Format
|
||||||
|
=====================
|
||||||
|
|
||||||
|
..
|
||||||
|
Copyright (c) 2015-2017, Virtuozzo, Inc.
|
||||||
|
Authors:
|
||||||
|
2015 Denis Lunev <den@openvz.org>
|
||||||
|
2015 Vladimir Sementsov-Ogievskiy <vsementsov@virtuozzo.com>
|
||||||
|
2016-2017 Klim Kireev <klim.kireev@virtuozzo.com>
|
||||||
|
2016-2017 Edgar Kaziakhmedov <edgar.kaziakhmedov@virtuozzo.com>
|
||||||
|
|
||||||
|
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 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 file
|
||||||
|
``DiskDescriptor.xml`` stores information about disk parameters,
|
||||||
|
snapshots, storages.
|
||||||
|
|
||||||
|
Top Snapshot
|
||||||
|
The overlay between actual state and some previous 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 :doc:`parallels`).
|
||||||
|
* 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
|
||||||
|
``DiskDescriptor.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.
|
||||||
@ -1,158 +0,0 @@
|
|||||||
= License =
|
|
||||||
|
|
||||||
Copyright (c) 2015-2017, Virtuozzo, Inc.
|
|
||||||
Authors:
|
|
||||||
2015 Denis Lunev <den@openvz.org>
|
|
||||||
2015 Vladimir Sementsov-Ogievskiy <vsementsov@virtuozzo.com>
|
|
||||||
2016-2017 Klim Kireev <klim.kireev@virtuozzo.com>
|
|
||||||
2016-2017 Edgar Kaziakhmedov <edgar.kaziakhmedov@virtuozzo.com>
|
|
||||||
|
|
||||||
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 DiskDescriptor.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.
|
|
||||||
Loading…
x
Reference in New Issue
Block a user