On 2025/01/20 7:00, Dmitry Osipenko wrote:
From: Alex Bennée <alex.bennee@linaro.org>
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>
Cc: Dmitry Osipenko <dmitry.osipenko@collabora.com>
Cc: Sergio Lopez Pascual <slp@redhat.com>
Signed-off-by: Dmitry Osipenko <dmitry.osipenko@collabora.com>
[dmitry.osipenko@collabora.com: Extended and corrected doc]
---
docs/system/devices/virtio-gpu.rst | 94 ++++++++++++++++++++++++++++--
1 file changed, 88 insertions(+), 6 deletions(-)
diff --git a/docs/system/devices/virtio-gpu.rst
b/docs/system/devices/virtio-gpu.rst
index f20c60016376..79af291a9316 100644
--- a/docs/system/devices/virtio-gpu.rst
+++ b/docs/system/devices/virtio-gpu.rst
@@ -4,14 +4,96 @@
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+
+ - libvirglrenderer (>= 1.0.0, venus support)
+ * - virtio-gpu-gl (vDRM native context/AMD)
+ - Linux 6.13+
+ - libvirglrenderer (>= 1.1.0, DRM renderer support)
+ * - virtio-gpu-gl (vDRM native context/Freedreno)
+ - Linux 6.13+
+ - libvirglrenderer (>= 1.0.0, DRM renderer support)
+ * - virtio-gpu-gl (vDRM native context/Intel i915)
+ - Linux 6.13+
+ - libvirglrenderer (`mr1384`_, DRM renderer support)
+
+.. _mr1384:
https://gitlab.freedesktop.org/virgl/virglrenderer/-/merge_requests/1384
+
+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
+ - Mesa Version
+ - Mesa build 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 (vDRM native context/AMD)
+ - 25.0.0+
+ - -Dgallium-drivers=radeonsi -Dvulkan-drivers=amd -Damdgpu-virtio=true
+ * - virtio-gpu-gl (vDRM native context/Freedreno)
+ - 23.1.0+
+ - -Dgallium-drivers=freedreno -Dvulkan-drivers=freedreno
+ * - virtio-gpu-gl (vDRM native context/Intel i915)
+ - `mr29870`_
+ - -Dgallium-drivers=iris -Dvulkan-drivers=intel
-Dintel-virtio-experimental=true
+
+.. _mr29870: https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/29870
I feel the dependency information for virglrenderer and Mesa are more
suited for the Mesa documentation as they are not specific to QEMU and
potentially useful also for e.g., libkrun and crosvm.