docs/interop/vhost-user.rst

26 The protocol defines 2 sides of the communication, *front-end* and
27 *back-end*. The *front-end* is the application that shares its virtqueues, in
30 In the current implementation QEMU is the *front-end*, and the *back-end*
38 The *front-end* and *back-end* can be either a client (i.e. connecting) or
202   front-end may not allow it. The back-end should rather map only the required
281   - 0: Vhost front-end messages used for writable fields
282   - 1: Vhost front-end messages used for live migration
337   - 0: Save: Transfer the state from the back-end to the front-end,
339   - 1: Load: Transfer the state from the front-end to the back-end,
385 The communication consists of the *front-end* sending message requests and
400 There are several messages that the front-end sends with file descriptors passed
414 If *front-end* is unable to send the full message or receives a wrong
422 allows full backwards compatibility on both front-end and back-end.  As
436 fashion. Old vhost-user front-end and back-end implementations continue to
468 the front-end without ``VHOST_USER_F_PROTOCOL_FEATURES`` set, the
484 * not send any messages to the front-end,
485 * still process and reply to messages from the front-end.
490 Many devices have a fixed number of virtqueues.  In this case the front-end
505 ``VHOST_USER_GET_QUEUE_NUM``. Front-end should stop when the number of requested
508 As all queues share one connection, the front-end uses a unique index for each
511 The front-end enables queues by sending message ``VHOST_USER_SET_VRING_ENABLE``.
518 Front-ends must not rely on the ``VHOST_USER_PROTOCOL_F_MQ`` protocol feature for
525 During live migration, the front-end may need to track the modifications
526 the back-end makes to the memory mapped regions. The front-end should mark
530 To start/stop logging of data/used ring writes, the front-end may send
570 ancillary data, it may be used to inform the front-end that the log has
581 passed back over to the front-end.  The front-end services requests on the
584 back-end.  The front-end indicates support for this via the
599 Generally, the front-end is connected to a virtual machine guest (which
603 provides functionality to have the front-end include the back-end's
609 To do this, the back-end state is transferred from back-end to front-end
616   it from the back-end to the front-end.  On the destination, the data
617   is loaded, transferring it from the front-end to the back-end.
633   end is the source front-end.  After reading the state data from the
634   channel, the source front-end must transfer it to the destination
635   front-end through an implementation-defined mechanism.
637 * When loading, the writing end is the destination front-end, and the
647 front-end, however, will re-initialize the vhost state on the
655 front-end has seen all data transferred (when the transfer FD has been
664 The front-end sends a list of vhost memory regions to the back-end using the
689 front-end sends IOTLB entries update & invalidation by sending
703 requests to the front-end with a ``struct vhost_iotlb_msg`` as
709 rely on the reply-ack feature, so the front-end may send a reply when
712 either front-end sent an update message containing the IOTLB entry
713 containing requested address and permission, or front-end sent nothing if
716 The front-end isn't expected to take the initiative to send IOTLB update
727 back-end to make requests to the front-end.
731 A back-end may then send ``VHOST_USER_BACKEND_*`` messages to the front-end
736 each message) to front-end via ancillary data using this fd communication
751 information of inflight descriptors and share it with front-end for
754 between front-end and back-end. And the format of this buffer is described
1023 to the front-end, while the latter needs to be used with the in-band
1057 Front-end message types
1122   as the front-end that owns of the session. This can be used on the *back-end*
1151   regions to the front-end.  The back-end must have mmap'd the regions but
1388   The front-end sends such requests to update and invalidate entries in the
1409   configuration (ie. before the front-end starts the VQ).
1418   submitted by the vhost-user front-end to fetch the contents of the
1420   MUST match the front-end's request, vhost-user back-end uses zero length of
1421   payload to indicate an error to the vhost-user front-end. The vhost-user
1422   front-end may cache the contents to avoid repeated
1432   submitted by the vhost-user front-end when the Guest changes the virtio
1470   When ``VHOST_USER_PROTOCOL_F_PAGEFAULT`` is supported, the front-end
1480   The front-end advises back-end that a transition to postcopy mode has
1492   The front-end advises that postcopy migration has now completed.  The back-end
1509   been successfully negotiated, this message is submitted by the front-end to
1521   been successfully negotiated, this message is submitted by the front-end to
1532   ancillary data. The GPU protocol is used to inform the front-end of
1557   submitted by the front-end to indicate that a buffer was added to
1571   by the front-end to the back-end. The back-end should return the message with a
1585   by the front-end to the back-end. The message payload contains a memory
1597   replies with the bases of the memory mapped region to the front-end.
1609   by the front-end to the back-end. The message payload contains a memory
1632   successfully negotiated, this message is submitted by the front-end to
1643   successfully negotiated, this message is submitted by the front-end to
1655   in the exporters cache, this message is submitted by the front-end
1666   Front-end and back-end negotiate a channel over which to transfer the
1667   back-end's internal state during migration.  Either side (front-end or
1684   Initially, the front-end creates a channel along with such an FD.  It
1688   front-end as ancillary data of the reply.  If so, the front-end must
1706   When this flag is not set, the front-end must use the returned file
1734 is sent by the front-end.
1745   negotiated, and back-end set the ``VHOST_USER_NEED_REPLY`` flag, the front-end
1763   ``VHOST_USER_NEED_REPLY`` flag, the front-end must respond with zero when
1799   descriptor or having the front-end relying on polling.
1813   set by the front-end via ``VHOST_USER_SET_VRING_ERR``.
1829   it will send a message to the front-end, which will act as a proxy to the
1831   the back-end sets the ``VHOST_USER_NEED_REPLY`` flag, the front-end must
1848   back-end sets the ``VHOST_USER_NEED_REPLY`` flag, the front-end must respond