diff options
Diffstat (limited to 'docs/interop')
| -rw-r--r-- | docs/interop/prl-xml.txt | 158 | ||||
| -rw-r--r-- | docs/interop/vhost-user.txt | 96 |
2 files changed, 247 insertions, 7 deletions
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. diff --git a/docs/interop/vhost-user.txt b/docs/interop/vhost-user.txt index 954771d0d8..9fcf48d611 100644 --- a/docs/interop/vhost-user.txt +++ b/docs/interop/vhost-user.txt @@ -53,8 +53,8 @@ Depending on the request type, payload can be: * A vring state description --------------- - | index | num | - --------------- + | index | num | + --------------- Index: a 32-bit index Num: a 32-bit number @@ -66,11 +66,14 @@ Depending on the request type, payload can be: Index: a 32-bit vring index Flags: a 32-bit vring flags - Descriptor: a 64-bit user address of the vring descriptor table - Used: a 64-bit user address of the vring used ring - Available: a 64-bit user address of the vring available ring + Descriptor: a 64-bit ring address of the vring descriptor table + Used: a 64-bit ring address of the vring used ring + Available: a 64-bit ring address of the vring available ring Log: a 64-bit guest address for logging + Note that a ring address is an IOVA if VIRTIO_F_IOMMU_PLATFORM has been + negotiated. Otherwise it is a user address. + * Memory regions description --------------------------------------------------- | num regions | padding | region0 | ... | region7 | @@ -116,6 +119,19 @@ Depending on the request type, payload can be: - 3: IOTLB invalidate - 4: IOTLB access fail + * Virtio device config space + ----------------------------------- + | offset | size | flags | payload | + ----------------------------------- + + Offset: a 32-bit offset of virtio device's configuration space + Size: a 32-bit configuration space access size in bytes + Flags: a 32-bit value: + - 0: Vhost master messages used for writeable fields + - 1: Vhost master messages used for live migration + Payload: Size bytes array holding the contents of the virtio + device's configuration space + In QEMU the vhost-user message is implemented with the following struct: typedef struct VhostUserMsg { @@ -129,6 +145,7 @@ typedef struct VhostUserMsg { VhostUserMemory memory; VhostUserLog log; struct vhost_iotlb_msg iotlb; + VhostUserConfig config; }; } QEMU_PACKED VhostUserMsg; @@ -211,8 +228,8 @@ Multiple queue is treated as a protocol extension, hence the slave has to implement protocol features first. The multiple queues feature is supported only when the protocol feature VHOST_USER_PROTOCOL_F_MQ (bit 0) is set. -The max number of queues the slave supports can be queried with message -VHOST_USER_GET_PROTOCOL_FEATURES. Master should stop when the number of +The max number of queue pairs the slave supports can be queried with message +VHOST_USER_GET_QUEUE_NUM. Master should stop when the number of requested queues is bigger than that. As all queues share one connection, the master uses a unique index for each @@ -273,6 +290,30 @@ Once the source has finished migration, rings will be stopped by the source. No further update must be done before rings are restarted. +Memory access +------------- + +The master sends a list of vhost memory regions to the slave using the +VHOST_USER_SET_MEM_TABLE message. Each region has two base addresses: a guest +address and a user address. + +Messages contain guest addresses and/or user addresses to reference locations +within the shared memory. The mapping of these addresses works as follows. + +User addresses map to the vhost memory region containing that user address. + +When the VIRTIO_F_IOMMU_PLATFORM feature has not been negotiated: + + * Guest addresses map to the vhost memory region containing that guest + address. + +When the VIRTIO_F_IOMMU_PLATFORM feature has been negotiated: + + * Guest addresses are also called I/O virtual addresses (IOVAs). They are + translated to user addresses via the IOTLB. + + * The vhost memory region guest address is not used. + IOMMU support ------------- @@ -596,6 +637,32 @@ Master message types and expect this message once (per VQ) during device configuration (ie. before the master starts the VQ). + * VHOST_USER_GET_CONFIG + + Id: 24 + Equivalent ioctl: N/A + Master payload: virtio device config space + Slave payload: virtio device config space + + Submitted by the vhost-user master to fetch the contents of the virtio + device configuration space, vhost-user slave's payload size MUST match + master's request, vhost-user slave uses zero length of payload to + indicate an error to vhost-user master. The vhost-user master may + cache the contents to avoid repeated VHOST_USER_GET_CONFIG calls. + +* VHOST_USER_SET_CONFIG + + Id: 25 + Equivalent ioctl: N/A + Master payload: virtio device config space + Slave payload: N/A + + Submitted by the vhost-user master when the Guest changes the virtio + device configuration space and also can be used for live migration + on the destination host. The vhost-user slave must check the flags + field, and slaves MUST NOT accept SET_CONFIG for read-only + configuration space fields unless the live migration bit is set. + Slave message types ------------------- @@ -614,6 +681,21 @@ Slave message types This request should be send only when VIRTIO_F_IOMMU_PLATFORM feature has been successfully negotiated. +* VHOST_USER_SLAVE_CONFIG_CHANGE_MSG + + Id: 2 + Equivalent ioctl: N/A + Slave payload: N/A + Master payload: N/A + + Vhost-user slave sends such messages to notify that the virtio device's + configuration space has changed, for those host devices which can support + such feature, host driver can send VHOST_USER_GET_CONFIG message to slave + to get the latest content. If VHOST_USER_PROTOCOL_F_REPLY_ACK is + negotiated, and slave set the VHOST_USER_NEED_REPLY flag, master must + respond with zero when operation is successfully completed, or non-zero + otherwise. + VHOST_USER_PROTOCOL_F_REPLY_ACK: ------------------------------- The original vhost-user specification only demands replies for certain |