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 <alex.bennee@linaro.org>
---
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
+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`
+instead which supports the wide variety of storage modes and exports a
+number of interfaces include vhost-user.
+
+.. _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
Reviewed-by: Manos Pitsidianakis <manos.pitsidianakis@linaro.org> With typo fixes: On Tue, Sep 2, 2025 at 7:51 PM Alex Bennée <alex.bennee@linaro.org> 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 <alex.bennee@linaro.org> > --- > 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 > >
© 2016 - 2025 Red Hat, Inc.