[Qemu-devel] [PATCH 0/5] preparation for Parallels Disk xml driver

[Qemu-devel] [PATCH 0/5] preparation for Parallels Disk xml driver

[Denis V. Lunev]

Parallels Desktop and Parallels Cloud Server uses images glued with the
bundle description in XML format. This series contains very basic
description of this XML files and makes preparations for actual
implementation to be followed.

Signed-off-by: Edgar Kaziakhmedov <edgar.kaziakhmedov@virtuozzo.com>
Signed-off-by: Klim Kireev <klim.kireev@virtuozzo.com>
Signed-off-by: Vladimir Sementsov-Ogievskiy <vsementsov@virtuozzo.com>
Signed-off-by: Denis V. Lunev <den@openvz.org>
CC: Stefan Hajnoczi <stefanha@redhat.com>

[Qemu-devel] [PATCH 1/5] docs/interop/prl-xml: description of Parallels Disk format

[Denis V. Lunev]

From: Klim Kireev <klim.kireev@virtuozzo.com>

This patch adds main information about Parallels Disk
format, which consists of DiskDescriptor.xml and other files.

Signed-off-by: Edgar Kaziakhmedov <edgar.kaziakhmedov@virtuozzo.com>
Signed-off-by: Klim Kireev <klim.kireev@virtuozzo.com>
Signed-off-by: Vladimir Sementsov-Ogievskiy <vsementsov@virtuozzo.com>
Signed-off-by: Denis V. Lunev <den@openvz.org>
CC: Stefan Hajnoczi <stefanha@redhat.com>
---
 docs/interop/prl-xml.txt | 155 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 155 insertions(+)
 create mode 100644 docs/interop/prl-xml.txt

diff --git a/docs/interop/prl-xml.txt b/docs/interop/prl-xml.txt
new file mode 100644
index 0000000..8ccb91a
--- /dev/null
+++ b/docs/interop/prl-xml.txt
@@ -0,0 +1,155 @@
+= License =
+
+Copyright (c) 2015 Denis Lunev
+Copyright (c) 2015 Vladimir Sementsov-Ogievskiy
+Copyright (c) 2016-2017 Klim Kireev
+Copyright (c) 2016-2017 Edgar Kaziakhmedov
+
+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 unspecified here fields 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 without parent, the root of snapshot tree.
+
+    Storage        a special conception of data, which consists of disk
+                   parameters and a list of images. One of this image is root,
+                   others are overlays. Images must be expandable (parallels
+                   image file), however root image could be expandable or
+                   plain. There may be more then one storage in the Parallels
+                   disk and it is defined 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 isn't supported
+                   in QEMU.
+
+  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 classical meaning.
+
+    Sector         a 512-byte data chunk.
+
+== Description file ==
+All information is placed in single XML section Parallels_disk_image.
+The section has only one attribute "Version", that must be 1.0.
+General structure of DiskDescriptor.xml:
+
+<Parallels_disk_image Version="1.0">
+    <Disk_Parameters>
+        ...
+    </Disk_Parameters>
+    <StorageData>
+        ...
+    </StorageData>
+    <Snapshots>
+        ...
+    </Snapshots>
+</Parallels_disk_image>
+
+== Disk_Parameters section ==
+The Disk_Parameters section describes the physical layout of the virtual disk
+and some general settings.
+
+The Disk_Parameters section MUST contain the following subsections:
+    * 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.
+                  Attention: this field affects the read/write functionality.
+
+== StorageData section ==
+This section of the file describes root image and all snapshot images.
+
+The StorageData section consists of the Storage subsection, as shown below:
+<StorageData>
+    <Storage>
+        ...
+    </Storage>
+</StorageData>
+
+A Storage descriptor consists of the following subsections:
+    * Start     - start sector of the storage, equals to 0.
+    * End       - number of sectors in 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 subsections.
+
+Each Image section consists of the following subsections:
+    * GUID - image identifier, UUID in curly brackets.
+             For instance, {12345678-9abc-def1-2345-6789abcdef12}.
+    * Type - image type of the element. It can be:
+             "Plain" for plain disks.
+             "Compressed" for expanding disks.
+    * File - path to image file. Path can be relative to DiskDecriptor.xml or
+             absolute.
+
+== Snapshots section ==
+The Snapshots section describes the snapshot relations with the snapshot tree.
+
+The section contains the set of Shot subsections, as shown below:
+<Snapshots>
+    <TopGUID> ... </TopGUID> //Optional subsection
+    <Shot>
+        ...
+    </Shot>
+    <Shot>
+        ...
+    </Shot>
+    ...
+</Snapshots>
+
+Each Shot section contains the following subsections:
+    * 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 one root
+snapshot. Top snapshot could be described via two ways: via TopGUID subsection
+in the Snapshots section 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) sould be
+opened read-only.
+There is another predefined GIUD,
+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.
+
+NOTE: To address top snapshot QEMU supports only predefined GUID mode.
-- 
2.7.4

[Qemu-devel] [PATCH 2/5] configure: add dependency

[Denis V. Lunev]

From: Klim Kireev <klim.kireev@virtuozzo.com>

This dependency is required for adequate Parallels images support.
Typically the disk consists of several images which are glued by
XML disk descriptor. Also XML hides inside several important parameters
which are not available in the image header.

The patch also adds clause to checkpatch.pl to understand libxml2 types.

Signed-off-by: Denis V. Lunev <den@openvz.org>
Signed-off-by: Klim Kireev <klim.kireev@virtuozzo.com>
Signed-off-by: Edgar Kaziakhmedov <edgar.kaziakhmedov@virtuozzo.com>
CC: Stefan Hajnoczi <stefanha@redhat.com>
---
 configure             | 27 +++++++++++++++++++++++++++
 block/Makefile.objs   |  2 ++
 scripts/checkpatch.pl |  1 +
 3 files changed, 30 insertions(+)

diff --git a/configure b/configure
index 0c6e757..e988fd0 100755
--- a/configure
+++ b/configure
@@ -422,6 +422,7 @@ tcmalloc="no"
 jemalloc="no"
 replication="yes"
 vxhs=""
+libxml2=""
 
 supported_cpu="no"
 supported_os="no"
@@ -1275,6 +1276,10 @@ for opt do
   ;;
   --enable-numa) numa="yes"
   ;;
+  --disable-libxml2) libxml2="no"
+  ;;
+  --enable-libxml2) libxml2="yes"
+  ;;
   --disable-tcmalloc) tcmalloc="no"
   ;;
   --enable-tcmalloc) tcmalloc="yes"
@@ -1548,6 +1553,7 @@ disabled with --disable-FEATURE, default is enabled if available:
   tpm             TPM support
   libssh2         ssh block device support
   numa            libnuma support
+  libxml2         for Parallels image format
   tcmalloc        tcmalloc support
   jemalloc        jemalloc support
   replication     replication support
@@ -1592,6 +1598,20 @@ if test "$ARCH" = "unknown"; then
     fi
 fi
 
+# check for libxml2
+if test "$libxml2" != "no" ; then
+    if $pkg_config --exists libxml-2.0; then
+        libxml2="yes"
+        libxml2_cflags=$($pkg_config --cflags libxml-2.0)
+        libxml2_libs=$($pkg_config --libs libxml-2.0)
+    else
+        if test "$libxml2" = "yes"; then
+            feature_not_found "libxml2" "Install libxml2 devel"
+        fi
+        libxml2="no"
+    fi
+fi
+
 # Consult white-list to determine whether to enable werror
 # by default.  Only enable by default for git builds
 if test -z "$werror" ; then
