Reviewed-by: Manos Pitsidianakis <[email protected]> With typo fixes:
On Tue, Sep 2, 2025 at 7:51 PM Alex Bennée <[email protected]> wrote: > > We might as well group all the contrib submissions together and gently > dissuade people from using them in production. Update the references in > vhost-user to neatly refer to the storage daemon and the various > external rust backends. > > Signed-off-by: Alex Bennée <[email protected]> > --- > docs/system/devices/virtio/index.rst | 2 +- > .../devices/virtio/vhost-user-contrib.rst | 87 +++++++++++++++++++ > .../devices/virtio/vhost-user-input.rst | 45 ---------- > docs/system/devices/virtio/vhost-user.rst | 22 ++--- > docs/system/devices/virtio/virtio-gpu.rst | 2 + > 5 files changed, 101 insertions(+), 57 deletions(-) > create mode 100644 docs/system/devices/virtio/vhost-user-contrib.rst > delete mode 100644 docs/system/devices/virtio/vhost-user-input.rst > > diff --git a/docs/system/devices/virtio/index.rst > b/docs/system/devices/virtio/index.rst > index 7f931737cc1..04588fa78ab 100644 > --- a/docs/system/devices/virtio/index.rst > +++ b/docs/system/devices/virtio/index.rst > @@ -24,6 +24,6 @@ can also be off-loaded to an external process via > :ref:`vhost user > virtio-pmem.rst > virtio-snd.rst > vhost-user.rst > - vhost-user-input.rst > + vhost-user-contrib.rst > > .. _VirtIO specification: > https://docs.oasis-open.org/virtio/virtio/v1.3/virtio-v1.3.html > diff --git a/docs/system/devices/virtio/vhost-user-contrib.rst > b/docs/system/devices/virtio/vhost-user-contrib.rst > new file mode 100644 > index 00000000000..10a92c19e82 > --- /dev/null > +++ b/docs/system/devices/virtio/vhost-user-contrib.rst > @@ -0,0 +1,87 @@ > +vhost-user daemons in contrib > +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ > + > +QEMU provides a number of :ref:`vhost_user` daemons in the contrib > +directory. They were often written when vhost-user was initially added > +to the code base. You should also consider if other vhost-user daemons > +such as those from the rust-vmm `vhost-device repository`_ are better > +suited for production use. > + > +.. _vhost-device repository: https://github.com/rust-vmm/vhost-device > + > +.. _vhost_user_block: > + > +vhost-user-block - block device > +=============================== > + > +vhost-user-block is a backed for exposing block devices. It can s/backed/backend > +present a flat file or block device as a simple block device to the > +guest. You almost certainly want to use the :ref:`storage-daemon` s/the// ? > +instead which supports the wide variety of storage modes and exports a s/the/a/ > +number of interfaces include vhost-user. s/include/including > + > +.. _vhost_user_gpu: > + > +vhost-user-gpu - gpu device > +=========================== > + > +vhost-user-gpu presents a paravirtualized GPU and display controller. > +You probably want to use the internal :ref:`virtio_gpu` implementation > +if you want the latest features. There is also a `vhost_device_gpu`_ > +daemon as part of the rust-vmm project. > + > +.. _vhost_device_gpu: > https://github.com/rust-vmm/vhost-device/tree/main/vhost-device-gpu > + > +.. _vhost_user_input: > + > +vhost-user-input - Input emulation > +================================== > + > +The Virtio input device is a paravirtualized device for input events. > + > +Description > +----------- > + > +The vhost-user-input device implementation was designed to work with a daemon > +polling on input devices and passes input events to the guest. > + > +QEMU provides a backend implementation in contrib/vhost-user-input. > + > +Linux kernel support > +-------------------- > + > +Virtio input requires a guest Linux kernel built with the > +``CONFIG_VIRTIO_INPUT`` option. > + > +Examples > +-------- > + > +The backend daemon should be started first: > + > +:: > + > + host# vhost-user-input --socket-path=input.sock \ > + --evdev-path=/dev/input/event17 > + > +The QEMU invocation needs to create a chardev socket to communicate with the > +backend daemon and access the VirtIO queues with the guest over the > +:ref:`shared memory <shared_memory_object>`. > + > +:: > + > + host# qemu-system > \ > + -chardev socket,path=/tmp/input.sock,id=mouse0 > \ > + -device vhost-user-input-pci,chardev=mouse0 > \ > + -m 4096 > \ > + -object memory-backend-file,id=mem,size=4G,mem-path=/dev/shm,share=on > \ > + -numa node,memdev=mem > \ > + ... > + > + > +.. _vhost_user_scsi: > + > +vhost-user-scsi - SCSI controller > +================================= > + > +The vhost-user-scsi daemon can proxy iSCSI devices onto a virtualized > +SCSI controller. > diff --git a/docs/system/devices/virtio/vhost-user-input.rst > b/docs/system/devices/virtio/vhost-user-input.rst > deleted file mode 100644 > index 118eb78101c..00000000000 > --- a/docs/system/devices/virtio/vhost-user-input.rst > +++ /dev/null > @@ -1,45 +0,0 @@ > -.. _vhost_user_input: > - > -QEMU vhost-user-input - Input emulation > -======================================= > - > -This document describes the setup and usage of the Virtio input device. > -The Virtio input device is a paravirtualized device for input events. > - > -Description > ------------ > - > -The vhost-user-input device implementation was designed to work with a daemon > -polling on input devices and passes input events to the guest. > - > -QEMU provides a backend implementation in contrib/vhost-user-input. > - > -Linux kernel support > --------------------- > - > -Virtio input requires a guest Linux kernel built with the > -``CONFIG_VIRTIO_INPUT`` option. > - > -Examples > --------- > - > -The backend daemon should be started first: > - > -:: > - > - host# vhost-user-input --socket-path=input.sock \ > - --evdev-path=/dev/input/event17 > - > -The QEMU invocation needs to create a chardev socket to communicate with the > -backend daemon and access the VirtIO queues with the guest over the > -:ref:`shared memory <shared_memory_object>`. > - > -:: > - > - host# qemu-system > \ > - -chardev socket,path=/tmp/input.sock,id=mouse0 > \ > - -device vhost-user-input-pci,chardev=mouse0 > \ > - -m 4096 > \ > - -object memory-backend-file,id=mem,size=4G,mem-path=/dev/shm,share=on > \ > - -numa node,memdev=mem > \ > - ... > diff --git a/docs/system/devices/virtio/vhost-user.rst > b/docs/system/devices/virtio/vhost-user.rst > index 9c9a28df380..f556a840e99 100644 > --- a/docs/system/devices/virtio/vhost-user.rst > +++ b/docs/system/devices/virtio/vhost-user.rst > @@ -27,37 +27,37 @@ platform details for what sort of virtio bus to use. > - Notes > * - vhost-user-blk > - Block storage > - - See contrib/vhost-user-blk > + - :ref:`storage-daemon` > * - vhost-user-fs > - File based storage driver > - - See https://gitlab.com/virtio-fs/virtiofsd > + - `virtiofsd <https://gitlab.com/virtio-fs/virtiofsd>`_ > * - vhost-user-gpio > - Proxy gpio pins to host > - - See https://github.com/rust-vmm/vhost-device > + - `vhost-device-gpio > <https://github.com/rust-vmm/vhost-device/tree/main/vhost-device-gpio>`_ > * - vhost-user-gpu > - GPU driver > - - See contrib/vhost-user-gpu > + - `vhost-device-gpu > <https://github.com/rust-vmm/vhost-device/tree/main/vhost-device-gpu>`_ or > :ref:`vhost_user_gpu` > * - vhost-user-i2c > - Proxy i2c devices to host > - - See https://github.com/rust-vmm/vhost-device > + - `vhost-device-i2c > <https://github.com/rust-vmm/vhost-device/tree/main/vhost-device-i2c>`_ > * - vhost-user-input > - Generic input driver > - - :ref:`vhost_user_input` > + - `vhost-device-input > <https://github.com/rust-vmm/vhost-device/tree/main/vhost-device-input>`_ or > :ref:`vhost_user_input` > * - vhost-user-rng > - Entropy driver > - - See https://github.com/rust-vmm/vhost-device > + - `vhost-device-rng > <https://github.com/rust-vmm/vhost-device/tree/main/vhost-device-rng>`_ > * - vhost-user-scmi > - System Control and Management Interface > - - See https://github.com/rust-vmm/vhost-device > + - `vhost-device-scmi > <https://github.com/rust-vmm/vhost-device/tree/main/vhost-device-scmi>`_ > * - vhost-user-snd > - Audio device > - - See https://github.com/rust-vmm/vhost-device/staging > + - `vhost-device-sound > <https://github.com/rust-vmm/vhost-device/tree/main/vhost-device-sound>`_ > * - vhost-user-scsi > - SCSI based storage > - - See contrib/vhost-user-scsi > + - :ref:`vhost_user_scsi` > * - vhost-user-vsock > - Socket based communication > - - See https://github.com/rust-vmm/vhost-device > + - `vhost-device-vsock > <https://github.com/rust-vmm/vhost-device/tree/main/vhost-device-vsock>`_ > > The referenced *daemons* are not exhaustive, any conforming backend > implementing the device and using the vhost-user protocol should work. > diff --git a/docs/system/devices/virtio/virtio-gpu.rst > b/docs/system/devices/virtio/virtio-gpu.rst > index 39d2fd2d21c..0f4bb304a9b 100644 > --- a/docs/system/devices/virtio/virtio-gpu.rst > +++ b/docs/system/devices/virtio/virtio-gpu.rst > @@ -1,6 +1,8 @@ > .. > SPDX-License-Identifier: GPL-2.0-or-later > > +.. _virtio_gpu: > + > VirtIO GPU > ========== > > -- > 2.47.2 > >
