On Wed, Jul 07, 2021 at 07:45:49PM +0100, Alex Bennée wrote: > 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.ben...@linaro.org> > Cc: Stefan Hajnoczi <stefa...@redhat.com> > --- > docs/interop/vhost-user.rst | 4 ++- > docs/system/device-emulation.rst | 1 + > docs/system/devices/vhost-user.rst | 57 ++++++++++++++++++++++++++++++ > 3 files changed, 61 insertions(+), 1 deletion(-) > 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..f46423b6f3 100644 > --- a/docs/interop/vhost-user.rst > +++ b/docs/interop/vhost-user.rst > @@ -1,3 +1,5 @@ > +.. _vhost_user_proto: > + > =================== > Vhost-user Protocol > =================== > @@ -6,7 +8,7 @@ Vhost-user Protocol > :Licence: This work is licensed under the terms of the GNU GPL, > version 2 or later. See the COPYING file in the top-level > directory. > - > + > .. contents:: Table of Contents > > Introduction > diff --git a/docs/system/device-emulation.rst > b/docs/system/device-emulation.rst > index a0f00bc340..5aca6ed66b 100644 > --- a/docs/system/device-emulation.rst > +++ b/docs/system/device-emulation.rst > @@ -75,4 +75,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..ecb1107d4c > --- /dev/null > +++ b/docs/system/devices/vhost-user.rst > @@ -0,0 +1,57 @@ > +.. _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. The daemon > +will open a socket and *listen* for a connection from QEMU at which > +point the protocol will start its negotiation.
I suggest dropping this line because it's more complicated and possibly confusing at this point: vhost-user daemons can either listen or they can connect (i.e. QEMU is the one that listens). I think both directions were supported because they were convenient in different situations. > + > +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`` object. A reference to a ``memory-backend-file`` or ``memory-backend-memfd`` objects. (memory-backend-ram doesn't have an fd so it cannot be passed over a UNIX domain socket.) > +file-descriptor which can access this object will be passed via the > +socket as part of the protocol negotiation. > + > +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| \\ > + -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 >
signature.asc
Description: PGP signature