@@ -5549,6 +5569,7 @@ echo "lzo support       $lzo"
 echo "snappy support    $snappy"
 echo "bzip2 support     $bzip2"
 echo "NUMA host support $numa"
+echo "libxml2           $libxml2"
 echo "tcmalloc support  $tcmalloc"
 echo "jemalloc support  $jemalloc"
 echo "avx2 optimization $avx2_opt"
@@ -6208,6 +6229,12 @@ if test "$have_rtnetlink" = "yes" ; then
   echo "CONFIG_RTNETLINK=y" >> $config_host_mak
 fi
 
+if test "$libxml2" = "yes" ; then
+  echo "CONFIG_LIBXML2=y" >> $config_host_mak
+  echo "LIBXML2_CFLAGS=$libxml2_cflags" >> $config_host_mak
+  echo "LIBXML2_LIBS=$libxml2_libs" >> $config_host_mak
+fi
+
 if test "$replication" = "yes" ; then
   echo "CONFIG_REPLICATION=y" >> $config_host_mak
 fi
diff --git a/block/Makefile.objs b/block/Makefile.objs
index 6eaf78a..a73387f 100644
--- a/block/Makefile.objs
+++ b/block/Makefile.objs
@@ -47,3 +47,5 @@ block-obj-$(if $(CONFIG_BZIP2),m,n) += dmg-bz2.o
 dmg-bz2.o-libs     := $(BZIP2_LIBS)
 qcow.o-libs        := -lz
 linux-aio.o-libs   := -laio
+parallels.o-cflags := $(LIBXML2_CFLAGS)
+parallels.o-libs   := $(LIBXML2_LIBS)
diff --git a/scripts/checkpatch.pl b/scripts/checkpatch.pl
index 34df753..e76cc85 100755
--- a/scripts/checkpatch.pl
+++ b/scripts/checkpatch.pl
@@ -265,6 +265,7 @@ our @typeList = (
 	qr{${Ident}_handler_fn},
 	qr{target_(?:u)?long},
 	qr{hwaddr},
+	qr{xml${Ident}},
 );
 
 # This can be modified by sub possible.  Since it can be empty, be careful
-- 
2.7.4

[Qemu-devel] [PATCH 3/5] block/parallels: move some structures into header

[Denis V. Lunev]

From: Klim Kireev <klim.kireev@virtuozzo.com>

To implement xml format, some defines and structures
from parallels.c are required.

Signed-off-by: Klim Kireev <klim.kireev@virtuozzo.com>
Reviewed-by: Vladimir Sementsov-Ogievskiy <vsementsov@virtuozzo.com>
Signed-off-by: Denis V. Lunev <den@openvz.org>
CC: Stefan Hajnoczi <stefanha@redhat.com>
---
 block/parallels.h | 83 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 block/parallels.c | 53 +----------------------------------
 2 files changed, 84 insertions(+), 52 deletions(-)
 create mode 100644 block/parallels.h

diff --git a/block/parallels.h b/block/parallels.h
new file mode 100644
index 0000000..7d0fb73
--- /dev/null
+++ b/block/parallels.h
@@ -0,0 +1,83 @@
+/*
+* Block driver for Parallels disk image format
+*
+* Copyright (c) 2016-2017 Klim S. Kireev <klim.kireev@virtuozzo.com>
+* Copyright (c) 2015 Denis V. Lunev <den@openvz.org>
+*
+* This code was originally based on comparing different disk images created
+* by Parallels. Currently it is based on opened OpenVZ sources
+* available at
+*     https://github.com/OpenVZ/ploop
+*
+* Permission is hereby granted, free of charge, to any person obtaining a copy
+* of this software and associated documentation files (the "Software"), to deal
+* in the Software without restriction, including without limitation the rights
+* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+* copies of the Software, and to permit persons to whom the Software is
+* furnished to do so, subject to the following conditions:
+*
+* The above copyright notice and this permission notice shall be included in
+* all copies or substantial portions of the Software.
+*
+* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+* THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+* THE SOFTWARE.
+*/
+#ifndef BLOCK_PARALLELS_H
+#define BLOCK_PARALLELS_H
+#include "qemu/module.h"
+
+#define DEFAULT_CLUSTER_SIZE 1048576        /* 1 MiB */
+
+/* always little-endian */
+typedef struct ParallelsHeader {
+    char magic[16]; /* "WithoutFreeSpace" */
+    uint32_t version;
+    uint32_t heads;
+    uint32_t cylinders;
+    uint32_t tracks;
+    uint32_t bat_entries;
+    uint64_t nb_sectors;
+    uint32_t inuse;
+    uint32_t data_off;
+    char padding[12];
+} QEMU_PACKED ParallelsHeader;
+
+typedef enum ParallelsPreallocMode {
+    PRL_PREALLOC_MODE_FALLOCATE = 0,
+    PRL_PREALLOC_MODE_TRUNCATE = 1,
+    PRL_PREALLOC_MODE__MAX = 2,
+} ParallelsPreallocMode;
+
+typedef struct BDRVParallelsState {
+    /** Locking is conservative, the lock protects
+     *   - image file extending (truncate, fallocate)
+     *   - any access to block allocation table
+     */
+    CoMutex lock;
+
+    ParallelsHeader *header;
+    uint32_t header_size;
+    bool header_unclean;
+
+    unsigned long *bat_dirty_bmap;
+    unsigned int  bat_dirty_block;
+
+    uint32_t *bat_bitmap;
+    unsigned int bat_size;
+
+    int64_t  data_end;
+    uint64_t prealloc_size;
+    ParallelsPreallocMode prealloc_mode;
+
+    unsigned int tracks;
+
+    unsigned int off_multiplier;
+    Error *migration_blocker;
+} BDRVParallelsState;
+
+#endif
diff --git a/block/parallels.c b/block/parallels.c
index 9545761..f9a3b99 100644
--- a/block/parallels.c
+++ b/block/parallels.c
@@ -36,6 +36,7 @@
 #include "qemu/bswap.h"
 #include "qemu/bitmap.h"
 #include "migration/blocker.h"
+#include "parallels.h"
 
 /**************************************************************/
 
@@ -45,30 +46,6 @@
 #define HEADER_INUSE_MAGIC  (0x746F6E59)
 #define MAX_PARALLELS_IMAGE_FACTOR (1ull << 32)
 
