diff options
Diffstat (limited to 'docs/interop/vhost-user.txt')
| -rw-r--r-- | docs/interop/vhost-user.txt | 96 |
1 files changed, 89 insertions, 7 deletions
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 |