diff mbox series

[RFC] docs/system: expand the virtio-gpu documentation

Message ID 20250114182221.840349-1-alex.bennee@linaro.org
State New
Headers show
Series [RFC] docs/system: expand the virtio-gpu documentation | expand

Commit Message

Alex Bennée Jan. 14, 2025, 6:22 p.m. UTC 
This attempts to tidy up the VirtIO GPU documentation to make the list
of requirements clearer. There are still a lot of moving parts and the
distros have some catching up to do before this is all handled
automatically.

Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
Based-on: 20241110221838.2241356-1-dmitry.osipenko@collabora.com
Cc: Dmitry Osipenko <dmitry.osipenko@collabora.com>
Cc: Sergio Lopez Pascual <slp@redhat.com>

---
Dimitry, feel free to merge or adapt this incomplete RFC into v5
---
 docs/system/devices/virtio-gpu.rst | 89 ++++++++++++++++++++++++++++--
 1 file changed, 83 insertions(+), 6 deletions(-)
diff mbox series

Patch

diff --git a/docs/system/devices/virtio-gpu.rst b/docs/system/devices/virtio-gpu.rst
index f20c600163..6226fb732e 100644
--- a/docs/system/devices/virtio-gpu.rst
+++ b/docs/system/devices/virtio-gpu.rst
@@ -4,14 +4,91 @@ 
 virtio-gpu
 ==========
 
-This document explains the setup and usage of the virtio-gpu device.
-The virtio-gpu device paravirtualizes the GPU and display controller.
-
-Linux kernel support
---------------------
+The virtio-gpu device provides a GPU and display controller
+paravirtualized using VirtIO. It supports a number of different modes
+from simple 2D displays to fully accelerated 3D graphics.
+
+Dependencies
+............
+
+.. note::
+  GPU virtualisation is still an evolving field. Depending on the mode
+  you are running you may need to override distribution supplied
+  libraries with more recent versions or enable build options.
+
+Host requirements
+-----------------
+
+Depending on the mode there are a number of requirements the host must
+meet to be able to be able to support guests. For 3D acceleration QEMU
+must be able to access the hosts GPU and for the best performance be
+able to reliably share GPU memory with the guest.
+
+.. list-table:: Host Requirements
+  :header-rows: 1
+
+  * - Mode
+    - Kernel
+    - Userspace
+  * - virtio-gpu
+    - framebuffer enabled
+    - GTK or SDL display
+  * - virtio-gpu-gl (OpenGL pass-through)
+    - GPU enabled
+    - libvirglrenderer (virgl support)
+  * - virtio-gpu-gl (rutabaga/gfxstream)
+    - GPU enabled
+    - aemu/rutabaga_gfx_ffi or vhost-user client with support
+  * - virtio-gpu-gl (Vulkan pass-through)
+    - Linux 6.13, CONFIG_UDMA
+    - libvirglrenderer (>= 1.1.0, venus support)
+  * - virtio-gpu-gl (Native Context)
+    - Linux 6.13, CONFIG_UDMA
+    - libvirglrenderer (master, possibly with patches)
+
+
+Guest requirements
+------------------
 
 virtio-gpu requires a guest Linux kernel built with the
-``CONFIG_DRM_VIRTIO_GPU`` option.
+``CONFIG_DRM_VIRTIO_GPU`` option. Otherwise for 3D accelerations you
+will need support from Mesa configured for whichever encapsulation you
+need.
+
+.. list-table:: Guest Requirements
+  :header-rows: 1
+
+  * - Mode
+    - Min Mesa Version
+    - Mesa flags
+  * - virtio-gpu
+    - n/a
+    - n/a
+  * - virtio-gpu-gl (OpenGL pass-through)
+    - 20.3.0+
+    - -Dgallium-drivers=virgl
+  * - virtio-gpu-gl (rutabaga/gfxstream)
+    - 24.3.0+
+    - -Dvulkan-drivers=gfxstream
+  * - virtio-gpu-gl (Vulkan pass-through)
+    - 24.2+
+    - -Dvulkan-drivers=virtio
+  * - virtio-gpu-gl (Native Context/Freedreno)
+    - master
+    - ?
+  * - virtio-gpu-gl (Native Context/Intel)
+    - `mr29870`_
+    - -Dvulkan-drivers=iris -Dintel-virtio-experimental=true
+  * - virtio-gpu-gl (Native Context/AMD)
+    - `mr21658`_
+    - -Dvulkan-drivers=radeonsi
+
+.. _mr29870: https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/29870
+.. _mr21658: https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/21658
+      
+Further information
+...................
+
 
 QEMU virtio-gpu variants
 ------------------------