[Qemu-devel] [PATCH 1/1] parallels: add format spec

[Qemu-devel] [PATCH 1/1] parallels: add format spec

[Denis V. Lunev]

From: Vladimir Sementsov-Ogievskiy <vsementsov@virtuozzo.com>

This specifies Parallels image format as implemented in Parallels Cloud
Server 6.10

Signed-off-by: Vladimir Sementsov-Ogievskiy <vsementsov@virtuozzo.com>
Signed-off-by: Denis V. Lunev <den@openvz.org>
CC: John Snow <jsnow@redhat.com>
CC: Stefan Hajnoczi <stefanha@redhat.com>
---
 MAINTAINERS              |   1 +
 docs/specs/parallels.txt | 218 +++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 219 insertions(+)
 create mode 100644 docs/specs/parallels.txt

diff --git a/MAINTAINERS b/MAINTAINERS
index 9e1fa72..23441e1 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -1471,6 +1471,7 @@ M: Denis V. Lunev <den@openvz.org>
 L: qemu-block@nongnu.org
 S: Supported
 F: block/parallels.c
+F: docs/specs/parallels.txt
 
 qed
 M: Stefan Hajnoczi <stefanha@redhat.com>
diff --git a/docs/specs/parallels.txt b/docs/specs/parallels.txt
new file mode 100644
index 0000000..56c716a
--- /dev/null
+++ b/docs/specs/parallels.txt
@@ -0,0 +1,218 @@
+= Parallels Expandable Image File Format =
+
+A Parallels expandable image file consists of three consecutive parts:
+    * header
+    * BAT
+    * data area
+
+All numbers in a Parallels expandable image are stored in little-endian byte
+order.
+
+
+== Definitions ==
+
+    Sector    A 512-byte data chunk.
+
+    Cluster   A data chunk of the size specified in the image header.
+              Currently, the default size is 1MiB (2048 sectors). In previous
+              versions, cluster sizes of 63 sectors, 256 and 252 kilobytes were
+              used.
+
+    BAT       Block Allocation Table, an entity that contains information for
+              guest-to-host I/O data address translation.
+
+
+== Header ==
+
+The header is placed at the start of an image and contains the following
+fields:
+
+    char      magic[16]
+              Must contain "WithoutFreeSpace" or "WithouFreSpacExt".
+
+    uint32    version
+              Must be 2.
+
+    uint32    heads
+              Disk geometry parameter for guest.
+
+    uint32    cylinders
+              Disk geometry parameter for guest.
+
+    uint32    tracks
+              Cluster size, in sectors.
+
+    uint32    nb_bat_entries
+              Disk size, in clusters (BAT size).
+
+    uint64    nb_sectors
+              Disk size, in sectors.
+
+              For "WithoutFreeSpace" images:
+              Only the lowest 4 bytes are used. The highest 4 bytes must be
+              cleared in this case.
+
+              For "WithouFreSpacExt" images, there are no such
+              restrictions.
+
+    uint32    in_use
+              Set to 0x746F6E59 when the image is opened by software in R/W
+              mode; set to 0x312e3276 when the image is closed.
+
+              A zero in this field means that the image was opened by an old
+              version of the software that doesn't support Format Extension
+              (see below).
+
+              Other values are not allowed.
+
+    uint32    data_off
+              An offset, in sectors, from the start of the file to the start of
+              the data area.
+
+              For "WithoutFreeSpace" images:
+              - If data_off is zero, the offset is calculated as the end of BAT
+                table plus some padding to ensure sector size alignment.
+              - If data_off is non-zero, the offset should be aligned to sector
+                size. However it is recommended to align it to cluster size for
+                newly created images.
+
+              For "WithouFreSpacExt" images:
+              data_off must be non-zero and aligned to cluster size.
+
+    uint32    flags
+              Miscellaneous flags.
+
+              Bit 0: Empty Image bit. If set, the image should be
+                     considered clear.
+
+              Bits 2-31: Unused.
+
+    uint64    ext_off
+              Format Extension offset, an offset, in sectors, from the start of
+              the file to the start of the Format Extension Cluster.
+
+              ext_off must meet the same requirements as cluster offsets
+              defined by BAT entries (see below).
+
+
+== BAT ==
+
+BAT is placed immediately after the image header. In the file, BAT is a
+contiguous array of 32-bit unsigned little-endian integers with
+(bat_entries * 4) bytes size.
+
+Each BAT entry contains an offset from the start of the file to the
+corresponding cluster. The offset set in clusters for "WithouFreSpacExt" images
+and in sectors for "WithoutFreeSpace" images.
+
+If a BAT entry is zero, the corresponding cluster is not allocated and should
+be considered as filled with zeroes.
+
+Cluster offsets specified by BAT entries must meet the following requirements:
+    - the value must not be lower than data offset (provided by header.data_off
+      or calculated as specified above),
+    - the value must be lower than the desired file size,
+    - the value must be unique among all BAT entries,
+    - the result of (cluster offset - data offset) must be aligned to cluster
+      size.
+
+
+== Data Area ==
+
+The data area is an area from the data offset (provided by header.data_off or
+calculated as specified above) to the end of the file. It represents a
+contiguous array of clusters. Most of them are allocated by the BAT, some may
+be allocated by the ext_off field in the header while other may be allocated by
+extensions. All clusters allocated by ext_off and extensions should meet the
+same requirements as clusters specified by BAT entries.
+
+
+== Format Extension ==
+
+The Format Extension is an area 1 cluster in size that provides additional
+format features. This cluster is addressed by the ext_off field in the header.
+The format of the Format Extension area is the following:
+
+    uint64    magic
+              Must be 0xAB234CEF23DCEA87
+
+    uint8     m_CheckSum[16]
+              The MD5 checksum of the entire Header Extension cluster except
+              the first 24 bytes.
+
+    The above are followed by feature sections or "extensions". The last
+    extension must be "End of features" (see below).
+
+Each feature section has the following format:
+
+    uint64    magic
+              The identifier of the feature:
+              0x0000000000000000 - End of features
+              0x20385FAE252CB34A - Dirty bitmap
+
+    uint64    flags
+              External flags for extension:
+
+              Bit 0: NECESSARY
+                     If the software cannot load the extension (due to an
+                     unknown magic number or error), the file should not be
+                     changed. If this flag is unset and there is an error on
+                     loading the extension, said extension should be dropped.
+
+              Bit 1: TRANSIT
+                     If there is an unknown extension with this flag set,
+                     said extension should be left as is.
+
+              If neither NECESSARY nor TRANSIT are set, the extension should be
+              dropped.
+
+    uint32    data_size
+              The size of the following feature data, in bytes.
+
+    uint32    unused32
+              Align header to 8 bytes boundary.
+
+    uint8     data[data_size]
+
+    The above is followed by padding to the next 8 bytes boundary, then the
+    next extension starts.
+
+    The last extension must be "End of features" with all the fields set to 0.
+
+
+=== Dirty bitmaps feature ===
+
+This feature provides a way of storing dirty bitmaps in the image. The fields
+of its data area are:
+
+    uint64    size
+              The bitmap size, should be equal to disk size in sectors.
+
+    uint8     id[16]
+              An identifier for backup consistency checking.
+
+    uint32    granularity
+              Bitmap granularity, in sectors. I.e., the number of sectors
+              corresponding to one bit of the bitmap.
+
+    uint32    l1_size
+              The number of entries in the L1 table of the bitmap.
+
+    uint64    l1[l1_size]
+              L1 offset table (in bytes)
+
+A dirty bitmap is stored using a one-level structure for the mapping to host
+clusters - an L1 table.
+
+Given an offset into the bitmap, the offset in bytes into the image file can be
+obtained as follows:
+
+    offset = l1_table[offset / cluster_size] + (offset % cluster_size)
+
+If an L1 table entry is 0, the corresponding cluster of the bitmap is assumed
+to be zero.
+
+If an L1 table entry is 1, the corresponding cluster of the bitmap is assumed
+to have all bits set.
+
+If an L1 table entry is not 0 or 1, it allocates a cluster from the data area.
-- 
2.1.4