-#define DEFAULT_CLUSTER_SIZE 1048576        /* 1 MiB */
-
-
-// always little-endian
-typedef struct ParallelsHeader {
-    char magic[16]; // "WithoutFreeSpace"
-    uint32_t version;
-    uint32_t heads;
-    uint32_t cylinders;
-    uint32_t tracks;
-    uint32_t bat_entries;
-    uint64_t nb_sectors;
-    uint32_t inuse;
-    uint32_t data_off;
-    char padding[12];
-} QEMU_PACKED ParallelsHeader;
-
-
-typedef enum ParallelsPreallocMode {
-    PRL_PREALLOC_MODE_FALLOCATE = 0,
-    PRL_PREALLOC_MODE_TRUNCATE = 1,
-    PRL_PREALLOC_MODE__MAX = 2,
-} ParallelsPreallocMode;
-
 static QEnumLookup prealloc_mode_lookup = {
     .array = (const char *const[]) {
         "falloc",
@@ -77,34 +54,6 @@ static QEnumLookup prealloc_mode_lookup = {
     .size = PRL_PREALLOC_MODE__MAX
 };
 
-typedef struct BDRVParallelsState {
-    /** Locking is conservative, the lock protects
-     *   - image file extending (truncate, fallocate)
-     *   - any access to block allocation table
-     */
-    CoMutex lock;
-
-    ParallelsHeader *header;
-    uint32_t header_size;
-    bool header_unclean;
-
-    unsigned long *bat_dirty_bmap;
-    unsigned int  bat_dirty_block;
-
-    uint32_t *bat_bitmap;
-    unsigned int bat_size;
-
-    int64_t  data_end;
-    uint64_t prealloc_size;
-    ParallelsPreallocMode prealloc_mode;
-
-    unsigned int tracks;
-
-    unsigned int off_multiplier;
-    Error *migration_blocker;
-} BDRVParallelsState;
-
-
 #define PARALLELS_OPT_PREALLOC_MODE     "prealloc-mode"
 #define PARALLELS_OPT_PREALLOC_SIZE     "prealloc-size"
 
-- 
2.7.4

[Qemu-devel] [PATCH 4/5] block/parallels: replace some magic numbers

[Denis V. Lunev]

From: Klim Kireev <klim.kireev@virtuozzo.com>

Signed-off-by: Klim Kireev <klim.kireev@virtuozzo.com>
Reviewed-by: Vladimir Sementsov-Ogievskiy <vsementsov@virtuozzo.com>
Signed-off-by: Denis V. Lunev <den@openvz.org>
CC: Stefan Hajnoczi <stefanha@redhat.com>
---
 block/parallels.h | 2 ++
 block/parallels.c | 5 +++--
 2 files changed, 5 insertions(+), 2 deletions(-)

diff --git a/block/parallels.h b/block/parallels.h
index 7d0fb73..9be29fe 100644
--- a/block/parallels.h
+++ b/block/parallels.h
@@ -31,6 +31,8 @@
 #define BLOCK_PARALLELS_H
 #include "qemu/module.h"
 
+#define HEADS_NUMBER 16
+#define SEC_IN_CYL 32
 #define DEFAULT_CLUSTER_SIZE 1048576        /* 1 MiB */
 
 /* always little-endian */
diff --git a/block/parallels.c b/block/parallels.c
index f9a3b99..7a8e8b0 100644
--- a/block/parallels.c
+++ b/block/parallels.c
@@ -476,8 +476,9 @@ static int parallels_create(const char *filename, QemuOpts *opts, Error **errp)
     memcpy(header.magic, HEADER_MAGIC2, sizeof(header.magic));
     header.version = cpu_to_le32(HEADER_VERSION);
     /* don't care much about geometry, it is not used on image level */
-    header.heads = cpu_to_le32(16);
-    header.cylinders = cpu_to_le32(total_size / BDRV_SECTOR_SIZE / 16 / 32);
+    header.heads = cpu_to_le32(HEADS_NUMBER);
+    header.cylinders = cpu_to_le32(total_size / BDRV_SECTOR_SIZE
+                                   / HEADS_NUMBER / SEC_IN_CYL);
     header.tracks = cpu_to_le32(cl_size >> BDRV_SECTOR_BITS);
     header.bat_entries = cpu_to_le32(bat_entries);
     header.nb_sectors = cpu_to_le64(DIV_ROUND_UP(total_size, BDRV_SECTOR_SIZE));
-- 
2.7.4

[Qemu-devel] [PATCH 5/5] block/parallels: add backing support to readv/writev

[Denis V. Lunev]

From: Edgar Kaziakhmedov <edgar.kaziakhmedov@virtuozzo.com>

Since parallels format supports backing files, refine
readv/writev (allocate_clusters) to redirect read/write requests
to a backing file (if cluster is not available in the current bs).

Signed-off-by: Edgar Kaziakhmedov <edgar.kaziakhmedov@virtuozzo.com>
Signed-off-by: Vladimir Sementsov-Ogievskiy <vsementsov@virtuozzo.com>
Signed-off-by: Denis V. Lunev <den@openvz.org>
CC: Stefan Hajnoczi <stefanha@redhat.com>
---
 block/parallels.c | 50 ++++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 44 insertions(+), 6 deletions(-)

diff --git a/block/parallels.c b/block/parallels.c
index 7a8e8b0..d380208 100644
--- a/block/parallels.c
+++ b/block/parallels.c
@@ -142,6 +142,7 @@ static int64_t block_status(BDRVParallelsState *s, int64_t sector_num,
 static int64_t allocate_clusters(BlockDriverState *bs, int64_t sector_num,
                                  int nb_sectors, int *pnum)
 {
+    int ret;
     BDRVParallelsState *s = bs->opaque;
     int64_t pos, space, idx, to_allocate, i, len;
 
@@ -170,7 +171,6 @@ static int64_t allocate_clusters(BlockDriverState *bs, int64_t sector_num,
         return len;
     }
     if (s->data_end + space > (len >> BDRV_SECTOR_BITS)) {
-        int ret;
         space += s->prealloc_size;
         if (s->prealloc_mode == PRL_PREALLOC_MODE_FALLOCATE) {
             ret = bdrv_pwrite_zeroes(bs->file,
@@ -186,6 +186,37 @@ static int64_t allocate_clusters(BlockDriverState *bs, int64_t sector_num,
         }
     }
 
+    /* Try to read from backing to fill empty clusters
+     * FIXME: 1. previous write_zeroes may be redundant
+     *        2. most of data we read from backing will be rewritten by
+     *           parallels_co_writev. On aligned-to-cluster write we do not need
+     *           this read at all.
+     *        3. it would be good to combine write of data from backing and new
+     *           data into one write call */
+    if (bs->backing) {
+        int64_t nb_cow_sectors = to_allocate * s->tracks;
+        int64_t nb_cow_bytes = nb_cow_sectors << BDRV_SECTOR_BITS;
+        QEMUIOVector qiov;
+        struct iovec iov = {
+            .iov_len = nb_cow_bytes,
+            .iov_base = qemu_blockalign(bs, nb_cow_bytes)
+        };
+        qemu_iovec_init_external(&qiov, &iov, 1);
+
+        ret = bdrv_co_readv(bs->backing, idx * s->tracks, nb_cow_sectors,
+                            &qiov);
+        if (ret < 0) {
+            qemu_vfree(iov.iov_base);
+            return ret;
+        }
+
+        ret = bdrv_co_writev(bs->file, s->data_end, nb_cow_sectors, &qiov);
+        qemu_vfree(iov.iov_base);
+        if (ret < 0) {
+            return ret;
+        }
+    }
+
     for (i = 0; i < to_allocate; i++) {
         s->bat_bitmap[idx + i] = cpu_to_le32(s->data_end / s->off_multiplier);
         s->data_end += s->tracks;
@@ -309,12 +340,19 @@ static coroutine_fn int parallels_co_readv(BlockDriverState *bs,
 
         nbytes = n << BDRV_SECTOR_BITS;
 
+        qemu_iovec_reset(&hd_qiov);
+        qemu_iovec_concat(&hd_qiov, qiov, bytes_done, nbytes);
+
         if (position < 0) {
-            qemu_iovec_memset(qiov, bytes_done, 0, nbytes);
+            if (bs->backing) {
+                ret = bdrv_co_readv(bs->backing, sector_num, n, &hd_qiov);
+                if (ret < 0) {
+                    break;
+                }
+            } else {
+                qemu_iovec_memset(&hd_qiov, 0, 0, nbytes);
+            }
         } else {
-            qemu_iovec_reset(&hd_qiov);
-            qemu_iovec_concat(&hd_qiov, qiov, bytes_done, nbytes);
-
             ret = bdrv_co_readv(bs->file, position, n, &hd_qiov);
             if (ret < 0) {
                 break;
@@ -748,7 +786,7 @@ static BlockDriver bdrv_parallels = {
     .bdrv_co_flush_to_os      = parallels_co_flush_to_os,
     .bdrv_co_readv  = parallels_co_readv,
     .bdrv_co_writev = parallels_co_writev,
-
+    .supports_backing = true,
     .bdrv_create    = parallels_create,
     .bdrv_check     = parallels_check,
     .create_opts    = &parallels_create_opts,
-- 
2.7.4

Re: [Qemu-devel] [Qemu-block] [PATCH 2/5] configure: add dependency

[Roman Kagan]

On Mon, Dec 18, 2017 at 02:09:08PM +0300, Denis V. Lunev wrote:
> From: Klim Kireev <klim.kireev@virtuozzo.com>
> 
> This dependency is required for adequate Parallels images support.
> Typically the disk consists of several images which are glued by
> XML disk descriptor. Also XML hides inside several important parameters
> which are not available in the image header.
> 
> The patch also adds clause to checkpatch.pl to understand libxml2 types.

Can't you get by with glib's GMarkup, to avoid extra dependencies?

https://developer.gnome.org/glib/stable/glib-Simple-XML-Subset-Parser.html

Roman.

> Signed-off-by: Denis V. Lunev <den@openvz.org>
> Signed-off-by: Klim Kireev <klim.kireev@virtuozzo.com>
> Signed-off-by: Edgar Kaziakhmedov <edgar.kaziakhmedov@virtuozzo.com>
> CC: Stefan Hajnoczi <stefanha@redhat.com>
> ---
>  configure             | 27 +++++++++++++++++++++++++++
>  block/Makefile.objs   |  2 ++
>  scripts/checkpatch.pl |  1 +
>  3 files changed, 30 insertions(+)
> 
> diff --git a/configure b/configure
> index 0c6e757..e988fd0 100755
> --- a/configure
> +++ b/configure
> @@ -422,6 +422,7 @@ tcmalloc="no"
>  jemalloc="no"
>  replication="yes"
>  vxhs=""
> +libxml2=""
>  
>  supported_cpu="no"
>  supported_os="no"
> @@ -1275,6 +1276,10 @@ for opt do
>    ;;
>    --enable-numa) numa="yes"
>    ;;
> +  --disable-libxml2) libxml2="no"
> +  ;;
> +  --enable-libxml2) libxml2="yes"
> +  ;;
>    --disable-tcmalloc) tcmalloc="no"
>    ;;
>    --enable-tcmalloc) tcmalloc="yes"
> @@ -1548,6 +1553,7 @@ disabled with --disable-FEATURE, default is enabled if available:
>    tpm             TPM support
>    libssh2         ssh block device support
>    numa            libnuma support
> +  libxml2         for Parallels image format
>    tcmalloc        tcmalloc support
>    jemalloc        jemalloc support
>    replication     replication support
> @@ -1592,6 +1598,20 @@ if test "$ARCH" = "unknown"; then
>      fi
>  fi
>  
> +# check for libxml2
> +if test "$libxml2" != "no" ; then
> +    if $pkg_config --exists libxml-2.0; then
> +        libxml2="yes"
> +        libxml2_cflags=$($pkg_config --cflags libxml-2.0)
> +        libxml2_libs=$($pkg_config --libs libxml-2.0)
> +    else
> +        if test "$libxml2" = "yes"; then
> +            feature_not_found "libxml2" "Install libxml2 devel"
> +        fi
> +        libxml2="no"
> +    fi
> +fi
> +
>  # Consult white-list to determine whether to enable werror
>  # by default.  Only enable by default for git builds
>  if test -z "$werror" ; then
> @@ -5549,6 +5569,7 @@ echo "lzo support       $lzo"
>  echo "snappy support    $snappy"
>  echo "bzip2 support     $bzip2"
>  echo "NUMA host support $numa"
> +echo "libxml2           $libxml2"
>  echo "tcmalloc support  $tcmalloc"
>  echo "jemalloc support  $jemalloc"
>  echo "avx2 optimization $avx2_opt"
> @@ -6208,6 +6229,12 @@ if test "$have_rtnetlink" = "yes" ; then
>    echo "CONFIG_RTNETLINK=y" >> $config_host_mak
>  fi
>  
> +if test "$libxml2" = "yes" ; then
> +  echo "CONFIG_LIBXML2=y" >> $config_host_mak
> +  echo "LIBXML2_CFLAGS=$libxml2_cflags" >> $config_host_mak
> +  echo "LIBXML2_LIBS=$libxml2_libs" >> $config_host_mak
> +fi
> +
>  if test "$replication" = "yes" ; then
>    echo "CONFIG_REPLICATION=y" >> $config_host_mak
>  fi
> diff --git a/block/Makefile.objs b/block/Makefile.objs
> index 6eaf78a..a73387f 100644
> --- a/block/Makefile.objs
> +++ b/block/Makefile.objs
> @@ -47,3 +47,5 @@ block-obj-$(if $(CONFIG_BZIP2),m,n) += dmg-bz2.o
>  dmg-bz2.o-libs     := $(BZIP2_LIBS)
>  qcow.o-libs        := -lz
>  linux-aio.o-libs   := -laio
> +parallels.o-cflags := $(LIBXML2_CFLAGS)
> +parallels.o-libs   := $(LIBXML2_LIBS)
> diff --git a/scripts/checkpatch.pl b/scripts/checkpatch.pl
> index 34df753..e76cc85 100755
> --- a/scripts/checkpatch.pl
> +++ b/scripts/checkpatch.pl
> @@ -265,6 +265,7 @@ our @typeList = (
>  	qr{${Ident}_handler_fn},
>  	qr{target_(?:u)?long},
>  	qr{hwaddr},
> +	qr{xml${Ident}},
>  );
>  
>  # This can be modified by sub possible.  Since it can be empty, be careful
> -- 
> 2.7.4
> 
> 

Re: [Qemu-devel] [PATCH 1/5] docs/interop/prl-xml: description of Parallels Disk format

[Stefan Hajnoczi]

[-- Attachment #1: Type: text/plain, Size: 10565 bytes --]

On Mon, Dec 18, 2017 at 02:09:07PM +0300, Denis V. Lunev wrote:
> From: Klim Kireev <klim.kireev@virtuozzo.com>
> 
> This patch adds main information about Parallels Disk
> format, which consists of DiskDescriptor.xml and other files.
> 
> Signed-off-by: Edgar Kaziakhmedov <edgar.kaziakhmedov@virtuozzo.com>
> Signed-off-by: Klim Kireev <klim.kireev@virtuozzo.com>
> Signed-off-by: Vladimir Sementsov-Ogievskiy <vsementsov@virtuozzo.com>
> Signed-off-by: Denis V. Lunev <den@openvz.org>
> CC: Stefan Hajnoczi <stefanha@redhat.com>
> ---
>  docs/interop/prl-xml.txt | 155 +++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 155 insertions(+)
>  create mode 100644 docs/interop/prl-xml.txt
> 
> diff --git a/docs/interop/prl-xml.txt b/docs/interop/prl-xml.txt
> new file mode 100644
> index 0000000..8ccb91a
> --- /dev/null
> +++ b/docs/interop/prl-xml.txt
> @@ -0,0 +1,155 @@
> += License =
> +
> +Copyright (c) 2015 Denis Lunev
> +Copyright (c) 2015 Vladimir Sementsov-Ogievskiy
> +Copyright (c) 2016-2017 Klim Kireev
> +Copyright (c) 2016-2017 Edgar Kaziakhmedov
> +
> +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 unspecified here fields and Snapshot.xml file

s/unspecified here fields/fields not covered in this document/

> +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 without parent, the root of snapshot tree.

s/without parent/with no parent/

> +
> +    Storage        a special conception of data, which consists of disk
> +                   parameters and a list of images. One of this image is root,
> +                   others are overlays. Images must be expandable (parallels
> +                   image file), however root image could be expandable or
> +                   plain. There may be more then one storage in the Parallels

s/then/than/

> +                   disk and it is defined as a split image.

I was having trouble understanding this paragraph.  At this point I can
begin to see that split images consist of multiple storages.  That makes
the concept of storage clearer.

Perhaps rephrase this paragraph as:

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.  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.

> +                   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 isn't supported

s/isn't/aren't/

> +                   in QEMU.
> +
> +  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 classical meaning.

To make this clearer the last line could be:

  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 single XML section Parallels_disk_image.
> +The section has only one attribute "Version", that must be 1.0.
> +General structure of DiskDescriptor.xml:
> +
> +<Parallels_disk_image Version="1.0">
> +    <Disk_Parameters>
> +        ...
> +    </Disk_Parameters>
> +    <StorageData>
> +        ...
> +    </StorageData>
> +    <Snapshots>
> +        ...
> +    </Snapshots>
> +</Parallels_disk_image>
> +
> +== Disk_Parameters section ==
> +The Disk_Parameters section describes the physical layout of the virtual disk
> +and some general settings.
> +
> +The Disk_Parameters section MUST contain the following subsections:
> +    * 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.
> +                  Attention: this field affects the read/write functionality.

What does "Attention: this field affects the read/write functionality" mean?

> +
> +== StorageData section ==
> +This section of the file describes root image and all snapshot images.

s/root image/the root image/

> +
> +The StorageData section consists of the Storage subsection, as shown below:
> +<StorageData>
> +    <Storage>
> +        ...
> +    </Storage>
> +</StorageData>
> +
> +A Storage descriptor consists of the following subsections:
> +    * Start     - start sector of the storage, equals to 0.
> +    * End       - number of sectors in storage, equals to Disk_size.

Just to be clear, if Start > 0 then End is still Disk_size and not Start
+ Disk_size?  Please tweak the wording to make this clear.

> +    * 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).

What is the purpose of this field if the Parallels Expandable Image
header also has the same value?

> +    * Several Image subsections.
> +
> +Each Image section consists of the following subsections:

I'm confused by the use of "section" and "subsections" here.  This spec
is ambiguous and does not describe the XML clearly.  Is a "section"
always an XML tag and a "subsection" is a child XML tag?

In other words, are we talking about:

  <Image>
      <GUID>{12345678-9abc-def1-2345-6789abcdef12}</GUID>
      <Type>Plain</Type>
      <File>my_file</File>
  </Image>

Or could it be:

  <Image GUID="{12345678-9abc-def1-2345-6789abcdef12}"
         Type="Plain"
	 File="my_file" />

?

Please use XML terminology ("tag", "attribute", etc) instead of
"section"/"subsection".

> +    * GUID - image identifier, UUID in curly brackets.
> +             For instance, {12345678-9abc-def1-2345-6789abcdef12}.

How is the GUID used?  Does it need to be validated against the GUID in
the image file?

> +    * Type - image type of the element. It can be:
> +             "Plain" for plain disks.

What is a plain disk?  Is this a raw file or a Parallels Expandable
Image file?

> +             "Compressed" for expanding disks.
> +    * File - path to image file. Path can be relative to DiskDecriptor.xml or
> +             absolute.
> +
> +== Snapshots section ==
> +The Snapshots section describes the snapshot relations with the snapshot tree.
> +
> +The section contains the set of Shot subsections, as shown below:
> +<Snapshots>
> +    <TopGUID> ... </TopGUID> //Optional subsection
> +    <Shot>
> +        ...
> +    </Shot>
> +    <Shot>
> +        ...
> +    </Shot>
> +    ...
> +</Snapshots>
> +
> +Each Shot section contains the following subsections:
> +    * 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 one root
> +snapshot. Top snapshot could be described via two ways: via TopGUID subsection
> +in the Snapshots section 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) sould be

s/sould/should/

> +opened read-only.
> +There is another predefined GIUD,

s/GIUD/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.

> +NOTE: To address top snapshot QEMU supports only predefined GUID mode.

This sounds like an implementation limitation and a spec violation
(since the spec says <TopGUID> may be used).  Please implement <TopGUID>
support unless it's really hard to do, or drop <TopGUID> from this spec
so that it's clear this feature doesn't need to be supported by QEMU and
other open source software.

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 455 bytes --]

Re: [Qemu-devel] [PATCH 3/5] block/parallels: move some structures into header

[Stefan Hajnoczi]

[-- Attachment #1: Type: text/plain, Size: 333 bytes --]

On Mon, Dec 18, 2017 at 02:09:09PM +0300, Denis V. Lunev wrote:
> +#ifndef BLOCK_PARALLELS_H
> +#define BLOCK_PARALLELS_H
> +#include "qemu/module.h"

Does anything in this file require module.h?

Also, the include for CoMutex is missing.  Please make sure this header
file includes necessary dependencies except for "qemu/osdep.h".

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 455 bytes --]

Re: [Qemu-devel] [PATCH 4/5] block/parallels: replace some magic numbers

[Stefan Hajnoczi]

[-- Attachment #1: Type: text/plain, Size: 518 bytes --]

On Mon, Dec 18, 2017 at 02:09:10PM +0300, Denis V. Lunev wrote:
> From: Klim Kireev <klim.kireev@virtuozzo.com>
> 
> Signed-off-by: Klim Kireev <klim.kireev@virtuozzo.com>
> Reviewed-by: Vladimir Sementsov-Ogievskiy <vsementsov@virtuozzo.com>
> Signed-off-by: Denis V. Lunev <den@openvz.org>
> CC: Stefan Hajnoczi <stefanha@redhat.com>
> ---
>  block/parallels.h | 2 ++
>  block/parallels.c | 5 +++--
>  2 files changed, 5 insertions(+), 2 deletions(-)

Reviewed-by: Stefan Hajnoczi <stefanha@redhat.com>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 455 bytes --]

Re: [Qemu-devel] [PATCH 5/5] block/parallels: add backing support to readv/writev

[Stefan Hajnoczi]

[-- Attachment #1: Type: text/plain, Size: 764 bytes --]

On Mon, Dec 18, 2017 at 02:09:11PM +0300, Denis V. Lunev wrote:
> From: Edgar Kaziakhmedov <edgar.kaziakhmedov@virtuozzo.com>
> 
> Since parallels format supports backing files, refine
> readv/writev (allocate_clusters) to redirect read/write requests
> to a backing file (if cluster is not available in the current bs).
> 
> Signed-off-by: Edgar Kaziakhmedov <edgar.kaziakhmedov@virtuozzo.com>
> Signed-off-by: Vladimir Sementsov-Ogievskiy <vsementsov@virtuozzo.com>
> Signed-off-by: Denis V. Lunev <den@openvz.org>
> CC: Stefan Hajnoczi <stefanha@redhat.com>
> ---
>  block/parallels.c | 50 ++++++++++++++++++++++++++++++++++++++++++++------
>  1 file changed, 44 insertions(+), 6 deletions(-)

Reviewed-by: Stefan Hajnoczi <stefanha@redhat.com>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 455 bytes --]

Re: [Qemu-devel] [Qemu-block] [PATCH 2/5] configure: add dependency

[klim]

On 12/22/2017 03:38 PM, Roman Kagan wrote:
> On Mon, Dec 18, 2017 at 02:09:08PM +0300, Denis V. Lunev wrote:
>> From: Klim Kireev <klim.kireev@virtuozzo.com>
>>
>> This dependency is required for adequate Parallels images support.
>> Typically the disk consists of several images which are glued by
>> XML disk descriptor. Also XML hides inside several important parameters
>> which are not available in the image header.
>>
>> The patch also adds clause to checkpatch.pl to understand libxml2 types.
> Can't you get by with glib's GMarkup, to avoid extra dependencies?
>
> https://developer.gnome.org/glib/stable/glib-Simple-XML-Subset-Parser.html
>
> Roman.
>
>> Signed-off-by: Denis V. Lunev <den@openvz.org>
>> Signed-off-by: Klim Kireev <klim.kireev@virtuozzo.com>
>> Signed-off-by: Edgar Kaziakhmedov <edgar.kaziakhmedov@virtuozzo.com>
>> CC: Stefan Hajnoczi <stefanha@redhat.com>
>> ---
>>   configure             | 27 +++++++++++++++++++++++++++
>>   block/Makefile.objs   |  2 ++
>>   scripts/checkpatch.pl |  1 +
>>   3 files changed, 30 insertions(+)
>>
>> diff --git a/configure b/configure
>> index 0c6e757..e988fd0 100755
>> --- a/configure
>> +++ b/configure
>> @@ -422,6 +422,7 @@ tcmalloc="no"
>>   jemalloc="no"
>>   replication="yes"
>>   vxhs=""
>> +libxml2=""
>>   
>>   supported_cpu="no"
>>   supported_os="no"
>> @@ -1275,6 +1276,10 @@ for opt do
>>     ;;
>>     --enable-numa) numa="yes"
>>     ;;
>> +  --disable-libxml2) libxml2="no"
>> +  ;;
>> +  --enable-libxml2) libxml2="yes"
>> +  ;;
>>     --disable-tcmalloc) tcmalloc="no"
>>     ;;
>>     --enable-tcmalloc) tcmalloc="yes"
>> @@ -1548,6 +1553,7 @@ disabled with --disable-FEATURE, default is enabled if available:
>>     tpm             TPM support
>>     libssh2         ssh block device support
>>     numa            libnuma support
>> +  libxml2         for Parallels image format
>>     tcmalloc        tcmalloc support
>>     jemalloc        jemalloc support
>>     replication     replication support
>> @@ -1592,6 +1598,20 @@ if test "$ARCH" = "unknown"; then
>>       fi
>>   fi
>>   
>> +# check for libxml2
>> +if test "$libxml2" != "no" ; then
>> +    if $pkg_config --exists libxml-2.0; then
>> +        libxml2="yes"
>> +        libxml2_cflags=$($pkg_config --cflags libxml-2.0)
>> +        libxml2_libs=$($pkg_config --libs libxml-2.0)
>> +    else
>> +        if test "$libxml2" = "yes"; then
>> +            feature_not_found "libxml2" "Install libxml2 devel"
>> +        fi
>> +        libxml2="no"
>> +    fi
>> +fi
>> +
>>   # Consult white-list to determine whether to enable werror
>>   # by default.  Only enable by default for git builds
>>   if test -z "$werror" ; then
>> @@ -5549,6 +5569,7 @@ echo "lzo support       $lzo"
>>   echo "snappy support    $snappy"
>>   echo "bzip2 support     $bzip2"
>>   echo "NUMA host support $numa"
>> +echo "libxml2           $libxml2"
>>   echo "tcmalloc support  $tcmalloc"
>>   echo "jemalloc support  $jemalloc"
>>   echo "avx2 optimization $avx2_opt"
>> @@ -6208,6 +6229,12 @@ if test "$have_rtnetlink" = "yes" ; then
>>     echo "CONFIG_RTNETLINK=y" >> $config_host_mak
>>   fi
>>   
>> +if test "$libxml2" = "yes" ; then
>> +  echo "CONFIG_LIBXML2=y" >> $config_host_mak
>> +  echo "LIBXML2_CFLAGS=$libxml2_cflags" >> $config_host_mak
>> +  echo "LIBXML2_LIBS=$libxml2_libs" >> $config_host_mak
>> +fi
>> +
>>   if test "$replication" = "yes" ; then
>>     echo "CONFIG_REPLICATION=y" >> $config_host_mak
>>   fi
>> diff --git a/block/Makefile.objs b/block/Makefile.objs
>> index 6eaf78a..a73387f 100644
>> --- a/block/Makefile.objs
>> +++ b/block/Makefile.objs
>> @@ -47,3 +47,5 @@ block-obj-$(if $(CONFIG_BZIP2),m,n) += dmg-bz2.o
>>   dmg-bz2.o-libs     := $(BZIP2_LIBS)
>>   qcow.o-libs        := -lz
>>   linux-aio.o-libs   := -laio
>> +parallels.o-cflags := $(LIBXML2_CFLAGS)
>> +parallels.o-libs   := $(LIBXML2_LIBS)
>> diff --git a/scripts/checkpatch.pl b/scripts/checkpatch.pl
>> index 34df753..e76cc85 100755
>> --- a/scripts/checkpatch.pl
>> +++ b/scripts/checkpatch.pl
>> @@ -265,6 +265,7 @@ our @typeList = (
>>   	qr{${Ident}_handler_fn},
>>   	qr{target_(?:u)?long},
>>   	qr{hwaddr},
>> +	qr{xml${Ident}},
>>   );
>>   
>>   # This can be modified by sub possible.  Since it can be empty, be careful
>> -- 
>> 2.7.4
>>
>>
It is inconvenient, because GMarkup sees XML files as series of event, 
while for our purposes the tree model is much more preferable.

