motorhead/qemu
1
0
Fork 0
mirror of https://github.com/Motorhead1991/qemu.git synced 2025-08-27 03:51:57 -06:00
Code Issues Projects Releases Packages Wiki Activity Actions

docs/interop/prl-xml.rst: Fix minor grammar nits

Browse source 
Fix some minor grammar nits in the prl-xml documentation.

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-6-peter.maydell@linaro.org
This commit is contained in:
Peter Maydell 2024-08-09 17:37:55 +01:00
parent 7d9fc7e74d
commit 09334420d2
1 changed files with 39 additions and 34 deletions
Download patch file Download diff file Expand all files Collapse all files

73
docs/interop/prl-xml.rst
View file

@ -13,15 +13,15 @@ Parallels Disk Format
See the COPYING file in the top-level directory. See the COPYING file in the top-level directory.
This specification contains minimal information about Parallels Disk Format, This specification contains minimal information about Parallels Disk Format,
which is enough to proper work with QEMU. Nevertheless, Parallels Cloud Server which is enough to properly work with QEMU. Nevertheless, Parallels Cloud Server
and Parallels Desktop are able to add some unspecified nodes to xml and use and Parallels Desktop are able to add some unspecified nodes to the xml and use
them, but they are for internal work and don't affect functionality. Also it 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 uses auxiliary xml ``Snapshot.xml``, which allows storage of optional snapshot
information, but it doesn't influence open/read/write functionality. QEMU and information, but this doesn't influence open/read/write functionality. QEMU and
other software should not use fields not covered in this document and other software should not use fields not covered in this document or the
``Snapshot.xml`` file and must leave them as is. ``Snapshot.xml`` file, and must leave them as is.
Parallels disk consists of two parts: the set of snapshots and the disk A Parallels disk consists of two parts: the set of snapshots and the disk
descriptor file, which stores information about all files and snapshots. descriptor file, which stores information about all files and snapshots.
Definitions Definitions
@ -29,7 +29,7 @@ Definitions
Snapshot Snapshot
a record of the contents captured at a particular time, capable a record of the contents captured at a particular time, capable
of storing current state. A snapshot has UUID and parent UUID. of storing current state. A snapshot has a UUID and a parent UUID.
Snapshot image Snapshot image
an overlay representing the difference between this an overlay representing the difference between this
@ -39,13 +39,13 @@ Overlay
an image storing the different sectors between two captured states. an image storing the different sectors between two captured states.
Root image Root image
snapshot image with no parent, the root of snapshot tree. a snapshot image with no parent, the root of the snapshot tree.
Storage Storage
the backing storage for a subset of the virtual disk. When the backing storage for a subset of the virtual disk. When
there is more than one storage in a Parallels disk then that there is more than one storage in a Parallels disk then that
is referred to as a split image. In this case every storage is referred to as a split image. In this case every storage
covers specific address space area of the disk and has its covers a specific address space area of the disk and has its
particular root image. Split images are not considered here particular root image. Split images are not considered here
and are not supported. Each storage consists of disk and are not supported. Each storage consists of disk
parameters and a list of images. The list of images always parameters and a list of images. The list of images always
@ -55,7 +55,7 @@ Storage
Description file Description file
``DiskDescriptor.xml`` stores information about disk parameters, ``DiskDescriptor.xml`` stores information about disk parameters,
snapshots, storages. snapshots, and storages.
Top Snapshot Top Snapshot
The overlay between actual state and some previous snapshot. The overlay between actual state and some previous snapshot.
@ -70,9 +70,9 @@ Description file
All information is placed in a single XML element All information is placed in a single XML element
``Parallels_disk_image``. ``Parallels_disk_image``.
The element has only one attribute ``Version``, that must be ``1.0``. The element has only one attribute, ``Version``, which must be ``1.0``.
Schema of ``DiskDescriptor.xml``:: The schema of ``DiskDescriptor.xml``::
<Parallels_disk_image Version="1.0"> <Parallels_disk_image Version="1.0">
<Disk_Parameters> <Disk_Parameters>
@ -100,11 +100,11 @@ The ``Disk_Parameters`` element MUST contain the following child elements:
* ``Heads`` - number of the disk heads. * ``Heads`` - number of the disk heads.
* ``Sectors`` - number of the disk sectors per cylinder * ``Sectors`` - number of the disk sectors per cylinder
(sector size is 512 bytes) (sector size is 512 bytes)
Limitation: Product of the ``Heads``, ``Sectors`` and ``Cylinders`` Limitation: The product of the ``Heads``, ``Sectors`` and ``Cylinders``
values MUST be equal to the value of the Disk_size parameter. values MUST be equal to the value of the Disk_size parameter.
* ``Padding`` - must be 0. Parallels Cloud Server and Parallels Desktop may * ``Padding`` - must be 0. Parallels Cloud Server and Parallels Desktop may
use padding set to 1, however this case is not covered use padding set to 1; however this case is not covered
by this spec, QEMU and other software should not open by this specification. QEMU and other software should not open
such disks and should not create them. such disks and should not create them.
``StorageData`` element ``StorageData`` element
@ -121,20 +121,20 @@ as shown below::
</Storage> </Storage>
</StorageData> </StorageData>
A ``Storage`` element has following child elements: A ``Storage`` element has the following child elements:
* ``Start`` - start sector of the storage, in case of non split storage * ``Start`` - start sector of the storage, in case of non split storage
equals to 0. equals to 0.
* ``End`` - number of sector following the last sector, in case of non * ``End`` - number of sector following the last sector, in case of non
split storage equals to ``Disk_size``. split storage equals to ``Disk_size``.
* ``Blocksize`` - storage cluster size, number of sectors per one cluster. * ``Blocksize`` - storage cluster size, number of sectors per one cluster.
Cluster size for each "Compressed" (see below) image in The cluster size for each "Compressed" (see below) image in
parallels disk must be equal to this field. Note: cluster a parallels disk must be equal to this field. Note: the cluster
size for Parallels Expandable Image is in ``tracks`` field of size for a Parallels Expandable Image is in the ``tracks`` field of
its header (see :doc:`parallels`). its header (see :doc:`parallels`).
* Several ``Image`` child elements. * Several ``Image`` child elements.
Each ``Image`` element has following child elements: Each ``Image`` element has the following child elements:
* ``GUID`` - image identifier, UUID in curly brackets. * ``GUID`` - image identifier, UUID in curly brackets.
For instance, ``{12345678-9abc-def1-2345-6789abcdef12}.`` For instance, ``{12345678-9abc-def1-2345-6789abcdef12}.``
@ -145,7 +145,7 @@ Each ``Image`` element has following child elements:
* ``Plain`` for raw files. * ``Plain`` for raw files.
* ``Compressed`` for expanding disks. * ``Compressed`` for expanding disks.
* ``File`` - path to image file. Path can be relative to * ``File`` - path to image file. The path can be relative to
``DiskDescriptor.xml`` or absolute. ``DiskDescriptor.xml`` or absolute.
``Snapshots`` element ``Snapshots`` element
@ -171,17 +171,22 @@ Each ``Shot`` element contains the following child elements:
* ``GUID`` - an image GUID. * ``GUID`` - an image GUID.
* ``ParentGUID`` - GUID of the image of the parent snapshot. * ``ParentGUID`` - GUID of the image of the parent snapshot.
The software may traverse snapshots from child to parent using ``<ParentGUID>`` The software may traverse snapshots from child to parent using the
field as reference. ``ParentGUID`` of root snapshot is ``<ParentGUID>`` field as reference. The ``ParentGUID`` of the root
``{00000000-0000-0000-0000-000000000000}``. There should be only one root snapshot is ``{00000000-0000-0000-0000-000000000000}``.
snapshot. Top snapshot could be described via two ways: via ``TopGUID`` child There should be only one root snapshot.
element of the ``Snapshots`` element or via predefined GUID
The Top snapshot could be
described via two ways: via the ``TopGUID`` child
element of the ``Snapshots`` element, or via the predefined GUID
``{5fbaabe3-6958-40ff-92a7-860e329aab41}``. If ``TopGUID`` is defined, ``{5fbaabe3-6958-40ff-92a7-860e329aab41}``. If ``TopGUID`` is defined,
predefined GUID is interpreted as usual GUID. All snapshot images the predefined GUID is interpreted as a normal GUID. All snapshot images
(except Top Snapshot) should be (except the Top Snapshot) should be
opened read-only. There is another predefined GUID, opened read-only.
There is another predefined GUID,
``BackupID = {704718e1-2314-44c8-9087-d78ed36b0f4e}``, which is used by ``BackupID = {704718e1-2314-44c8-9087-d78ed36b0f4e}``, which is used by
original and some third-party software for backup, QEMU and other original and some third-party software for backup. QEMU and other
software may operate with images with ``GUID = BackupID`` as usual, software may operate with images with ``GUID = BackupID`` as usual.
however, it is not recommended to use this However, it is not recommended to use this
GUID for new disks. Top snapshot cannot have this GUID. GUID for new disks. The Top snapshot cannot have this GUID.