aboutsummaryrefslogtreecommitdiff
path: root/docs/interop
diff options
context:
space:
mode:
authorViresh Kumar <viresh.kumar@linaro.org>2023-03-09 14:21:01 +0530
committerMichael S. Tsirkin <mst@redhat.com>2023-04-21 04:25:52 -0400
commitf21e95ee97d5adb4a274b48c6c8f70a221c1f513 (patch)
treee35e894534f5452b628a8b4fb54d9e833ffd2011 /docs/interop
parent17c67f6849551b2bbffb7a3a8b490b853df86129 (diff)
downloadqemu-f21e95ee97d5adb4a274b48c6c8f70a221c1f513.zip
qemu-f21e95ee97d5adb4a274b48c6c8f70a221c1f513.tar.gz
qemu-f21e95ee97d5adb4a274b48c6c8f70a221c1f513.tar.bz2
docs: vhost-user: Add Xen specific memory mapping support
The current model of memory mapping at the back-end works fine where a standard call to mmap() (for the respective file descriptor) is enough before the front-end can start accessing the guest memory. There are other complex cases though where the back-end needs more information and simple mmap() isn't enough. For example Xen, a type-1 hypervisor, currently supports memory mapping via two different methods, foreign-mapping (via /dev/privcmd) and grant-dev (via /dev/gntdev). In both these cases, the back-end needs to call mmap() and ioctl(), with extra information like the Xen domain-id of the guest whose memory we are trying to map. Add a new protocol feature, 'VHOST_USER_PROTOCOL_F_XEN_MMAP', which lets the back-end know about the additional memory mapping requirements. When this feature is negotiated, the front-end will send the additional information within the memory regions themselves. Signed-off-by: Viresh Kumar <viresh.kumar@linaro.org> Message-Id: <6d0bd7f0e1aeec3ddb603ae4ff334c75c7d0d7b3.1678351495.git.viresh.kumar@linaro.org> Reviewed-by: Michael S. Tsirkin <mst@redhat.com> Signed-off-by: Michael S. Tsirkin <mst@redhat.com> Reviewed-by: Stefan Hajnoczi <stefanha@redhat.com> Reviewed-by: Alex Bennée <alex.bennee@linaro.org>
Diffstat (limited to 'docs/interop')
-rw-r--r--docs/interop/vhost-user.rst21
1 files changed, 21 insertions, 0 deletions
diff --git a/docs/interop/vhost-user.rst b/docs/interop/vhost-user.rst
index 1720d68..5a070ad 100644
--- a/docs/interop/vhost-user.rst
+++ b/docs/interop/vhost-user.rst
@@ -145,6 +145,26 @@ Memory region description
:mmap offset: 64-bit offset where region starts in the mapped memory
+When the ``VHOST_USER_PROTOCOL_F_XEN_MMAP`` protocol feature has been
+successfully negotiated, the memory region description contains two extra
+fields at the end.
+
++---------------+------+--------------+-------------+----------------+-------+
+| guest address | size | user address | mmap offset | xen mmap flags | domid |
++---------------+------+--------------+-------------+----------------+-------+
+
+:xen mmap flags: 32-bit bit field
+
+- Bit 0 is set for Xen foreign memory mapping.
+- Bit 1 is set for Xen grant memory mapping.
+- Bit 8 is set if the memory region can not be mapped in advance, and memory
+ areas within this region must be mapped / unmapped only when required by the
+ back-end. The back-end shouldn't try to map the entire region at once, as the
+ front-end may not allow it. The back-end should rather map only the required
+ amount of memory at once and unmap it after it is used.
+
+:domid: a 32-bit Xen hypervisor specific domain id.
+
Single memory region description
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -864,6 +884,7 @@ Protocol features
#define VHOST_USER_PROTOCOL_F_INBAND_NOTIFICATIONS 14
#define VHOST_USER_PROTOCOL_F_CONFIGURE_MEM_SLOTS 15
#define VHOST_USER_PROTOCOL_F_STATUS 16
+ #define VHOST_USER_PROTOCOL_F_XEN_MMAP 17
Front-end message types
-----------------------