Re: [Qemu-devel] [PATCH 1/1] parallels: add format spec

[Eric Blake]

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

On 11/16/2015 04:52 AM, Denis V. Lunev wrote:
> From: Vladimir Sementsov-Ogievskiy <vsementsov@virtuozzo.com>
> 
> This specifies Parallels image format as implemented in Parallels Cloud
> Server 6.10

Are we the canonical location of the specification?  If not, do we risk
getting out of sync with the canonical Parallels Cloud Server
documentation, in which case, wouldn't it be better to point to a URL of
the externally-maintained spec rather than duplicating it here?

> +++ b/docs/specs/parallels.txt
> @@ -0,0 +1,218 @@
> += Parallels Expandable Image File Format =
> +

Is this document okay under the default GPLv2+ license, or does it need
to explicitly call out a different license?


> +== Header ==
> +
> +The header is placed at the start of an image and contains the following
> +fields:
> +
> +    char      magic[16]
> +              Must contain "WithoutFreeSpace" or "WithouFreSpacExt".
> +
> +    uint32    version
> +              Must be 2.
> +

You may want to compare to the qcow2 spec, which also lists expected
byte offsets for each field (rather than having to count how many
earlier fields of which widths were specified).

-- 
Eric Blake   eblake redhat com    +1-919-301-3266
Libvirt virtualization library http://libvirt.org


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

