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

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

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