docs/system: virtio-gpu: Document host/guest requirements
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. Cc: Sergio Lopez Pascual <slp@redhat.com> Reviewed-by: Akihiko Odaki <akihiko.odaki@daynix.com> Acked-by: Pierre-Eric Pelloux-Prayer <pierre-eric.pelloux-prayer@amd.com> Reviewed-by: Yiwei Zhang <zzyiwei@gmail.com> Signed-off-by: Dmitry Osipenko <dmitry.osipenko@collabora.com> [dmitry.osipenko@collabora.com: Extended and corrected doc] Message-ID: <20260303151422.977399-14-dmitry.osipenko@collabora.com> Message-ID: <20260304165043.1437519-16-alex.bennee@linaro.org> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
Alex Bennée committed
Mar 4, 2026 at 16:50 UTC
13a97a1963505851d7587d3f50a317f1ad0a8fd6
1 file changed
+102
-3
docs/system/devices/virtio/virtio-gpu.rst
+102
-3
@@ -7,14 +7,28 @@ VirtIO GPU
7
==========
8
9
This document explains the setup and usage of the virtio-gpu device.
10
-The virtio-gpu device paravirtualizes the GPU and display controller.
10
+The virtio-gpu device provides a GPU and display controller
11
+paravirtualized using VirtIO. It supports a number of different modes
12
+from simple 2D displays to fully accelerated 3D graphics.
13
12
-Linux kernel support
13
---------------------
14
+Linux guest kernel support
15
+--------------------------
16
17
virtio-gpu requires a guest Linux kernel built with the
18
``CONFIG_DRM_VIRTIO_GPU`` option.
19
20
+3D acceleration
21
+---------------
22
+
23
+3D acceleration of a virtualized GPU is still an evolving field.
24
+Depending on the 3D mode you are running you may need to override
25
+distribution supplied libraries with more recent versions or enable
26
+build options. There are a number of requirements the host must meet
27
+to be able to be able to support guests. QEMU must be able to access the
28
+host's GPU and for the best performance be able to reliably share GPU
29
+memory with the guest. Details of 3D acceleration requirements are
30
+described in a further sections.
31
+
32
QEMU virtio-gpu variants
33
------------------------
34
@@ -67,8 +81,14 @@ intermediate representation is communicated to the host and the
81
`virglrenderer`_ library on the host translates the intermediate
82
representation back to OpenGL API calls.
83
84
+By default OpenGL version on guest is limited to 4.3. In order to enable
85
+OpenGL 4.6 support, virtio-gpu host blobs feature (``hostmem`` and ``blob``
86
+fields) should be enabled. The ``hostmem`` field specifies the size of
87
+virtio-gpu host memory window. This is typically between 256M and 8G.
88
+
89
.. parsed-literal::
90
-device virtio-gpu-gl
91
+ -device virtio-gpu-gl,hostmem=8G,blob=true
92
93
.. _virgl: https://docs.mesa3d.org/drivers/virgl.html
94
.. _Gallium3D: https://www.freedesktop.org/wiki/Software/gallium/
@@ -96,6 +116,67 @@ of virtio-gpu host memory window. This is typically between 256M and 8G.
116
117
.. _drm: https://gitlab.freedesktop.org/virgl/virglrenderer/-/tree/main/src/drm
118
119
+.. list-table:: Linux Host Requirements
120
+ :header-rows: 1
121
+
122
+ * - Capability
123
+ - Kernel Version
124
+ - Libvirglrenderer Version
125
+ * - OpenGL pass-through
126
+ - Any Linux version compatible with QEMU if not using host blobs feature,
127
+ Linux 6.13+ otherwise
128
+ - 0.8.2+
129
+ * - Vulkan pass-through
130
+ - Linux 6.13+
131
+ - 1.0.0+
132
+ * - AMDGPU DRM native context
133
+ - Linux 6.13+
134
+ - 1.1.0+
135
+ * - Freedreno DRM native context
136
+ - Linux 6.4+
137
+ - 1.0.0+
138
+ * - Intel i915 DRM native context
139
+ - Linux 6.13+
140
+ - 1.3.0+
141
+ * - Asahi DRM native context
142
+ - `Downstream version`_ of Asahi Linux kernel
143
+ - 1.2.0+
144
+ * - Panfrost native context
145
+ - Linux 6.13+
146
+ - 1.3.0+
147
+
148
+.. _Downstream version: https://github.com/AsahiLinux/linux
149
+
150
+.. list-table:: Linux Guest Requirements
151
+ :header-rows: 1
152
+
153
+ * - Capability
154
+ - Kernel Version
155
+ - Mesa Version
156
+ * - OpenGL pass-through
157
+ - Any Linux version supporting virtio-gpu
158
+ - 16.0.0+
159
+ * - Vulkan pass-through
160
+ - Linux 5.16+
161
+ - 24.2.0+
162
+ * - AMDGPU DRM native context
163
+ - Linux 6.14+
164
+ - 25.0.0+
165
+ * - Freedreno DRM native context
166
+ - Linux 6.14+
167
+ - 23.1.0+
168
+ * - Intel i915 DRM native context
169
+ - Linux 6.14+
170
+ - 26.1.0+
171
+ * - Asahi DRM native context
172
+ - Linux 6.14+
173
+ - 24.2.0+
174
+ * - Panfrost native context
175
+ - Linux 6.14+
176
+ - `mr36814`_
177
+
178
+.. _mr36814: https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/36814
179
+
180
virtio-gpu rutabaga
181
-------------------
182
@@ -135,3 +216,21 @@ Surfaceless is the default if ``wsi`` is not specified.
216
.. _Wayland display passthrough: https://www.youtube.com/watch?v=OZJiHMtIQ2M
217
.. _gfxstream-enabled rutabaga: https://crosvm.dev/book/appendix/rutabaga_gfx.html
218
.. _guest Wayland proxy: https://crosvm.dev/book/devices/wayland.html
219
+
220
+.. list-table:: Linux Host Requirements
221
+ :header-rows: 1
222
+
223
+ * - Capability
224
+ - Kernel Version
225
+ * - Vulkan+Wayland pass-through
226
+ - Linux 6.13+
227
+
228
+.. list-table:: Linux Guest Requirements
229
+ :header-rows: 1
230
+
231
+ * - Capability
232
+ - Kernel Version
233
+ - Mesa Version
234
+ * - Vulkan+Wayland pass-through
235
+ - Linux 5.16+
236
+ - 24.3.0+