Re: [Qemu-devel] [PATCH 1/1] parallels: add format spec

[Denis V. Lunev]

On 11/17/2015 06:54 PM, Eric Blake wrote:
> On 11/16/2015 04:52 AM, Denis V. Lunev wrote:
>> From: Vladimir Sementsov-Ogievskiy <vsementsov@virtuozzo.com>
>>
>> This specifies Parallels image format as implemented in Parallels Cloud
>> Server 6.10
> Are we the canonical location of the specification?  If not, do we risk
> getting out of sync with the canonical Parallels Cloud Server
> documentation, in which case, wouldn't it be better to point to a URL of
> the externally-maintained spec rather than duplicating it here?
the problem is that this documentation is not published in the
other place and for me keeping it here is a shorter way than
getting the page on the official virtuozzo.com
Thus I would like to get this place a canonical location of it.

At the moment I can make a promise to keep it actual. There
are no new features in the visible scope planned for PCS and
they can not appear in Parallels Server without me.

There is another purpose though. This spec gives a base for
Vladimir to implement named dirty bitmap support for
Parallels images in QEMU as they are implemented in PCS.
This is the main goal of this submission.


>> +++ b/docs/specs/parallels.txt
>> @@ -0,0 +1,218 @@
>> += Parallels Expandable Image File Format =
>> +
> Is this document okay under the default GPLv2+ license, or does it need
> to explicitly call out a different license?

GPLv2 is OK for us. We can state this explicitly in
the header if this is necessary.

>
>> +== Header ==
>> +
>> +The header is placed at the start of an image and contains the following
>> +fields:
>> +
>> +    char      magic[16]
>> +              Must contain "WithoutFreeSpace" or "WithouFreSpacExt".
>> +
>> +    uint32    version
>> +              Must be 2.
>> +
> You may want to compare to the qcow2 spec, which also lists expected
> byte offsets for each field (rather than having to count how many
> earlier fields of which widths were specified).
>
this would be nice to implement unit tests. We will add this
for sure! Thank you for an idea.

Den

Re: [Qemu-devel] [PATCH 1/1] parallels: add format spec

[Vladimir Sementsov-Ogievskiy]

