Re: [PATCH 4/4] docs/system: merge vhost-user-input into vhost-user-contrib

[Manos Pitsidianakis <manos.pitsidianakis@linaro.org>]

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
>
>