Also libvirt depends on libxml2, so it is installed in most cases.

Re: [Qemu-devel] [Qemu-block] [PATCH 2/5] configure: add dependency

[Daniel P. Berrange]

On Fri, Dec 22, 2017 at 03:38:02PM +0300, Roman Kagan wrote:
> On Mon, Dec 18, 2017 at 02:09:08PM +0300, Denis V. Lunev wrote:
> > From: Klim Kireev <klim.kireev@virtuozzo.com>
> > 
> > This dependency is required for adequate Parallels images support.
> > Typically the disk consists of several images which are glued by
> > XML disk descriptor. Also XML hides inside several important parameters
> > which are not available in the image header.
> > 
> > The patch also adds clause to checkpatch.pl to understand libxml2 types.
> 
> Can't you get by with glib's GMarkup, to avoid extra dependencies?
> 
> https://developer.gnome.org/glib/stable/glib-Simple-XML-Subset-Parser.html

I don't think the extra dep is a real problem, given that a full QEMU
build already links to 150+ libraries and libxml is widely available
across platforms and certainly everywhere on Linux. If you  build QEMU
with modular block drivers, then the libxml dep only gets added to the
parallels block driver so file and thus only loaded when needed.

Regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|

Re: [Qemu-devel] [PATCH 1/5] docs/interop/prl-xml: description of Parallels Disk format

