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

4 files changed, 189 insertions, 158 deletions

diff --git a/MAINTAINERS b/MAINTAINERS
index ae8bed8c75..3584d6a6c6 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -3965,6 +3965,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
diff --git a/docs/interop/index.rst b/docs/interop/index.rst
index 70bba62d90..999e44eae1 100644
--- a/docs/interop/index.rst
+++ b/docs/interop/index.rst
@@ -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
diff --git a/docs/interop/prl-xml.rst b/docs/interop/prl-xml.rst
new file mode 100644
index 0000000000..aacf11f4c4
--- /dev/null
+++ b/docs/interop/prl-xml.rst
@@ -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.
diff --git a/docs/interop/prl-xml.txt b/docs/interop/prl-xml.txt
deleted file mode 100644
index cf9b3fba26..0000000000
--- a/docs/interop/prl-xml.txt
+++ /dev/null
@@ -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.