[PATCH 0/4] virtio document cleanups (esp vhost-user)

[PATCH 0/4] virtio document cleanups (esp vhost-user)

[Alex Bennée]

These just tidy up the device emulation area to be a little more
organised as well as splitting out the VirtIO documents themselves.

Alex.

Alex Bennée (4):
  docs/system: split VirtIO devices from the rest
  docs/system: unify the naming style for VirtIO devices
  docs/system: drop vhost-user-rng docs
  docs/system: merge vhost-user-input into vhost-user-contrib

 docs/system/device-emulation.rst              | 18 ++--
 docs/system/devices/vfio-user.rst             |  2 +-
 docs/system/devices/vhost-user-input.rst      | 45 ----------
 docs/system/devices/vhost-user-rng.rst        | 41 ---------
 docs/system/devices/virtio/index.rst          | 29 +++++++
 .../devices/virtio/vhost-user-contrib.rst     | 87 +++++++++++++++++++
 .../devices/{ => virtio}/vhost-user.rst       | 22 ++---
 .../devices/{ => virtio}/virtio-gpu.rst       |  4 +-
 .../devices/{ => virtio}/virtio-pmem.rst      |  6 +-
 .../devices/{ => virtio}/virtio-snd.rst       |  2 +-
 10 files changed, 141 insertions(+), 115 deletions(-)
 delete mode 100644 docs/system/devices/vhost-user-input.rst
 delete mode 100644 docs/system/devices/vhost-user-rng.rst
 create mode 100644 docs/system/devices/virtio/index.rst
 create mode 100644 docs/system/devices/virtio/vhost-user-contrib.rst
 rename docs/system/devices/{ => virtio}/vhost-user.rst (77%)
 rename docs/system/devices/{ => virtio}/virtio-gpu.rst (99%)
 rename docs/system/devices/{ => virtio}/virtio-pmem.rst (98%)
 rename docs/system/devices/{ => virtio}/virtio-snd.rst (99%)

-- 
2.47.2

[PATCH 1/4] docs/system: split VirtIO devices from the rest

[Alex Bennée]

In an effort to tidy up our device documentation split the VirtIO docs
from the rest of the index and put the index to them at the front of
the list. Sort the remaining entries alphabetically and tweak the
references appropriately.

Add a short preface to the VirtIO section nudging users to use VirtIO
unless they specifically want a particular piece of hardware
emulation.

Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
---
 docs/system/device-emulation.rst              | 18 +++++------
 docs/system/devices/vfio-user.rst             |  2 +-
 docs/system/devices/virtio/index.rst          | 30 +++++++++++++++++++
 .../devices/{ => virtio}/vhost-user-input.rst |  0
 .../devices/{ => virtio}/vhost-user-rng.rst   |  0
 .../devices/{ => virtio}/vhost-user.rst       |  0
 .../devices/{ => virtio}/virtio-gpu.rst       |  0
 .../devices/{ => virtio}/virtio-pmem.rst      |  0
 .../devices/{ => virtio}/virtio-snd.rst       |  0
 9 files changed, 38 insertions(+), 12 deletions(-)
 create mode 100644 docs/system/devices/virtio/index.rst
 rename docs/system/devices/{ => virtio}/vhost-user-input.rst (100%)
 rename docs/system/devices/{ => virtio}/vhost-user-rng.rst (100%)
 rename docs/system/devices/{ => virtio}/vhost-user.rst (100%)
 rename docs/system/devices/{ => virtio}/virtio-gpu.rst (100%)
 rename docs/system/devices/{ => virtio}/virtio-pmem.rst (100%)
 rename docs/system/devices/{ => virtio}/virtio-snd.rst (100%)

diff --git a/docs/system/device-emulation.rst b/docs/system/device-emulation.rst
index 911381643f1..db714ad47aa 100644
--- a/docs/system/device-emulation.rst
+++ b/docs/system/device-emulation.rst
@@ -82,22 +82,18 @@ Emulated Devices
 .. toctree::
    :maxdepth: 1
 
+   devices/virtio/index.rst
+
    devices/can.rst
+   devices/canokey.rst
    devices/ccid.rst
    devices/cxl.rst
