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. Reviewed-by: Manos Pitsidianakis <[email protected]> Reviewed-by: John Levon <[email protected]> Message-ID: <[email protected]> Signed-off-by: Alex Bennée <[email protected]> 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..fc457ca74c7 --- /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 recommended 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.3