[klim]

On 01/04/2018 02:34 PM, Stefan Hajnoczi wrote:
> On Mon, Dec 18, 2017 at 02:09:07PM +0300, Denis V. Lunev wrote:
>> From: Klim Kireev <klim.kireev@virtuozzo.com>
>>
>> This patch adds main information about Parallels Disk
>> format, which consists of DiskDescriptor.xml and other files.
>>
>> Signed-off-by: Edgar Kaziakhmedov <edgar.kaziakhmedov@virtuozzo.com>
>> Signed-off-by: Klim Kireev <klim.kireev@virtuozzo.com>
>> Signed-off-by: Vladimir Sementsov-Ogievskiy <vsementsov@virtuozzo.com>
>> Signed-off-by: Denis V. Lunev <den@openvz.org>
>> CC: Stefan Hajnoczi <stefanha@redhat.com>
>> ---
>>   docs/interop/prl-xml.txt | 155 +++++++++++++++++++++++++++++++++++++++++++++++
>>   1 file changed, 155 insertions(+)
>>   create mode 100644 docs/interop/prl-xml.txt
>>
>> diff --git a/docs/interop/prl-xml.txt b/docs/interop/prl-xml.txt
>> new file mode 100644
>> index 0000000..8ccb91a
>> --- /dev/null
>> +++ b/docs/interop/prl-xml.txt
>> @@ -0,0 +1,155 @@
>> += License =
>> +
>> +Copyright (c) 2015 Denis Lunev
>> +Copyright (c) 2015 Vladimir Sementsov-Ogievskiy
>> +Copyright (c) 2016-2017 Klim Kireev
>> +Copyright (c) 2016-2017 Edgar Kaziakhmedov
>> +
>> +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 unspecified here fields and Snapshot.xml file
> s/unspecified here fields/fields not covered in this document/
>
>> +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 without parent, the root of snapshot tree.
> s/without parent/with no parent/
>
>> +
>> +    Storage        a special conception of data, which consists of disk
>> +                   parameters and a list of images. One of this image is root,
>> +                   others are overlays. Images must be expandable (parallels
>> +                   image file), however root image could be expandable or
>> +                   plain. There may be more then one storage in the Parallels
> s/then/than/
>
>> +                   disk and it is defined as a split image.
> I was having trouble understanding this paragraph.  At this point I can
> begin to see that split images consist of multiple storages.  That makes
> the concept of storage clearer.
>
> Perhaps rephrase this paragraph as:
>
> 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.  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.
>
>> +                   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 isn't supported
> s/isn't/aren't/
>
>> +                   in QEMU.
>> +
>> +  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 classical meaning.
> To make this clearer the last line could be:
>
>    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 single XML section Parallels_disk_image.
>> +The section has only one attribute "Version", that must be 1.0.
>> +General structure of DiskDescriptor.xml:
>> +
>> +<Parallels_disk_image Version="1.0">
>> +    <Disk_Parameters>
>> +        ...
>> +    </Disk_Parameters>
>> +    <StorageData>
>> +        ...
>> +    </StorageData>
>> +    <Snapshots>
>> +        ...
>> +    </Snapshots>
>> +</Parallels_disk_image>
>> +
>> +== Disk_Parameters section ==
>> +The Disk_Parameters section describes the physical layout of the virtual disk
>> +and some general settings.
>> +
>> +The Disk_Parameters section MUST contain the following subsections:
>> +    * 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.
>> +                  Attention: this field affects the read/write functionality.
> What does "Attention: this field affects the read/write functionality" mean?
>
>> +
>> +== StorageData section ==
>> +This section of the file describes root image and all snapshot images.
> s/root image/the root image/
>
>> +
>> +The StorageData section consists of the Storage subsection, as shown below:
>> +<StorageData>
>> +    <Storage>
>> +        ...
>> +    </Storage>
>> +</StorageData>
>> +
>> +A Storage descriptor consists of the following subsections:
>> +    * Start     - start sector of the storage, equals to 0.
>> +    * End       - number of sectors in storage, equals to Disk_size.
> Just to be clear, if Start > 0 then End is still Disk_size and not Start
> + Disk_size?  Please tweak the wording to make this clear.
>
>> +    * 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).
> What is the purpose of this field if the Parallels Expandable Image
> header also has the same value?
I suppose that it is needed for creating snapshots over an raw root image.
>> +    * Several Image subsections.
>> +
>> +Each Image section consists of the following subsections:
> I'm confused by the use of "section" and "subsections" here.  This spec
> is ambiguous and does not describe the XML clearly.  Is a "section"
> always an XML tag and a "subsection" is a child XML tag?
>
> In other words, are we talking about:
>
>    <Image>
>        <GUID>{12345678-9abc-def1-2345-6789abcdef12}</GUID>
>        <Type>Plain</Type>
>        <File>my_file</File>
>    </Image>
>
> Or could it be:
>
>    <Image GUID="{12345678-9abc-def1-2345-6789abcdef12}"
>           Type="Plain"
> 	 File="my_file" />
>
> ?
>
> Please use XML terminology ("tag", "attribute", etc) instead of
> "section"/"subsection".
>
>> +    * GUID - image identifier, UUID in curly brackets.
>> +             For instance, {12345678-9abc-def1-2345-6789abcdef12}.
> How is the GUID used?  Does it need to be validated against the GUID in
> the image file?
Parallels images don't contain GUID, what do you mean?
>
>> +    * Type - image type of the element. It can be:
>> +             "Plain" for plain disks.
> What is a plain disk?  Is this a raw file or a Parallels Expandable
> Image file?
>
>> +             "Compressed" for expanding disks.
>> +    * File - path to image file. Path can be relative to DiskDecriptor.xml or
>> +             absolute.
>> +
>> +== Snapshots section ==
>> +The Snapshots section describes the snapshot relations with the snapshot tree.
>> +
>> +The section contains the set of Shot subsections, as shown below:
>> +<Snapshots>
>> +    <TopGUID> ... </TopGUID> //Optional subsection
>> +    <Shot>
>> +        ...
>> +    </Shot>
>> +    <Shot>
>> +        ...
>> +    </Shot>
>> +    ...
>> +</Snapshots>
>> +
>> +Each Shot section contains the following subsections:
>> +    * 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 one root
>> +snapshot. Top snapshot could be described via two ways: via TopGUID subsection
>> +in the Snapshots section 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) sould be
> s/sould/should/
>
>> +opened read-only.
>> +There is another predefined GIUD,
> s/GIUD/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.
>> +NOTE: To address top snapshot QEMU supports only predefined GUID mode.
> This sounds like an implementation limitation and a spec violation
> (since the spec says <TopGUID> may be used).  Please implement <TopGUID>
> support unless it's really hard to do, or drop <TopGUID> from this spec
> so that it's clear this feature doesn't need to be supported by QEMU and
> other open source software.

