Reviewed-by: Manos Pitsidianakis <[email protected]> with a typo fix:
On Tue, Sep 2, 2025 at 7:51 PM Alex Bennée <[email protected]> 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 <[email protected]> > --- > 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 > >
