docs/system/devices/vhost-user.rst

   1 .. _vhost_user:
   2
   3 vhost-user back ends
   4 --------------------
   5
   6 vhost-user back ends are way to service the request of VirtIO devices
   7 outside of QEMU itself. To do this there are a number of things
   8 required.
   9
  10 vhost-user device
  11 ===================
  12
  13 These are simple stub devices that ensure the VirtIO device is visible
  14 to the guest. The code is mostly boilerplate although each device has
  15 a ``chardev`` option which specifies the ID of the ``--chardev``
  16 device that connects via a socket to the vhost-user *daemon*.
  17
  18 vhost-user daemon
  19 =================
  20
  21 This is a separate process that is connected to by QEMU via a socket
  22 following the :ref:`vhost_user_proto`. There are a number of daemons
  23 that can be built when enabled by the project although any daemon that
  24 meets the specification for a given device can be used.
  25
  26 Shared memory object
  27 ====================
  28
  29 In order for the daemon to access the VirtIO queues to process the
  30 requests it needs access to the guest's address space. This is
  31 achieved via the ``memory-backend-file`` or ``memory-backend-memfd``
  32 objects. A reference to a file-descriptor which can access this object
  33 will be passed via the socket as part of the protocol negotiation.
  34
  35 Currently the shared memory object needs to match the size of the main
  36 system memory as defined by the ``-m`` argument.
  37
  38 Example
  39 =======
  40
  41 First start you daemon.
  42
  43 .. parsed-literal::
  44
  45   $ virtio-foo --socket-path=/var/run/foo.sock $OTHER_ARGS
  46
  47 The you start your QEMU instance specifying the device, chardev and
  48 memory objects.
  49
  50 .. parsed-literal::
  51
  52   $ |qemu_system| \\
  53       -m 4096 \\
  54       -chardev socket,id=ba1,path=/var/run/foo.sock \\
  55       -device vhost-user-foo,chardev=ba1,$OTHER_ARGS \\
  56       -object memory-backend-memfd,id=mem,size=4G,share=on \\
  57       -numa node,memdev=mem \\
  58         ...
  59