Re: [Qemu-devel] [PATCH 1/5] docs/interop/prl-xml: description of Parallels Disk format

[Stefan Hajnoczi]

[-- Attachment #1: Type: text/plain, Size: 810 bytes --]

On Wed, Jan 10, 2018 at 07:23:29PM +0300, klim wrote:
> On 01/04/2018 02:34 PM, Stefan Hajnoczi wrote:
> > On Mon, Dec 18, 2017 at 02:09:07PM +0300, Denis V. Lunev wrote:
> > > +    * GUID - image identifier, UUID in curly brackets.
> > > +             For instance, {12345678-9abc-def1-2345-6789abcdef12}.
> > How is the GUID used?  Does it need to be validated against the GUID in
> > the image file?
> Parallels images don't contain GUID, what do you mean?

At this point in the spec nothing has used the GUID yet, so I was
wondering what purpose it serves.  After reading the Snapshots section
below I saw that the GUID is used there.

It would be nice to include something like "The GUID is used by the
Snapshots section to reference images (see below)" so that the reader
knows why this field is needed.

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 455 bytes --]

Re: [Qemu-devel] [PATCH 1/5] docs/interop/prl-xml: description of Parallels Disk format

[Eric Blake]

[-- Attachment #1: Type: text/plain, Size: 1249 bytes --]

On 01/22/2018 02:32 PM, Eric Blake wrote:
> On 01/12/2018 03:01 AM, Klim Kireev wrote:
>> This patch adds main information about Parallels Disk
>> format, which consists of DiskDescriptor.xml and other files.
>>
>> Signed-off-by: Edgar Kaziakhmedov <edgar.kaziakhmedov@virtuozzo.com>
>> Signed-off-by: Klim Kireev <klim.kireev@virtuozzo.com>
>> Signed-off-by: Vladimir Sementsov-Ogievskiy <vsementsov@virtuozzo.com>
>> Signed-off-by: Denis V. Lunev <den@openvz.org>
>> CC: Stefan Hajnoczi <stefanha@redhat.com>
>> ---
>>  docs/interop/prl-xml.txt | 158 +++++++++++++++++++++++++++++++++++++++++++++++
>>  1 file changed, 158 insertions(+)
>>  create mode 100644 docs/interop/prl-xml.txt
>>
>> diff --git a/docs/interop/prl-xml.txt b/docs/interop/prl-xml.txt
>> new file mode 100644
>> index 0000000000..7031f8752c
>> --- /dev/null
>> +++ b/docs/interop/prl-xml.txt
>> @@ -0,0 +1,158 @@
>> += License =
>> +
>> +Copyright (c) 2015-2017, Virtuozzo, Inc.
> 
> Want to claim 2018 as well?

Oh, and I see that the pull request has already been sent, so these
cleanups can be a followup patch.

-- 
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3266
Virtualization:  qemu.org | libvirt.org


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 619 bytes --]

