1.. _vhost_user:
2
3vhost-user back ends
4--------------------
5
6vhost-user back ends are way to service the request of VirtIO devices
7outside of QEMU itself. To do this there are a number of things
8required.
9
10vhost-user device
11=================
12
13These are simple stub devices that ensure the VirtIO device is visible
14to the guest. The code is mostly boilerplate although each device has
15a ``chardev`` option which specifies the ID of the ``--chardev``
16device that connects via a socket to the vhost-user *daemon*.
17
18Each device will have an virtio-mmio and virtio-pci variant. See your
19platform details for what sort of virtio bus to use.
20
21.. list-table:: vhost-user devices
22  :widths: 20 20 60
23  :header-rows: 1
24
25  * - Device
26    - Type
27    - Notes
28  * - vhost-user-blk
29    - Block storage
30    - See contrib/vhost-user-blk
31  * - vhost-user-fs
32    - File based storage driver
33    - See https://gitlab.com/virtio-fs/virtiofsd
34  * - vhost-user-gpio
35    - Proxy gpio pins to host
36    - See https://github.com/rust-vmm/vhost-device
37  * - vhost-user-gpu
38    - GPU driver
39    - See contrib/vhost-user-gpu
40  * - vhost-user-i2c
41    - Proxy i2c devices to host
42    - See https://github.com/rust-vmm/vhost-device
43  * - vhost-user-input
44    - Generic input driver
45    - :ref:`vhost_user_input`
46  * - vhost-user-rng
47    - Entropy driver
48    - :ref:`vhost_user_rng`
49  * - vhost-user-scmi
50    - System Control and Management Interface
51    - See https://github.com/rust-vmm/vhost-device
52  * - vhost-user-snd
53    - Audio device
54    - See https://github.com/rust-vmm/vhost-device/staging
55  * - vhost-user-scsi
56    - SCSI based storage
57    - See contrib/vhost-user-scsi
58  * - vhost-user-vsock
59    - Socket based communication
60    - See https://github.com/rust-vmm/vhost-device
61
62The referenced *daemons* are not exhaustive, any conforming backend
63implementing the device and using the vhost-user protocol should work.
64
65vhost-user-device
66^^^^^^^^^^^^^^^^^
67
68The vhost-user-device is a generic development device intended for
69expert use while developing new backends. The user needs to specify
70all the required parameters including:
71
72  - Device ``virtio-id``
73  - The ``num_vqs`` it needs and their ``vq_size``
74  - The ``config_size`` if needed
75
76.. note::
77  To prevent user confusion you cannot currently instantiate
78  vhost-user-device without first patching out::
79
80    /* Reason: stop inexperienced users confusing themselves */
81    dc->user_creatable = false;
82
83  in ``vhost-user-device.c`` and ``vhost-user-device-pci.c`` file and
84  rebuilding.
85
86vhost-user daemon
87=================
88
89This is a separate process that is connected to by QEMU via a socket
90following the :ref:`vhost_user_proto`. There are a number of daemons
91that can be built when enabled by the project although any daemon that
92meets the specification for a given device can be used.
93
94.. _shared_memory_object:
95
96Shared memory object
97====================
98
99In order for the daemon to access the VirtIO queues to process the
100requests it needs access to the guest's address space. This is
101achieved via the ``memory-backend-file``, ``memory-backend-memfd``, or
102``memory-backend-shm`` objects.
103A reference to a file-descriptor which can access this object
104will be passed via the socket as part of the protocol negotiation.
105
106Currently the shared memory object needs to match the size of the main
107system memory as defined by the ``-m`` argument.
108
109Example
110=======
111
112First start your daemon.
113
114.. parsed-literal::
115
116  $ virtio-foo --socket-path=/var/run/foo.sock $OTHER_ARGS
117
118Then you start your QEMU instance specifying the device, chardev and
119memory objects.
120
121.. parsed-literal::
122
123  $ |qemu_system| \\
124      -m 4096 \\
125      -chardev socket,id=ba1,path=/var/run/foo.sock \\
126      -device vhost-user-foo,chardev=ba1,$OTHER_ARGS \\
127      -object memory-backend-memfd,id=mem,size=4G,share=on \\
128      -numa node,memdev=mem \\
129        ...
130
131