[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[PULL 03/28] docs: add a section on the generalities of vhost-user
From: |
Alex Bennée |
Subject: |
[PULL 03/28] docs: add a section on the generalities of vhost-user |
Date: |
Fri, 23 Jul 2021 18:03:29 +0100 |
While we do mention some of this stuff in the various daemons and
manuals the subtleties of the socket and memory sharing are sometimes
missed. This document attempts to give some background on vhost-user
daemons in general terms.
Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
Reviewed-by: Stefan Hajnoczi <stefanha@redhat.com>
Message-Id: <20210720232703.10650-4-alex.bennee@linaro.org>
diff --git a/docs/interop/vhost-user.rst b/docs/interop/vhost-user.rst
index d6085f7045..7fc693521e 100644
--- a/docs/interop/vhost-user.rst
+++ b/docs/interop/vhost-user.rst
@@ -1,3 +1,5 @@
+.. _vhost_user_proto:
+
===================
Vhost-user Protocol
===================
diff --git a/docs/system/device-emulation.rst b/docs/system/device-emulation.rst
index 8adf05f606..7afcfd8064 100644
--- a/docs/system/device-emulation.rst
+++ b/docs/system/device-emulation.rst
@@ -86,4 +86,5 @@ Emulated Devices
devices/net.rst
devices/nvme.rst
devices/usb.rst
+ devices/vhost-user.rst
devices/virtio-pmem.rst
diff --git a/docs/system/devices/vhost-user.rst
b/docs/system/devices/vhost-user.rst
new file mode 100644
index 0000000000..86128114fa
--- /dev/null
+++ b/docs/system/devices/vhost-user.rst
@@ -0,0 +1,59 @@
+.. _vhost_user:
+
+vhost-user back ends
+--------------------
+
+vhost-user back ends are way to service the request of VirtIO devices
+outside of QEMU itself. To do this there are a number of things
+required.
+
+vhost-user device
+===================
+
+These are simple stub devices that ensure the VirtIO device is visible
+to the guest. The code is mostly boilerplate although each device has
+a ``chardev`` option which specifies the ID of the ``--chardev``
+device that connects via a socket to the vhost-user *daemon*.
+
+vhost-user daemon
+=================
+
+This is a separate process that is connected to by QEMU via a socket
+following the :ref:`vhost_user_proto`. There are a number of daemons
+that can be built when enabled by the project although any daemon that
+meets the specification for a given device can be used.
+
+Shared memory object
+====================
+
+In order for the daemon to access the VirtIO queues to process the
+requests it needs access to the guest's address space. This is
+achieved via the ``memory-backend-file`` or ``memory-backend-memfd``
+objects. A reference to a file-descriptor which can access this object
+will be passed via the socket as part of the protocol negotiation.
+
+Currently the shared memory object needs to match the size of the main
+system memory as defined by the ``-m`` argument.
+
+Example
+=======
+
+First start you daemon.
+
+.. parsed-literal::
+
+ $ virtio-foo --socket-path=/var/run/foo.sock $OTHER_ARGS
+
+The you start your QEMU instance specifying the device, chardev and
+memory objects.
+
+.. parsed-literal::
+
+ $ |qemu_system| \\
+ -m 4096 \\
+ -chardev socket,id=ba1,path=/var/run/foo.sock \\
+ -device vhost-user-foo,chardev=ba1,$OTHER_ARGS \\
+ -object memory-backend-memfd,id=mem,size=4G,share=on \\
+ -numa node,memdev=mem \\
+ ...
+
--
2.20.1
- [PULL for 6.1-rc1 00/28] doc, metadata, plugin and testing updates, Alex Bennée, 2021/07/23
- [PULL 01/28] gitignore: Update with some filetypes, Alex Bennée, 2021/07/23
- [PULL 03/28] docs: add a section on the generalities of vhost-user,
Alex Bennée <=
- [PULL 04/28] configure: remove needless if leg, Alex Bennée, 2021/07/23
- [PULL 02/28] docs: collect the disparate device emulation docs into one section, Alex Bennée, 2021/07/23
- [PULL 07/28] contrib/gitdm: add domain-map for MontaVista, Alex Bennée, 2021/07/23
- [PULL 06/28] .mailmap: fix up some broken commit authors, Alex Bennée, 2021/07/23
- [PULL 09/28] gitdm.config: sort the corporate GroupMap entries, Alex Bennée, 2021/07/23
- [PULL 08/28] contrib/gitdm: add a group mapping for robot scanners, Alex Bennée, 2021/07/23
- [PULL 10/28] contrib/gitdm: add domain-map/group-map mappings for Samsung, Alex Bennée, 2021/07/23
- [PULL 05/28] contrib/gitdm: add some new aliases to fix up commits, Alex Bennée, 2021/07/23
- [PULL 11/28] contrib/gitdm: add domain-map for Eldorado, Alex Bennée, 2021/07/23
- [PULL 19/28] contrib/gitdm: add more individual contributor entries., Alex Bennée, 2021/07/23