-   devices/vfio-user.rst
-   devices/ivshmem.rst
+   devices/igb.rst
    devices/ivshmem-flat.rst
+   devices/ivshmem.rst
    devices/keyboard.rst
    devices/net.rst
    devices/nvme.rst
-   devices/usb.rst
-   devices/vhost-user.rst
-   devices/virtio-gpu.rst
-   devices/virtio-pmem.rst
-   devices/virtio-snd.rst
-   devices/vhost-user-input.rst
-   devices/vhost-user-rng.rst
-   devices/canokey.rst
    devices/usb-u2f.rst
-   devices/igb.rst
+   devices/usb.rst
+   devices/vfio-user.rst
diff --git a/docs/system/devices/vfio-user.rst b/docs/system/devices/vfio-user.rst
index b6dcaa5615e..30c2215f4ea 100644
--- a/docs/system/devices/vfio-user.rst
+++ b/docs/system/devices/vfio-user.rst
@@ -6,7 +6,7 @@ vfio-user
 
 QEMU includes a ``vfio-user`` client. The ``vfio-user`` specification allows for
 implementing (PCI) devices in userspace outside of QEMU; it is similar to
-``vhost-user`` in this respect (see :doc:`vhost-user`), but can emulate arbitrary
+``vhost-user`` in this respect (see :doc:`virtio/vhost-user`), but can emulate arbitrary
 PCI devices, not just ``virtio``. Whereas ``vfio`` is handled by the host
 kernel, ``vfio-user``, while similar in implementation, is handled entirely in
 userspace.
diff --git a/docs/system/devices/virtio/index.rst b/docs/system/devices/virtio/index.rst
new file mode 100644
index 00000000000..bb44b14423e
--- /dev/null
+++ b/docs/system/devices/virtio/index.rst
@@ -0,0 +1,30 @@
+VirtIO Devices
+==============
+
+VirtIO devices are paravirtualized devices designed to be efficient to
+emulate and virtualize. Unless you are specifically trying to exercise
+a driver for some particular hardware they are the recommend device
+models to use for virtual machines.
+
+The `VirtIO specification`_ is an open standard managed by OASIS. It
+describes how a *driver* in a guest operating system interacts with
+the *device* model provided by QEMU. Multiple Operating Systems
+support drivers for VirtIO with Linux perhaps having the widest range
+of device types supported.
+
+The device implementation can either be provided wholly by QEMU, or in
+concert with the kernel (known as *vhost*). The device implementation
+can also be off-loaded to an external process via :ref:`vhost user
+<vhost_user>`.
+
+.. toctree::
+   :maxdepth: 1
+
+   virtio-gpu.rst
+   virtio-pmem.rst
+   virtio-snd.rst
+   vhost-user.rst
+   vhost-user-input.rst
+   vhost-user-rng.rst
+
+.. _VirtIO specification: https://docs.oasis-open.org/virtio/virtio/v1.3/virtio-v1.3.html
diff --git a/docs/system/devices/vhost-user-input.rst b/docs/system/devices/virtio/vhost-user-input.rst
similarity index 100%
rename from docs/system/devices/vhost-user-input.rst
rename to docs/system/devices/virtio/vhost-user-input.rst
diff --git a/docs/system/devices/vhost-user-rng.rst b/docs/system/devices/virtio/vhost-user-rng.rst
similarity index 100%
rename from docs/system/devices/vhost-user-rng.rst
rename to docs/system/devices/virtio/vhost-user-rng.rst
diff --git a/docs/system/devices/vhost-user.rst b/docs/system/devices/virtio/vhost-user.rst
similarity index 100%
rename from docs/system/devices/vhost-user.rst
rename to docs/system/devices/virtio/vhost-user.rst
diff --git a/docs/system/devices/virtio-gpu.rst b/docs/system/devices/virtio/virtio-gpu.rst
similarity index 100%
rename from docs/system/devices/virtio-gpu.rst
rename to docs/system/devices/virtio/virtio-gpu.rst
diff --git a/docs/system/devices/virtio-pmem.rst b/docs/system/devices/virtio/virtio-pmem.rst
similarity index 100%
rename from docs/system/devices/virtio-pmem.rst
rename to docs/system/devices/virtio/virtio-pmem.rst
diff --git a/docs/system/devices/virtio-snd.rst b/docs/system/devices/virtio/virtio-snd.rst
similarity index 100%
rename from docs/system/devices/virtio-snd.rst
rename to docs/system/devices/virtio/virtio-snd.rst
-- 
2.47.2