Re: [Qemu-devel] [PATCH 1/5] docs/interop/prl-xml: description of Parallels Disk format

[Eric Blake]

[-- Attachment #1: Type: text/plain, Size: 2648 bytes --]

On 01/12/2018 03:01 AM, Klim Kireev wrote:
> This patch adds main information about Parallels Disk
> format, which consists of DiskDescriptor.xml and other files.
> 
> Signed-off-by: Edgar Kaziakhmedov <edgar.kaziakhmedov@virtuozzo.com>
> Signed-off-by: Klim Kireev <klim.kireev@virtuozzo.com>
> Signed-off-by: Vladimir Sementsov-Ogievskiy <vsementsov@virtuozzo.com>
> Signed-off-by: Denis V. Lunev <den@openvz.org>
> CC: Stefan Hajnoczi <stefanha@redhat.com>
> ---
>  docs/interop/prl-xml.txt | 158 +++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 158 insertions(+)
>  create mode 100644 docs/interop/prl-xml.txt
> 
> diff --git a/docs/interop/prl-xml.txt b/docs/interop/prl-xml.txt
> new file mode 100644
> index 0000000000..7031f8752c
> --- /dev/null
> +++ b/docs/interop/prl-xml.txt
> @@ -0,0 +1,158 @@
> += License =
> +
> +Copyright (c) 2015-2017, Virtuozzo, Inc.

Want to claim 2018 as well?


> +
> +This specification contains minimal information about Parallels Disk Format,
> +which is enough to proper work with QEMU. Nevertheless, Parallels Cloud Server

s/proper/properly/

> +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

s/allows to store/allows storing/

> +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

s/Parallels/A Parallels/

> +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.

s/has UUID/has a UUID/

> +== 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.

In sectors and not bytes?  Is it possible to have an image that is not
sector-aligned?

-- 
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3266
Virtualization:  qemu.org | libvirt.org


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 619 bytes --]

