@@ -3963,6 +3963,7 @@ S: Supported
F: block/parallels.c
F: block/parallels-ext.c
F: docs/interop/parallels.rst
+F: docs/interop/prl-xml.rst
T: git https://src.openvz.org/scm/~den/qemu.git parallels
qed
@@ -16,6 +16,7 @@ are useful for making QEMU interoperate with other software.
live-block-operations
nbd
parallels
+ prl-xml
pr-helper
qmp-spec
qemu-ga
new file mode 100644
@@ -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.
deleted file mode 100644
@@ -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.
Convert prl-xml.txt to rST format. Signed-off-by: Peter Maydell <peter.maydell@linaro.org> --- MAINTAINERS | 1 + docs/interop/index.rst | 1 + docs/interop/prl-xml.rst | 187 +++++++++++++++++++++++++++++++++++++++ docs/interop/prl-xml.txt | 158 --------------------------------- 4 files changed, 189 insertions(+), 158 deletions(-) create mode 100644 docs/interop/prl-xml.rst delete mode 100644 docs/interop/prl-xml.txt