From: Alex Bennée <alex.ben...@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.ben...@linaro.org>
Cc: Sergio Lopez Pascual <s...@redhat.com>
Signed-off-by: Dmitry Osipenko <dmitry.osipe...@collabora.com>
[dmitry.osipe...@collabora.com: Extended and corrected doc]
---
docs/system/devices/virtio-gpu.rst | 106 ++++++++++++++++++++++++++++-
1 file changed, 104 insertions(+), 2 deletions(-)
diff --git a/docs/system/devices/virtio-gpu.rst
b/docs/system/devices/virtio-gpu.rst
index ea3eb052df3c..664fc4000fa9 100644
--- a/docs/system/devices/virtio-gpu.rst
+++ b/docs/system/devices/virtio-gpu.rst
@@ -5,14 +5,34 @@ virtio-gpu
==========
This document explains the setup and usage of the virtio-gpu device.
-The virtio-gpu device paravirtualizes the GPU and display controller.
+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.
+
+virtio-gpu requirements
+-----------------------
Linux kernel support
---------------------
+^^^^^^^^^^^^^^^^^^^^
virtio-gpu requires a guest Linux kernel built with the
``CONFIG_DRM_VIRTIO_GPU`` option.
+Host Linux kernel requirements vary depending on a used virtio-gpu
+capabilities. See further sections for a detailed descriptions.
+
+3D acceleration
+^^^^^^^^^^^^^^^
+
+3D acceleration of a virtualized GPU is still an evolving field.
+Depending on the 3D mode you are running you may need to override
+distribution supplied libraries with more recent versions or enable
+build options. There are a number of requirements the host must meet
+to be able to be able to support guests. QEMU must be able to access the
+host's GPU and for the best performance be able to reliably share GPU
+memory with the guest. Details of 3D acceleration requirements are
+described in a further sections.
+
QEMU virtio-gpu variants
------------------------
@@ -65,8 +85,14 @@ intermediate representation is communicated to the host and
the
`virglrenderer`_ library on the host translates the intermediate
representation back to OpenGL API calls.
+By default OpenGL version on guest is limited to 4.3. In order to enable
+OpenGL 4.6 support, virtio-gpu host blobs feature (``hostmem`` and ``blob``
+fields) should be enabled. The ``hostmem`` field specifies the size of
+virtio-gpu host memory window. This is typically between 256M and 8G.
+
.. parsed-literal::
-device virtio-gpu-gl
+ -device virtio-gpu-gl,hostmem=8G,blob=true
.. _virgl: https://docs.mesa3d.org/drivers/virgl.html
.. _Gallium3D: https://www.freedesktop.org/wiki/Software/gallium/
@@ -94,6 +120,62 @@ of virtio-gpu host memory window. This is typically between
256M and 8G.
.. _drm: https://gitlab.freedesktop.org/virgl/virglrenderer/-/tree/main/src/drm
+.. list-table:: Linux Host Requirements
+ :header-rows: 1
+
+ * - Capability
+ - Kernel
+ - virglrenderer build flags
+ * - OpenGL pass-through
+ - Any Linux version compatible with QEMU if not using host blobs feature,
+ Linux 6.13+ otherwise
+ - N/A
+ * - Vulkan pass-through
+ - Linux 6.13+
+ - -Dvenus=true -Drender-server=true
+ * - AMDGPU DRM native context
+ - Linux 6.13+
+ - -Ddrm-renderers=amdgpu-experimental
+ * - Freedreno DRM native context
+ - Linux 6.4+
+ - -Ddrm-renderers=msm
+ * - Intel i915 DRM native context
+ - Linux 6.13+
+ - -Ddrm-renderers=i915-experimental `mr1384`_
+ * - Asahi DRM native context
+ - Downstream version of Asahi Linux kernel
+ - -Ddrm-renderers=asahi-experimental `mr1274`_
+
+.. _mr1384:
https://gitlab.freedesktop.org/virgl/virglrenderer/-/merge_requests/1384
+.. _mr1274:
https://gitlab.freedesktop.org/virgl/virglrenderer/-/merge_requests/1274
+
+.. list-table:: Linux Guest Requirements
+ :header-rows: 1
+
+ * - Capability
+ - Mesa Version
+ - Mesa build flags
+ * - OpenGL pass-through
+ - 16.0.0+
+ - -Dgallium-drivers=virgl
+ * - Vulkan pass-through
+ - 24.2.0+
+ - -Dvulkan-drivers=virtio
+ * - AMDGPU DRM native context
+ - 25.0.0+
+ - -Dgallium-drivers=radeonsi -Dvulkan-drivers=amd -Damdgpu-virtio=true
+ * - Freedreno DRM native context
+ - 23.1.0+
+ - -Dgallium-drivers=freedreno -Dvulkan-drivers=freedreno
+ * - Intel i915 DRM native context
+ - `mr29870`_
+ - -Dgallium-drivers=iris -Dvulkan-drivers=intel
-Dintel-virtio-experimental=true
+ * - Asahi DRM native context
+ - 24.2.0+
+ - -Dgallium-drivers=asahi -Dvulkan-drivers=asahi
+
+.. _mr29870: https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/29870
+
virtio-gpu rutabaga
-------------------
@@ -133,3 +215,23 @@ Surfaceless is the default if ``wsi`` is not specified.
.. _Wayland display passthrough: https://www.youtube.com/watch?v=OZJiHMtIQ2M
.. _gfxstream-enabled rutabaga:
https://crosvm.dev/book/appendix/rutabaga_gfx.html
.. _guest Wayland proxy: https://crosvm.dev/book/devices/wayland.html
+
+.. list-table:: Linux Host Requirements
+ :header-rows: 1
+
+ * - Capability
+ - Kernel
+ - Rutabaga build flags
+ * - Vulkan+Wayland pass-through
+ - Linux 6.13+
+ - Follow `gfxstream-enabled rutabaga`_ build instructions
+
+.. list-table:: Linux Guest Requirements
+ :header-rows: 1
+
+ * - Capability
+ - Mesa Version
+ - Mesa build flags
+ * - Vulkan pass-through
+ - 24.3.0+
+ - -Dvulkan-drivers=gfxstream
--
2.47.1