[PATCH 2/4] docs/system: unify the naming style for VirtIO devices

[Alex Bennée]

This makes the index look a little neater.

Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
---
 docs/system/devices/virtio/virtio-gpu.rst  | 2 +-
 docs/system/devices/virtio/virtio-pmem.rst | 6 ++----
 docs/system/devices/virtio/virtio-snd.rst  | 2 +-
 3 files changed, 4 insertions(+), 6 deletions(-)

diff --git a/docs/system/devices/virtio/virtio-gpu.rst b/docs/system/devices/virtio/virtio-gpu.rst
index b7eb0fc0e72..39d2fd2d21c 100644
--- a/docs/system/devices/virtio/virtio-gpu.rst
+++ b/docs/system/devices/virtio/virtio-gpu.rst
@@ -1,7 +1,7 @@
 ..
    SPDX-License-Identifier: GPL-2.0-or-later
 
-virtio-gpu
+VirtIO GPU
 ==========
 
 This document explains the setup and usage of the virtio-gpu device.
diff --git a/docs/system/devices/virtio/virtio-pmem.rst b/docs/system/devices/virtio/virtio-pmem.rst
index c82ac067315..0c24de83ec7 100644
--- a/docs/system/devices/virtio/virtio-pmem.rst
+++ b/docs/system/devices/virtio/virtio-pmem.rst
@@ -1,7 +1,5 @@
-
-===========
-virtio pmem
-===========
+VirtIO Persistent Memory
+========================
 
 This document explains the setup and usage of the virtio pmem device.
 The virtio pmem device is a paravirtualized persistent memory device
diff --git a/docs/system/devices/virtio/virtio-snd.rst b/docs/system/devices/virtio/virtio-snd.rst
index 2a9187fd701..3c797f66e03 100644
--- a/docs/system/devices/virtio/virtio-snd.rst
+++ b/docs/system/devices/virtio/virtio-snd.rst
@@ -1,4 +1,4 @@
-virtio sound
+VirtIO Sound
 ============
 
 This document explains the setup and usage of the Virtio sound device.
-- 
2.47.2

[PATCH 3/4] docs/system: drop vhost-user-rng docs

[Alex Bennée]

This is a fairly lightweight document which doesn't add much to the
general advice in vhost-user. Update the vhost-user docs to point
directly at the rust-vmm repo.

Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
---
 docs/system/devices/virtio/index.rst          |  1 -
 docs/system/devices/virtio/vhost-user-rng.rst | 41 -------------------
 docs/system/devices/virtio/vhost-user.rst     |  2 +-
 3 files changed, 1 insertion(+), 43 deletions(-)
 delete mode 100644 docs/system/devices/virtio/vhost-user-rng.rst

