[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[PULL v2 73/86] docs/vhost-user: Clarifications for VHOST_USER_ADD/REM_M
From: |
Michael S. Tsirkin |
Subject: |
[PULL v2 73/86] docs/vhost-user: Clarifications for VHOST_USER_ADD/REM_MEM_REG |
Date: |
Mon, 16 May 2022 16:55:13 -0400 |
From: Kevin Wolf <kwolf@redhat.com>
The specification for VHOST_USER_ADD/REM_MEM_REG messages is unclear
in several points, which has led to clients having incompatible
implementations. This changes the specification to be more explicit
about them:
* VHOST_USER_ADD_MEM_REG is not specified as receiving a file
descriptor, though it obviously does need to do so. All
implementations agree on this one, fix the specification.
* VHOST_USER_REM_MEM_REG is not specified as receiving a file
descriptor either, and it also has no reason to do so. rust-vmm does
not send file descriptors for removing a memory region (in agreement
with the specification), libvhost-user and QEMU do (which is a bug),
though libvhost-user doesn't actually make any use of it.
Change the specification so that for compatibility QEMU's behaviour
becomes legal, even if discouraged, but rust-vmm's behaviour becomes
the explicitly recommended mode of operation.
* VHOST_USER_ADD_MEM_REG doesn't have a documented return value, which
is the desired behaviour in the non-postcopy case. It also implemented
like this in QEMU and rust-vmm, though libvhost-user is buggy and
sometimes sends an unexpected reply. This will be fixed in a separate
patch.
However, in postcopy mode it does reply like VHOST_USER_SET_MEM_TABLE.
This behaviour is shared between libvhost-user and QEMU; rust-vmm
doesn't implement postcopy mode yet. Mention it explicitly in the
spec.
* The specification doesn't mention how VHOST_USER_REM_MEM_REG
identifies the memory region to be removed. Change it to describe the
existing behaviour of libvhost-user (guest address, user address and
size must match).
Signed-off-by: Kevin Wolf <kwolf@redhat.com>
Message-Id: <20220407133657.155281-2-kwolf@redhat.com>
Reviewed-by: Raphael Norwitz <raphael.norwitz@nutanix.com>
Reviewed-by: Michael S. Tsirkin <mst@redhat.com>
Signed-off-by: Michael S. Tsirkin <mst@redhat.com>
Reviewed-by: Stefan Hajnoczi <stefanha@redhat.com>
---
docs/interop/vhost-user.rst | 16 ++++++++++++++++
1 file changed, 16 insertions(+)
diff --git a/docs/interop/vhost-user.rst b/docs/interop/vhost-user.rst
index 3c12607517..a99ba4433c 100644
--- a/docs/interop/vhost-user.rst
+++ b/docs/interop/vhost-user.rst
@@ -1376,6 +1376,14 @@ Front-end message types
For further details on postcopy, see ``VHOST_USER_SET_MEM_TABLE``.
They apply to ``VHOST_USER_ADD_MEM_REG`` accordingly.
+ Exactly one file descriptor from which the memory is mapped is
+ passed in the ancillary data.
+
+ In postcopy mode (see ``VHOST_USER_POSTCOPY_LISTEN``), the back-end
+ replies with the bases of the memory mapped region to the front-end.
+ For further details on postcopy, see ``VHOST_USER_SET_MEM_TABLE``.
+ They apply to ``VHOST_USER_ADD_MEM_REG`` accordingly.
+
``VHOST_USER_REM_MEM_REG``
:id: 38
:equivalent ioctl: N/A
@@ -1400,6 +1408,14 @@ Front-end message types
accept messages with one file descriptor. If a file descriptor is
passed, the back-end MUST close it without using it otherwise.
+ The memory region to be removed is identified by its guest address,
+ user address and size. The mmap offset is ignored.
+
+ No file descriptors SHOULD be passed in the ancillary data. For
+ compatibility with existing incorrect implementations, the back-end MAY
+ accept messages with one file descriptor. If a file descriptor is
+ passed, the back-end MUST close it without using it otherwise.
+
``VHOST_USER_SET_STATUS``
:id: 39
:equivalent ioctl: VHOST_VDPA_SET_STATUS
--
MST
- [PULL v2 63/86] docs: vhost-user: replace master/slave with front-end/back-end, (continued)
- [PULL v2 63/86] docs: vhost-user: replace master/slave with front-end/back-end, Michael S. Tsirkin, 2022/05/16
- [PULL v2 65/86] libvhost-user: expose vu_request_to_string, Michael S. Tsirkin, 2022/05/16
- [PULL v2 66/86] docs/devel: start documenting writing VirtIO devices, Michael S. Tsirkin, 2022/05/16
- [PULL v2 67/86] include/hw: start documenting the vhost API, Michael S. Tsirkin, 2022/05/16
- [PULL v2 68/86] hw/virtio/vhost-user: don't suppress F_CONFIG when supported, Michael S. Tsirkin, 2022/05/16
- [PULL v2 69/86] virtio/vhost-user: dynamically assign VhostUserHostNotifiers, Michael S. Tsirkin, 2022/05/16
- [PULL v2 70/86] virtio: drop name parameter for virtio_init(), Michael S. Tsirkin, 2022/05/16
- [PULL v2 71/86] virtio: add vhost support for virtio devices, Michael S. Tsirkin, 2022/05/16
- [PULL v2 75/86] include/hw/pci/pcie_host: Correct PCIE_MMCFG_SIZE_MAX, Michael S. Tsirkin, 2022/05/16
- [PULL v2 72/86] vhost-user: more master/slave things, Michael S. Tsirkin, 2022/05/16
- [PULL v2 73/86] docs/vhost-user: Clarifications for VHOST_USER_ADD/REM_MEM_REG,
Michael S. Tsirkin <=
- [PULL v2 74/86] include/hw/pci/pcie_host: Correct PCIE_MMCFG_BUS_MASK, Michael S. Tsirkin, 2022/05/16
- [PULL v2 76/86] hw/i386: Make pit a property of common x86 base machine type, Michael S. Tsirkin, 2022/05/16
- [PULL v2 77/86] hw/i386: Make pic a property of common x86 base machine type, Michael S. Tsirkin, 2022/05/16
- [PULL v2 78/86] hw/i386/amd_iommu: Fix IOMMU event log encoding errors, Michael S. Tsirkin, 2022/05/16
- [PULL v2 79/86] virtio-net: setup vhost_dev and notifiers for cvq only when feature is negotiated, Michael S. Tsirkin, 2022/05/16
- [PULL v2 80/86] virtio-net: align ctrl_vq index for non-mq guest for vhost_vdpa, Michael S. Tsirkin, 2022/05/16
- [PULL v2 81/86] vhost-vdpa: fix improper cleanup in net_init_vhost_vdpa, Michael S. Tsirkin, 2022/05/16
- [PULL v2 83/86] vhost-vdpa: backend feature should set only once, Michael S. Tsirkin, 2022/05/16
- [PULL v2 82/86] vhost-net: fix improper cleanup in vhost_net_start, Michael S. Tsirkin, 2022/05/16
- [PULL v2 84/86] vhost-vdpa: change name and polarity for vhost_vdpa_one_time_request(), Michael S. Tsirkin, 2022/05/16