Lines Matching full:is
10 Licence: This work is licensed under the terms of the GNU GPL,
19 This protocol is aiming to complement the ``ioctl`` interface used to
27 *back-end*. The *front-end* is the application that shares its virtqueues, in
28 our case QEMU. The *back-end* is the consumer of the virtqueues.
30 In the current implementation QEMU is the *front-end*, and the *back-end*
31 is the external process consuming the virtio queues, for example a
35 implementations, it is recommended to follow the :ref:`Backend program
45 is supported on any platform that provides the following features:
54 - Either eventfd or pipe/pipe2. On platforms where eventfd is not
80 - Bit 2 is the reply flag - needs to be sent on each reply from the back-end
81 - Bit 3 is the need_reply flag - see :ref:`REPLY_ACK <reply_ack>` for
124 back-end will process. This is a free-running index that is not
140 back-end will process. This is a free-running index that is not
144 will place the next descriptor. This is a free-running index that
145 is not wrapped by the ring size.
167 Note that a ring address is an IOVA if ``VIRTIO_F_IOMMU_PLATFORM`` has
168 been negotiated. Otherwise it is a user address.
197 - Bit 0 is set for Xen foreign memory mapping.
198 - Bit 1 is set for Xen grant memory mapping.
199 - Bit 8 is set if the memory region can not be mapped in advance, and memory
203 amount of memory at once and unmap it after it is used.
216 :region: region is represented by :ref:`Memory region description <memory_region_description>`.
335 the state is transferred:
346 regions before switch-over to the destination): The VM guest is
347 stopped, and the vhost-user device is suspended (see
351 iterative migration while the device is running.
356 In QEMU the vhost-user message is implemented with the following struct:
380 The protocol for vhost-user is based on the existing implementation of
414 If *front-end* is unable to send the full message or receives a wrong
428 Note that VHOST_USER_F_PROTOCOL_FEATURES is the UNUSED (30) feature
445 * While a ring is stopped, the back-end must not process the ring at
446 all, regardless of whether it is enabled or disabled. The
448 into effect once the ring is started.
458 Each ring is initialized in a stopped and disabled state. The back-end
459 must start a ring upon receiving a kick (that is, detecting that file
460 descriptor is readable) on the descriptor specified by
479 While all vrings are stopped, the device is *suspended*. In addition to
495 number of virtqueues is chosen by the back-end. The number can depend on host
500 queues. This is treated as a protocol extension, hence the back-end has to
501 implement protocol features first. The multiple queues feature is supported
502 only when the protocol feature ``VHOST_USER_PROTOCOL_F_MQ`` (bit 0) is set.
506 queues is bigger than that.
515 feature, even for devices with a fixed number of virtqueues, since it is simple
537 ``VHOST_VRING_F_LOG`` is part of ring's flags.
543 The log memory fd is provided in the ancillary data of
547 The size of the log is supplied as part of ``VhostUserMsg`` which
556 Where ``addr`` is the guest physical address.
561 ``VHOST_VRING_F_LOG`` is set for this ring), ``log_guest_addr`` should
563 used ring is logged at this offset from log start. Also note that this
569 ``VHOST_USER_SET_LOG_FD`` is an optional message with an eventfd in
577 In postcopy migration the back-end is started before all the memory has
580 'userfault'-fd and registers the memory with it; this fd is then
582 userfaultfd for pages that are accessed and when the page is available
597 transparently resume operation until another migration attempt is made.
599 Generally, the front-end is connected to a virtual machine guest (which
609 To do this, the back-end state is transferred from back-end to front-end
611 transfer happens over a channel that is negotiated using the
615 * Direction of transfer: On the source, the data is saved, transferring
617 is loaded, transferring it from the front-end to the back-end.
619 * Migration phase: Currently, the only supported phase is the period
624 migration while the device is running.
626 The nature of the channel is implementation-defined, but it must
632 * When saving, the writing end is the source back-end, and the reading
633 end is the source front-end. After reading the state data from the
637 * When loading, the writing end is the destination front-end, and the
638 reading end is the destination back-end. After reading the state data
683 * The vhost memory region guest address is not used.
697 (3), the I/O virtual address and the size. On success, the back-end is
710 operation is completed if the reply-ack feature is negotiated and
714 the IOTLB miss message is invalid (invalid IOVA or permission).
725 An optional communication channel is provided if the back-end declares
729 The fd is provided via ``VHOST_USER_SET_BACKEND_REQ_FD`` ancillary data.
734 If ``VHOST_USER_PROTOCOL_F_BACKEND_SEND_FD`` protocol feature is
743 resubmit inflight I/Os. If virtqueue is processed in order, we can
754 between front-end and back-end. And the format of this buffer is described
761 N is the number of available virtqueues. The back-end could get it from num
769 /* Indicate whether this descriptor is inflight or not.
777 * Only available when batching is used for submitting */
827 #. Steps 1,2,3 may be performed repeatedly if batching is possible
857 /* Indicate whether this descriptor is inflight or not.
935 #. If ``d`` is head descriptor,
945 #. If ``d`` is last descriptor, set ``desc[old_free_head].last`` to
956 #. If ``d`` is last descriptor, set ``old_free_head`` to ``free_head``
969 #. Steps 1,2,3,4 may be performed repeatedly if batching is possible
992 #. If ``d.flags`` is not equal to the calculated flags value (means
1011 In some limited situations (e.g. for simulation) it is desirable to
1018 cause the sending application(s) to block, it is not advised to use
1019 this feature unless absolutely necessary. It is also considered an
1022 the former is necessary for getting a message channel from the back-end
1090 ``VHOST_USER_F_PROTOCOL_FEATURES`` is present in
1107 Only legal if feature bit ``VHOST_USER_F_PROTOCOL_FEATURES`` is present in
1121 Issued when a new connection is established. It marks the sender
1132 This is no longer used. Used to be sent to request disabling all
1134 state (this interpretation would lead to bugs). It is recommended
1145 vring addresses. In the ancillary data there is an array of file
1156 ``NEED_REPLY_MASK`` is not set in this case. QEMU will then
1171 the log memory fd is provided in the ancillary data of
1181 Sets the logging file descriptor, which is passed as ancillary data.
1208 process in the *Available Ring*. The device is supposed to read the
1215 Consequently, the payload type is specific to the type of virt queue
1232 descriptor index at which to put new descriptors, which is the
1233 value in the vring structure in memory, so this value is not
1236 * For a packed virtqueue, neither index is explicitly available to
1240 Consequently, the payload type is specific to the type of virt queue
1244 When and as long as all of a device's vrings are stopped, it is
1248 The request payload's *num* field is currently reserved and must be
1257 Set the event file descriptor for adding buffers to the vring. It is
1260 Bits (0-7) of the payload contain the vring index. Bit 8 is the
1261 invalid FD flag. This flag is set when there is no file descriptor
1265 this message isn't necessary as the ring is also started on the
1276 Set the event file descriptor to signal when buffers are used. It is
1279 Bits (0-7) of the payload contain the vring index. Bit 8 is the
1280 invalid FD flag. This flag is set when there is no file descriptor
1295 Set the event file descriptor to signal when error occurs. It is
1298 Bits (0-7) of the payload contain the vring index. Bit 8 is the
1299 invalid FD flag. This flag is set when there is no file descriptor
1316 is set in queried protocol features by
1337 is terminated for guest that does not support GUEST_ANNOUNCE.
1339 Only legal if feature bit ``VHOST_USER_F_PROTOCOL_FEATURES`` is
1341 ``VHOST_USER_PROTOCOL_F_RARP`` is present in
1356 is present in ``VHOST_USER_GET_FEATURES`` and protocol feature bit
1357 ``VHOST_USER_PROTOCOL_F_NET_MTU`` is present in
1360 If ``VHOST_USER_PROTOCOL_F_REPLY_ACK`` is negotiated, the back-end must
1361 respond with zero in case the specified MTU is valid, or non-zero
1370 Set the socket file descriptor for back-end initiated requests. It is passed
1375 feature bit ``VHOST_USER_PROTOCOL_F_BACKEND_REQ`` bit is present in
1377 ``VHOST_USER_PROTOCOL_F_REPLY_ACK`` is negotiated, the back-end must
1401 Set the endianness of a VQ for legacy devices. Little-endian is
1402 indicated with state.num set to 0 and big-endian is indicated with
1417 When ``VHOST_USER_PROTOCOL_F_CONFIG`` is negotiated, this message is
1431 When ``VHOST_USER_PROTOCOL_F_CONFIG`` is negotiated, this message is
1436 configuration space fields unless the live migration bit is set.
1470 When ``VHOST_USER_PROTOCOL_F_PAGEFAULT`` is supported, the front-end
1471 advises back-end that a migration with postcopy enabled is underway,
1473 stage the migration is still in precopy mode.
1481 happened. The back-end must ensure that shared memory is registered
1484 This is always sent sometime after a ``VHOST_USER_POSTCOPY_ADVISE``,
1485 and thus only when ``VHOST_USER_PROTOCOL_F_PAGEFAULT`` is supported.
1493 must disable the userfaultfd. The reply is an acknowledgement
1496 When ``VHOST_USER_PROTOCOL_F_PAGEFAULT`` is supported, this message
1497 is sent at the end of the migration, after
1500 The value returned is an error indication; 0 is success.
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
1531 Sets the GPU protocol socket file descriptor, which is passed as
1532 ancillary data. The GPU protocol is used to inform the front-end of
1547 feature is set by the back-end.
1561 The state.num field is currently reserved and must be set to 0.
1570 feature has been successfully negotiated, this message is submitted
1584 feature has been successfully negotiated, this message is submitted
1590 ``VHOST_USER_REM_MEM_REG`` message, this message is used to set and
1593 Exactly one file descriptor from which the memory is mapped is
1608 feature has been successfully negotiated, this message is submitted
1614 ``VHOST_USER_ADD_MEM_REG`` message, this message is used to set and
1617 The memory region to be removed is identified by its guest address,
1618 user address and size. The mmap offset is ignored.
1622 accept messages with one file descriptor. If a file descriptor is
1632 successfully negotiated, this message is submitted by the front-end to
1643 successfully negotiated, this message is submitted by the front-end to
1654 feature has been successfully negotiated, and the UUID is found
1655 in the exporters cache, this message is submitted by the front-end
1658 is successful, or no fd otherwise.
1668 back-end) may create the channel. The nature of this channel is not
1670 must create a file descriptor that is provided to the respectively
1691 Whether the back-end should decide to use its own channel is decided
1692 based on efficiency: If the channel is a pipe, both ends will most
1695 zero-copy, is considered more efficient and thus preferred. If the
1702 The value returned is both an indication for success, and whether a
1703 file descriptor for a back-end-provided channel is returned: Bits 0–7
1704 are 0 on success, and non-zero on error. Bit 8 is the invalid FD
1705 flag; this flag is set when there is no file descriptor returned.
1706 When this flag is not set, the front-end must use the returned file
1724 The value returned indicates success or error; 0 is success, any
1725 non-zero value is an error.
1733 For this type of message, the request is sent by the back-end and the reply
1734 is sent by the front-end.
1744 access failure. If ``VHOST_USER_PROTOCOL_F_REPLY_ACK`` is
1746 must respond with zero when operation is successfully completed, or
1757 When ``VHOST_USER_PROTOCOL_F_CONFIG`` is negotiated, vhost-user
1762 ``VHOST_USER_PROTOCOL_F_REPLY_ACK`` is negotiated, and the back-end sets the
1764 operation is successfully completed, or non-zero otherwise.
1772 Sets host notifier for a specified queue. The queue index is
1774 host notifier is described by the file descriptor (typically it's a
1775 VFIO device fd) which is passed as ancillary data and the size
1776 (which is mmap size and should be the same as host page size) and
1777 offset (which is mmap offset) carried in the vring area
1783 request is sent with a file descriptor.
1801 The state.num field is currently reserved and must be set to 0.
1815 The state.num field is currently reserved and must be set to 0.
1827 The back-end is responsible of keeping its own table with exported dma-buf fds.
1830 exporter back-end. If ``VHOST_USER_PROTOCOL_F_REPLY_ACK`` is negotiated, and
1832 respond with zero when operation is successfully completed, or non-zero
1845 it) will have permission to remove it. Otherwise, the message is ignored.
1847 the UUID. If ``VHOST_USER_PROTOCOL_F_REPLY_ACK`` is negotiated, and the
1849 with zero when operation is successfully completed, or non-zero otherwise.
1861 when the operation is successful, or non-zero otherwise. Note that if the
1862 operation fails, no fd is sent to the backend.
1881 of the command. Today, QEMU is expected to terminate the main vhost-user
1897 is a good idea to follow the conventions listed here when
1909 If the back-end is not capable of enabling a requested feature on the
1923 the SIGTERM signal is received. Eventually, it may receive SIGKILL by
1932 It is incompatible with --fd.
1936 When this argument is given, the back-end program is started with the
1937 vhost-user socket as file descriptor FDNUM. It is incompatible with
1948 The JSON output is described in the ``vhost-user.json`` schema, by