diff --git a/docs/system/devices/virtio/index.rst b/docs/system/devices/virtio/index.rst
index bb44b14423e..7f931737cc1 100644
--- a/docs/system/devices/virtio/index.rst
+++ b/docs/system/devices/virtio/index.rst
@@ -25,6 +25,5 @@ can also be off-loaded to an external process via :ref:`vhost user
    virtio-snd.rst
    vhost-user.rst
    vhost-user-input.rst
-   vhost-user-rng.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-rng.rst b/docs/system/devices/virtio/vhost-user-rng.rst
deleted file mode 100644
index ead14053264..00000000000
--- a/docs/system/devices/virtio/vhost-user-rng.rst
+++ /dev/null
@@ -1,41 +0,0 @@
-.. _vhost_user_rng:
-
-QEMU vhost-user-rng - RNG emulation
-===================================
-
-Background
-----------
-
-What follows builds on the material presented in vhost-user.rst - it should
-be reviewed before moving forward with the content in this file.
-
-Description
------------
-
-The vhost-user-rng device implementation was designed to work with a random
-number generator daemon such as the one found in the vhost-device crate of
-the rust-vmm project available on github [1].
-
-[1]. https://github.com/rust-vmm/vhost-device
-
-Examples
---------
-
-The daemon should be started first:
-
-::
-
-  host# vhost-device-rng --socket-path=rng.sock -c 1 -m 512 -p 1000
-
-The QEMU invocation needs to create a chardev socket the device can
-use to communicate as well as share the guests memory over a memfd.
-
-::
-
-  host# qemu-system								\
-      -chardev socket,path=$(PATH)/rng.sock,id=rng0				\
-      -device vhost-user-rng-pci,chardev=rng0					\
-      -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 bddf8df5ed5..9c9a28df380 100644
--- a/docs/system/devices/virtio/vhost-user.rst
+++ b/docs/system/devices/virtio/vhost-user.rst
@@ -45,7 +45,7 @@ platform details for what sort of virtio bus to use.
     - :ref:`vhost_user_input`
   * - vhost-user-rng
     - Entropy driver
-    - :ref:`vhost_user_rng`
+    - See https://github.com/rust-vmm/vhost-device
   * - vhost-user-scmi
     - System Control and Management Interface
     - See https://github.com/rust-vmm/vhost-device
-- 
2.47.2

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

[Alex Bennée]

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

Re: [PATCH 1/4] docs/system: split VirtIO devices from the rest

[John Levon]

On Tue, Sep 02, 2025 at 05:50:45PM +0100, Alex Bennée wrote:

> In an effort to tidy up our device documentation split the VirtIO docs
> from the rest of the index and put the index to them at the front of
> the list. Sort the remaining entries alphabetically and tweak the
> references appropriately.
> 
> Add a short preface to the VirtIO section nudging users to use VirtIO
> unless they specifically want a particular piece of hardware
> emulation.
> 
> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>

Reviewed-by: John Levon <john.levon@nutanix.com>

regards
john

Re: [PATCH 2/4] docs/system: unify the naming style for VirtIO devices

[John Levon]

On Tue, Sep 02, 2025 at 05:50:46PM +0100, Alex Bennée wrote:

> This makes the index look a little neater.
> 
> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>

Reviewed-by: John Levon <john.levon@nutanix.com>

regards
john

Re: [PATCH 3/4] docs/system: drop vhost-user-rng docs

[John Levon]

On Tue, Sep 02, 2025 at 05:50:47PM +0100, Alex Bennée wrote:

> This is a fairly lightweight document which doesn't add much to the
> general advice in vhost-user. Update the vhost-user docs to point
> directly at the rust-vmm repo.
> 
> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>

Reviewed-by: John Levon <john.levon@nutanix.com>

regards
john

Re: [PATCH 2/4] docs/system: unify the naming style for VirtIO devices

[Manos Pitsidianakis]

Hi Alex,

On Tue, Sep 2, 2025 at 7:51 PM Alex Bennée <alex.bennee@linaro.org> wrote:
>
> This makes the index look a little neater.
>
> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
> ---

The spec uses VIRTIO/Virtio/virtio but not VirtIO. A unified look is a
nice cleanup. Maybe we could use Virtio?

>  docs/system/devices/virtio/virtio-gpu.rst  | 2 +-
>  docs/system/devices/virtio/virtio-pmem.rst | 6 ++----
>  docs/system/devices/virtio/virtio-snd.rst  | 2 +-
>  3 files changed, 4 insertions(+), 6 deletions(-)
>
> diff --git a/docs/system/devices/virtio/virtio-gpu.rst b/docs/system/devices/virtio/virtio-gpu.rst
> index b7eb0fc0e72..39d2fd2d21c 100644
> --- a/docs/system/devices/virtio/virtio-gpu.rst
> +++ b/docs/system/devices/virtio/virtio-gpu.rst
> @@ -1,7 +1,7 @@
>  ..
>     SPDX-License-Identifier: GPL-2.0-or-later
>
> -virtio-gpu
> +VirtIO GPU
>  ==========
>
>  This document explains the setup and usage of the virtio-gpu device.
> diff --git a/docs/system/devices/virtio/virtio-pmem.rst b/docs/system/devices/virtio/virtio-pmem.rst
> index c82ac067315..0c24de83ec7 100644
> --- a/docs/system/devices/virtio/virtio-pmem.rst
> +++ b/docs/system/devices/virtio/virtio-pmem.rst
> @@ -1,7 +1,5 @@
> -
> -===========
> -virtio pmem
> -===========
> +VirtIO Persistent Memory
> +========================
>
>  This document explains the setup and usage of the virtio pmem device.
>  The virtio pmem device is a paravirtualized persistent memory device
> diff --git a/docs/system/devices/virtio/virtio-snd.rst b/docs/system/devices/virtio/virtio-snd.rst
> index 2a9187fd701..3c797f66e03 100644
> --- a/docs/system/devices/virtio/virtio-snd.rst
> +++ b/docs/system/devices/virtio/virtio-snd.rst
> @@ -1,4 +1,4 @@
> -virtio sound
> +VirtIO Sound
>  ============
>
>  This document explains the setup and usage of the Virtio sound device.
> --
> 2.47.2
>
>

Re: [PATCH 1/4] docs/system: split VirtIO devices from the rest

[Manos Pitsidianakis]

Reviewed-by: Manos Pitsidianakis <manos.pitsidianakis@linaro.org>

with a typo fix:


On Tue, Sep 2, 2025 at 7:51 PM Alex Bennée <alex.bennee@linaro.org> wrote:
>
> In an effort to tidy up our device documentation split the VirtIO docs
> from the rest of the index and put the index to them at the front of
> the list. Sort the remaining entries alphabetically and tweak the
> references appropriately.
>
> Add a short preface to the VirtIO section nudging users to use VirtIO
> unless they specifically want a particular piece of hardware
> emulation.
>
> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
> ---
>  docs/system/device-emulation.rst              | 18 +++++------
>  docs/system/devices/vfio-user.rst             |  2 +-
>  docs/system/devices/virtio/index.rst          | 30 +++++++++++++++++++
>  .../devices/{ => virtio}/vhost-user-input.rst |  0
>  .../devices/{ => virtio}/vhost-user-rng.rst   |  0
>  .../devices/{ => virtio}/vhost-user.rst       |  0
>  .../devices/{ => virtio}/virtio-gpu.rst       |  0
>  .../devices/{ => virtio}/virtio-pmem.rst      |  0
>  .../devices/{ => virtio}/virtio-snd.rst       |  0
>  9 files changed, 38 insertions(+), 12 deletions(-)
>  create mode 100644 docs/system/devices/virtio/index.rst
>  rename docs/system/devices/{ => virtio}/vhost-user-input.rst (100%)
>  rename docs/system/devices/{ => virtio}/vhost-user-rng.rst (100%)
>  rename docs/system/devices/{ => virtio}/vhost-user.rst (100%)
>  rename docs/system/devices/{ => virtio}/virtio-gpu.rst (100%)
>  rename docs/system/devices/{ => virtio}/virtio-pmem.rst (100%)
>  rename docs/system/devices/{ => virtio}/virtio-snd.rst (100%)
>
> diff --git a/docs/system/device-emulation.rst b/docs/system/device-emulation.rst
> index 911381643f1..db714ad47aa 100644
> --- a/docs/system/device-emulation.rst
> +++ b/docs/system/device-emulation.rst
> @@ -82,22 +82,18 @@ Emulated Devices
>  .. toctree::
>     :maxdepth: 1
>
> +   devices/virtio/index.rst
> +
>     devices/can.rst
> +   devices/canokey.rst
>     devices/ccid.rst
>     devices/cxl.rst
> -   devices/vfio-user.rst
> -   devices/ivshmem.rst
> +   devices/igb.rst
>     devices/ivshmem-flat.rst
> +   devices/ivshmem.rst
>     devices/keyboard.rst
>     devices/net.rst
>     devices/nvme.rst
> -   devices/usb.rst
> -   devices/vhost-user.rst
> -   devices/virtio-gpu.rst
> -   devices/virtio-pmem.rst
> -   devices/virtio-snd.rst
> -   devices/vhost-user-input.rst
> -   devices/vhost-user-rng.rst
> -   devices/canokey.rst
>     devices/usb-u2f.rst
> -   devices/igb.rst
> +   devices/usb.rst
> +   devices/vfio-user.rst
> diff --git a/docs/system/devices/vfio-user.rst b/docs/system/devices/vfio-user.rst
> index b6dcaa5615e..30c2215f4ea 100644
> --- a/docs/system/devices/vfio-user.rst
> +++ b/docs/system/devices/vfio-user.rst
> @@ -6,7 +6,7 @@ vfio-user
>
>  QEMU includes a ``vfio-user`` client. The ``vfio-user`` specification allows for
>  implementing (PCI) devices in userspace outside of QEMU; it is similar to
> -``vhost-user`` in this respect (see :doc:`vhost-user`), but can emulate arbitrary
> +``vhost-user`` in this respect (see :doc:`virtio/vhost-user`), but can emulate arbitrary
>  PCI devices, not just ``virtio``. Whereas ``vfio`` is handled by the host
>  kernel, ``vfio-user``, while similar in implementation, is handled entirely in
>  userspace.
> diff --git a/docs/system/devices/virtio/index.rst b/docs/system/devices/virtio/index.rst
> new file mode 100644
> index 00000000000..bb44b14423e
> --- /dev/null
> +++ b/docs/system/devices/virtio/index.rst
> @@ -0,0 +1,30 @@
> +VirtIO Devices
> +==============
> +
> +VirtIO devices are paravirtualized devices designed to be efficient to
> +emulate and virtualize. Unless you are specifically trying to exercise
> +a driver for some particular hardware they are the recommend device

s/recommend/recommended

> +models to use for virtual machines.
> +
> +The `VirtIO specification`_ is an open standard managed by OASIS. It
> +describes how a *driver* in a guest operating system interacts with
> +the *device* model provided by QEMU. Multiple Operating Systems
> +support drivers for VirtIO with Linux perhaps having the widest range
> +of device types supported.
> +
> +The device implementation can either be provided wholly by QEMU, or in
> +concert with the kernel (known as *vhost*). The device implementation
> +can also be off-loaded to an external process via :ref:`vhost user
> +<vhost_user>`.
> +
> +.. toctree::
> +   :maxdepth: 1
> +
> +   virtio-gpu.rst
> +   virtio-pmem.rst
> +   virtio-snd.rst
> +   vhost-user.rst
> +   vhost-user-input.rst
> +   vhost-user-rng.rst
> +
> +.. _VirtIO specification: https://docs.oasis-open.org/virtio/virtio/v1.3/virtio-v1.3.html
> diff --git a/docs/system/devices/vhost-user-input.rst b/docs/system/devices/virtio/vhost-user-input.rst
> similarity index 100%
> rename from docs/system/devices/vhost-user-input.rst
> rename to docs/system/devices/virtio/vhost-user-input.rst
> diff --git a/docs/system/devices/vhost-user-rng.rst b/docs/system/devices/virtio/vhost-user-rng.rst
> similarity index 100%
> rename from docs/system/devices/vhost-user-rng.rst
> rename to docs/system/devices/virtio/vhost-user-rng.rst
> diff --git a/docs/system/devices/vhost-user.rst b/docs/system/devices/virtio/vhost-user.rst
> similarity index 100%
> rename from docs/system/devices/vhost-user.rst
> rename to docs/system/devices/virtio/vhost-user.rst
> diff --git a/docs/system/devices/virtio-gpu.rst b/docs/system/devices/virtio/virtio-gpu.rst
> similarity index 100%
> rename from docs/system/devices/virtio-gpu.rst
> rename to docs/system/devices/virtio/virtio-gpu.rst
> diff --git a/docs/system/devices/virtio-pmem.rst b/docs/system/devices/virtio/virtio-pmem.rst
> similarity index 100%
> rename from docs/system/devices/virtio-pmem.rst
> rename to docs/system/devices/virtio/virtio-pmem.rst
> diff --git a/docs/system/devices/virtio-snd.rst b/docs/system/devices/virtio/virtio-snd.rst
> similarity index 100%
> rename from docs/system/devices/virtio-snd.rst
> rename to docs/system/devices/virtio/virtio-snd.rst
> --
> 2.47.2
>
>

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

[Manos Pitsidianakis]

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