[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[PULL 02/13] docs/vhost-user: Clarifications for VHOST_USER_ADD/REM_MEM_
From: |
Kevin Wolf |
Subject: |
[PULL 02/13] docs/vhost-user: Clarifications for VHOST_USER_ADD/REM_MEM_REG |
Date: |
Wed, 4 May 2022 16:25:11 +0200 |
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: Stefan Hajnoczi <stefanha@redhat.com>
Signed-off-by: Kevin Wolf <kwolf@redhat.com>
---
docs/interop/vhost-user.rst | 17 +++++++++++++++++
1 file changed, 17 insertions(+)
diff --git a/docs/interop/vhost-user.rst b/docs/interop/vhost-user.rst
index 4dbc84fd00..f9e721ba5f 100644
--- a/docs/interop/vhost-user.rst
+++ b/docs/interop/vhost-user.rst
@@ -308,6 +308,7 @@ replies. Here is a list of the ones that do:
There are several messages that the master sends with file descriptors passed
in the ancillary data:
+* ``VHOST_USER_ADD_MEM_REG``
* ``VHOST_USER_SET_MEM_TABLE``
* ``VHOST_USER_SET_LOG_BASE`` (if ``VHOST_USER_PROTOCOL_F_LOG_SHMFD``)
* ``VHOST_USER_SET_LOG_FD``
@@ -1334,6 +1335,14 @@ Master message types
``VHOST_USER_REM_MEM_REG`` message, this message is used to set and
update the memory tables of the slave device.
+ 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 slave
+ replies with the bases of the memory mapped region to the master.
+ 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
@@ -1349,6 +1358,14 @@ Master message types
``VHOST_USER_ADD_MEM_REG`` message, this message is used to set and
update the memory tables of the slave device.
+ 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 slave MAY
+ accept messages with one file descriptor. If a file descriptor is
+ passed, the slave MUST close it without using it otherwise.
+
``VHOST_USER_SET_STATUS``
:id: 39
:equivalent ioctl: VHOST_VDPA_SET_STATUS
--
2.35.1
- [PULL 00/13] Block layer patches, Kevin Wolf, 2022/05/04
- [PULL 02/13] docs/vhost-user: Clarifications for VHOST_USER_ADD/REM_MEM_REG,
Kevin Wolf <=
- [PULL 03/13] libvhost-user: Fix extra vu_add/rem_mem_reg reply, Kevin Wolf, 2022/05/04
- [PULL 04/13] vhost-user: Don't pass file descriptor for VHOST_USER_REM_MEM_REG, Kevin Wolf, 2022/05/04
- [PULL 06/13] qcow2: Do not reopen data_file in invalidate_cache, Kevin Wolf, 2022/05/04
- [PULL 09/13] block/vmdk: Fix reopening bs->file, Kevin Wolf, 2022/05/04
- [PULL 01/13] qemu-img: properly list formats which have consistency check implemented, Kevin Wolf, 2022/05/04
- [PULL 07/13] Revert "main-loop: Disable GLOBAL_STATE_CODE() assertions", Kevin Wolf, 2022/05/04
- [PULL 13/13] coroutine-win32: use QEMU_DEFINE_STATIC_CO_TLS(), Kevin Wolf, 2022/05/04
- [PULL 05/13] block: Classify bdrv_get_flags() as I/O function, Kevin Wolf, 2022/05/04
- [PULL 10/13] iotests/reopen-file: Test reopening file child, Kevin Wolf, 2022/05/04
- [PULL 12/13] coroutine: use QEMU_DEFINE_STATIC_CO_TLS(), Kevin Wolf, 2022/05/04