[Qemu-devel] [PATCH 1/5] docs/interop/prl-xml: description of Parallels Disk format

[Klim Kireev]

This patch adds main information about Parallels Disk
format, which consists of DiskDescriptor.xml and other files.

Signed-off-by: Edgar Kaziakhmedov <edgar.kaziakhmedov@virtuozzo.com>
Signed-off-by: Klim Kireev <klim.kireev@virtuozzo.com>
Signed-off-by: Vladimir Sementsov-Ogievskiy <vsementsov@virtuozzo.com>
Signed-off-by: Denis V. Lunev <den@openvz.org>
CC: Stefan Hajnoczi <stefanha@redhat.com>
---
 docs/interop/prl-xml.txt | 158 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 158 insertions(+)
 create mode 100644 docs/interop/prl-xml.txt

diff --git a/docs/interop/prl-xml.txt b/docs/interop/prl-xml.txt
new file mode 100644
index 0000000000..7031f8752c
--- /dev/null
+++ b/docs/interop/prl-xml.txt
@@ -0,0 +1,158 @@
+= 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 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.
-- 
2.14.3

[Qemu-devel] [PATCH 1/5] docs/interop/prl-xml: description of Parallels Disk format

[Klim Kireev]

This patch adds main information about Parallels Disk
format, which consists of DiskDescriptor.xml and other files.

Signed-off-by: Edgar Kaziakhmedov <edgar.kaziakhmedov@virtuozzo.com>
Signed-off-by: Klim Kireev <klim.kireev@virtuozzo.com>
Signed-off-by: Vladimir Sementsov-Ogievskiy <vsementsov@virtuozzo.com>
Signed-off-by: Denis V. Lunev <den@openvz.org>
CC: Stefan Hajnoczi <stefanha@redhat.com>
---
 docs/interop/prl-xml.txt | 156 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 156 insertions(+)
 create mode 100644 docs/interop/prl-xml.txt

diff --git a/docs/interop/prl-xml.txt b/docs/interop/prl-xml.txt
new file mode 100644
index 0000000000..57bffc67ae
--- /dev/null
+++ b/docs/interop/prl-xml.txt
@@ -0,0 +1,156 @@
+= License =
+
+Copyright (c) 2015-2017, Virtuozzo, Inc.
+Authors:
+        2015 Denis Lunev
+        2015 Vladimir Sementsov-Ogievskiy
+        2016-2017 Klim Kireev
+        2016-2017 Edgar Kaziakhmedov
+
+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}.
+    * 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.
-- 
2.14.3