On 17.11.2015 18:54, Eric Blake wrote:
> On 11/16/2015 04:52 AM, Denis V. Lunev wrote:
>> From: Vladimir Sementsov-Ogievskiy <vsementsov@virtuozzo.com>
>>
>> This specifies Parallels image format as implemented in Parallels Cloud
>> Server 6.10
> Are we the canonical location of the specification?  If not, do we risk
> getting out of sync with the canonical Parallels Cloud Server
> documentation, in which case, wouldn't it be better to point to a URL of
> the externally-maintained spec rather than duplicating it here?
>
>> +++ b/docs/specs/parallels.txt
>> @@ -0,0 +1,218 @@
>> += Parallels Expandable Image File Format =
>> +
> Is this document okay under the default GPLv2+ license, or does it need
> to explicitly call out a different license?
>
>
>> +== Header ==
>> +
>> +The header is placed at the start of an image and contains the following
>> +fields:
>> +
>> +    char      magic[16]
>> +              Must contain "WithoutFreeSpace" or "WithouFreSpacExt".
>> +
>> +    uint32    version
>> +              Must be 2.
>> +
> You may want to compare to the qcow2 spec, which also lists expected
> byte offsets for each field (rather than having to count how many
> earlier fields of which widths were specified).

I've compared qed spec with qcow2 spec and like the first one. What the 
need of specifying each offset? Creating a c-structure is simpler when 
you see types. and than offsetof and sizeof may be used if needed. 
Nobody will #define numeric offsets I think.



-- 
Best regards,
Vladimir
* now, @virtuozzo.com instead of @parallels.com. Sorry for this inconvenience.

Re: [Qemu-devel] [PATCH 1/1] parallels: add format spec

[Eric Blake]

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

On 11/17/2015 11:15 PM, Vladimir Sementsov-Ogievskiy wrote:

>> You may want to compare to the qcow2 spec, which also lists expected
>> byte offsets for each field (rather than having to count how many
>> earlier fields of which widths were specified).
> 
> I've compared qed spec with qcow2 spec and like the first one. What the
> need of specifying each offset? Creating a c-structure is simpler when
> you see types. and than offsetof and sizeof may be used if needed.
> Nobody will #define numeric offsets I think.

You'd be surprised (libvirt has some hard-coded numeric offsets:
https://libvirt.org/git/?p=libvirt.git;a=blob;f=src/util/virstoragefile.c;h=2aa1d90;hb=5ed7afa9d#l159)

Also, listing offsets makes it obvious that you are NOT relying on
compiler padding, and makes it obvious whether you have been careful
that all 64-bit quantities are 8-byte-aligned without wasting space.

The original cow format (not qcow or qcow2) has the awful distinction of
NOT having specified offsets, and had different layouts on 32-bit
platforms than it did on 64-bit platforms; hence, we retired it in
commit 550830f9 as unsupportable.

-- 
Eric Blake   eblake redhat com    +1-919-301-3266
Libvirt virtualization library http://libvirt.org


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

Re: [Qemu-devel] [PATCH 1/1] parallels: add format spec

[Vladimir Sementsov-Ogievskiy]

On 18.11.2015 09:39, Eric Blake wrote:
> On 11/17/2015 11:15 PM, Vladimir Sementsov-Ogievskiy wrote:
>
>>> You may want to compare to the qcow2 spec, which also lists expected
>>> byte offsets for each field (rather than having to count how many
>>> earlier fields of which widths were specified).
>> I've compared qed spec with qcow2 spec and like the first one. What the
>> need of specifying each offset? Creating a c-structure is simpler when
>> you see types. and than offsetof and sizeof may be used if needed.
>> Nobody will #define numeric offsets I think.
> You'd be surprised (libvirt has some hard-coded numeric offsets:
> https://libvirt.org/git/?p=libvirt.git;a=blob;f=src/util/virstoragefile.c;h=2aa1d90;hb=5ed7afa9d#l159)
>
> Also, listing offsets makes it obvious that you are NOT relying on
> compiler padding, and makes it obvious whether you have been careful
> that all 64-bit quantities are 8-byte-aligned without wasting space.
>
> The original cow format (not qcow or qcow2) has the awful distinction of
> NOT having specified offsets, and had different layouts on 32-bit
> platforms than it did on 64-bit platforms; hence, we retired it in
> commit 550830f9 as unsupportable.
>

Thanks for explanation, I'll rework this. May be, it's definitely better 
to be absolutely accurate than get more comfort, when it is about 
specification..

-- 
Best regards,
Vladimir
* now, @virtuozzo.com instead of @parallels.com. Sorry for this inconvenience.