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`` or ``memory-backend-memfd`` 102objects. A reference to a file-descriptor which can access this object 103will be passed via the socket as part of the protocol negotiation. 104 105Currently the shared memory object needs to match the size of the main 106system memory as defined by the ``-m`` argument. 107 108Example 109======= 110 111First start your daemon. 112 113.. parsed-literal:: 114 115 $ virtio-foo --socket-path=/var/run/foo.sock $OTHER_ARGS 116 117Then you start your QEMU instance specifying the device, chardev and 118memory objects. 119 120.. parsed-literal:: 121 122 $ |qemu_system| \\ 123 -m 4096 \\ 124 -chardev socket,id=ba1,path=/var/run/foo.sock \\ 125 -device vhost-user-foo,chardev=ba1,$OTHER_ARGS \\ 126 -object memory-backend-memfd,id=mem,size=4G,share=on \\ 127 -numa node,memdev=mem \\ 128 ... 129 130