All of lore.kernel.org
 help / color / mirror / Atom feed
From: "Alex Bennée" <alex.bennee@linaro.org>
To: qemu-devel@nongnu.org
Cc: fam@euphon.net, berrange@redhat.com,
	"Michael S. Tsirkin" <mst@redhat.com>,
	f4bug@amsat.org, stefanha@redhat.com, crosa@redhat.com,
	pbonzini@redhat.com, "Alex Bennée" <alex.bennee@linaro.org>,
	aurelien@aurel32.net
Subject: [PATCH v1 03/29] docs: add a section on the generalities of vhost-user
Date: Wed, 21 Jul 2021 00:26:37 +0100	[thread overview]
Message-ID: <20210720232703.10650-4-alex.bennee@linaro.org> (raw)
In-Reply-To: <20210720232703.10650-1-alex.bennee@linaro.org>

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: <20210714182056.25888-4-alex.bennee@linaro.org>
---
 docs/interop/vhost-user.rst        |  2 +
 docs/system/device-emulation.rst   |  1 +
 docs/system/devices/vhost-user.rst | 59 ++++++++++++++++++++++++++++++
 3 files changed, 62 insertions(+)
 create mode 100644 docs/system/devices/vhost-user.rst

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 7af5dbefab..3bebb862b9 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.32.0.264.g75ae10bc75



  parent reply	other threads:[~2021-07-20 23:31 UTC|newest]

Thread overview: 36+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2021-07-20 23:26 [PATCH for 6.1-rc1 v1 00/29] various fixes pre-PR (metadata, docs, plugins, testing) Alex Bennée
2021-07-20 23:26 ` [PATCH v1 01/29] gitignore: Update with some filetypes Alex Bennée
2021-07-20 23:26 ` [PATCH v1 02/29] docs: collect the disparate device emulation docs into one section Alex Bennée
2021-07-21 13:25   ` Markus Armbruster
2021-07-20 23:26 ` Alex Bennée [this message]
2021-07-20 23:26 ` [PATCH v1 04/29] configure: remove needless if leg Alex Bennée
2021-07-20 23:26 ` [PATCH v1 05/29] contrib/gitdm: add some new aliases to fix up commits Alex Bennée
2021-07-20 23:26 ` [PATCH v1 06/29] .mailmap: fix up some broken commit authors Alex Bennée
2021-07-20 23:26 ` [PATCH v1 07/29] contrib/gitdm: add domain-map for MontaVista Alex Bennée
2021-07-20 23:26 ` [PATCH v1 08/29] contrib/gitdm: add a group mapping for robot scanners Alex Bennée
2021-07-20 23:26 ` [PATCH v1 09/29] gitdm.config: sort the corporate GroupMap entries Alex Bennée
2021-07-21  8:06   ` Philippe Mathieu-Daudé
2021-07-20 23:26 ` [PATCH v1 10/29] contrib/gitdm: add domain-map/group-map mappings for Samsung Alex Bennée
2021-07-20 23:26 ` [PATCH v1 11/29] contrib/gitdm: add domain-map for Eldorado Alex Bennée
2021-07-20 23:26 ` [PATCH v1 12/29] contrib/gitdm: add domain-map/group-map for Wind River Alex Bennée
2021-07-20 23:26 ` [PATCH v1 13/29] contrib/gitdm: un-ironically add a mapping for LWN Alex Bennée
2021-07-20 23:26 ` [PATCH v1 14/29] contrib/gitdm: add domain-map for Crudebyte Alex Bennée
2021-07-20 23:26 ` [PATCH v1 15/29] contrib/gitdm: add domain-map for NVIDIA Alex Bennée
2021-07-20 23:26 ` [PATCH v1 16/29] contrib/gitdm: add group-map for Netflix Alex Bennée
2021-07-20 23:26 ` [PATCH v1 17/29] contrib/gitdm: add an explicit academic entry for BU Alex Bennée
2021-07-20 23:26 ` [PATCH v1 18/29] contrib/gitdm: add a new interns group-map for GSoC/Outreachy work Alex Bennée
2021-07-20 23:26 ` [PATCH v1 19/29] contrib/gitdm: add more individual contributor entries Alex Bennée
2021-07-20 23:26 ` [PATCH v1 20/29] tcg/plugins: implement a qemu_plugin_user_exit helper Alex Bennée
2021-07-20 23:26 ` [PATCH v1 21/29] plugins/cache: Fixed a bug with destroying FIFO metadata Alex Bennée
2021-07-20 23:26 ` [PATCH v1 22/29] plugins/cache: limited the scope of a mutex lock Alex Bennée
2021-07-20 23:26 ` [PATCH v1 23/29] plugins/cache: Fixed "function decl. is not a prototype" warnings Alex Bennée
2021-07-21  8:09   ` Philippe Mathieu-Daudé
2021-07-20 23:26 ` [PATCH v1 24/29] plugins: Fix physical address calculation for IO regions Alex Bennée
2021-07-20 23:26 ` [PATCH v1 25/29] hw/tricore: fix inclusion of tricore_testboard Alex Bennée
2021-08-02 16:07   ` Bastian Koppelmann
2021-07-20 23:27 ` [PATCH v1 26/29] tests/tcg/configure.sh: add handling for assembler only builds Alex Bennée
2021-07-20 23:27 ` [PATCH v1 27/29] gitlab: enable a very minimal build with the tricore container Alex Bennée
2021-07-21  7:05   ` Thomas Huth
2021-07-21 15:00   ` Willian Rampazzo
2021-07-20 23:27 ` [PATCH v1 28/29] gitlab-ci: Remove the second superfluous macos task Alex Bennée
2021-07-20 23:27 ` [PATCH v1 29/29] gitlab-ci: Extract OpenSBI job rules to reusable section Alex Bennée

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20210720232703.10650-4-alex.bennee@linaro.org \
    --to=alex.bennee@linaro.org \
    --cc=aurelien@aurel32.net \
    --cc=berrange@redhat.com \
    --cc=crosa@redhat.com \
    --cc=f4bug@amsat.org \
    --cc=fam@euphon.net \
    --cc=mst@redhat.com \
    --cc=pbonzini@redhat.com \
    --cc=qemu-devel@nongnu.org \
    --cc=stefanha@redhat.com \
    --subject='Re: [PATCH v1 03/29] docs: add a section on the generalities of vhost-user' \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.