From patchwork Mon Dec 18 11:09:07 2017 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: "Denis V. Lunev" X-Patchwork-Id: 10118781 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork.web.codeaurora.org (Postfix) with ESMTP id B0639603FA for ; Mon, 18 Dec 2017 11:15:31 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id A26AF288F1 for ; Mon, 18 Dec 2017 11:15:31 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 9692628970; Mon, 18 Dec 2017 11:15:31 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-6.9 required=2.0 tests=BAYES_00,RCVD_IN_DNSWL_HI autolearn=ham version=3.3.1 Received: from lists.gnu.org (lists.gnu.org [208.118.235.17]) (using TLSv1 with cipher AES256-SHA (256/256 bits)) (No client certificate requested) by mail.wl.linuxfoundation.org (Postfix) with ESMTPS id C2773288F1 for ; Mon, 18 Dec 2017 11:15:30 +0000 (UTC) Received: from localhost ([::1]:57958 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1eQtOM-0007fn-2K for patchwork-qemu-devel@patchwork.kernel.org; Mon, 18 Dec 2017 06:15:30 -0500 Received: from eggs.gnu.org ([2001:4830:134:3::10]:57305) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1eQtIV-0003Bm-0z for qemu-devel@nongnu.org; Mon, 18 Dec 2017 06:09:31 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1eQtIO-0007Zx-IV for qemu-devel@nongnu.org; Mon, 18 Dec 2017 06:09:26 -0500 Received: from mailhub.sw.ru ([195.214.232.25]:7306 helo=relay.sw.ru) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1eQtIO-0007Z5-1z for qemu-devel@nongnu.org; Mon, 18 Dec 2017 06:09:20 -0500 Received: from iris.sw.ru (msk-vpn.virtuozzo.com [195.214.232.6]) by relay.sw.ru (8.13.4/8.13.4) with ESMTP id vBHC7I6u013555; Sun, 17 Dec 2017 15:07:18 +0300 (MSK) From: "Denis V. Lunev" To: qemu-block@nongnu.org, qemu-devel@nongnu.org Date: Mon, 18 Dec 2017 14:09:07 +0300 Message-Id: <1513595351-5899-2-git-send-email-den@openvz.org> X-Mailer: git-send-email 2.7.4 In-Reply-To: <1513595351-5899-1-git-send-email-den@openvz.org> References: <1513595351-5899-1-git-send-email-den@openvz.org> X-detected-operating-system: by eggs.gnu.org: OpenBSD 3.x [fuzzy] X-Received-From: 195.214.232.25 Subject: [Qemu-devel] [PATCH 1/5] docs/interop/prl-xml: description of Parallels Disk format X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Klim Kireev , Vladimir Sementsov-Ogievskiy , Edgar Kaziakhmedov , Stefan Hajnoczi , "Denis V . Lunev" Errors-To: qemu-devel-bounces+patchwork-qemu-devel=patchwork.kernel.org@nongnu.org Sender: "Qemu-devel" X-Virus-Scanned: ClamAV using ClamSMTP From: Klim Kireev This patch adds main information about Parallels Disk format, which consists of DiskDescriptor.xml and other files. Signed-off-by: Edgar Kaziakhmedov Signed-off-by: Klim Kireev Signed-off-by: Vladimir Sementsov-Ogievskiy Signed-off-by: Denis V. Lunev CC: Stefan Hajnoczi --- 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: + + + + ... + + + ... + + + ... + + + +== 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: + + + ... + + + +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: + + ... //Optional subsection + + ... + + + ... + + ... + + +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 +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.