Re: [PATCH v1 2/2] docs: add a section on the generalities of vhost-user

[Stefan Hajnoczi]

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.bennee@linaro.org>
> Cc: Stefan Hajnoczi <stefanha@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