On Mon, Oct 20, 2025 at 4:43 PM Dmitry Osipenko <[email protected]> wrote: > > From: Alex Bennée <[email protected]> > > 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 <[email protected]> > Cc: Sergio Lopez Pascual <[email protected]> > Reviewed-by: Akihiko Odaki <[email protected]> > Signed-off-by: Dmitry Osipenko <[email protected]> > [[email protected]: Extended and corrected doc] > --- > docs/system/devices/virtio-gpu.rst | 100 ++++++++++++++++++++++++++++- > 1 file changed, 97 insertions(+), 3 deletions(-) > > diff --git a/docs/system/devices/virtio-gpu.rst > b/docs/system/devices/virtio-gpu.rst > index ea3eb052df3c..3324a697013f 100644 > --- a/docs/system/devices/virtio-gpu.rst > +++ b/docs/system/devices/virtio-gpu.rst > @@ -5,14 +5,28 @@ 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. > > -Linux kernel support > --------------------- > +Linux guest kernel support > +-------------------------- > > virtio-gpu requires a guest Linux kernel built with the > ``CONFIG_DRM_VIRTIO_GPU`` option. > > +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 +79,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 +114,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 Version > + - Libvirglrenderer Version > + * - OpenGL pass-through > + - Any Linux version compatible with QEMU if not using host blobs feature, > + Linux 6.13+ otherwise > + - 0.8.2+ > + * - Vulkan pass-through > + - Linux 6.13+ > + - 1.0.0+ > + * - AMDGPU DRM native context > + - Linux 6.13+ > + - 1.1.0+ > + * - Freedreno DRM native context > + - Linux 6.4+ > + - 1.0.0+ > + * - Intel i915 DRM native context > + - Linux 6.13+ > + - `mr1384`_ > + * - Asahi DRM native context > + - `Downstream version`_ of Asahi Linux kernel > + - 1.2.0+ > + > +.. _mr1384: > https://gitlab.freedesktop.org/virgl/virglrenderer/-/merge_requests/1384 > +.. _Downstream version: https://github.com/AsahiLinux/linux > + > +.. list-table:: Linux Guest Requirements > + :header-rows: 1 > + > + * - Capability > + - Kernel Version > + - Mesa Version > + * - OpenGL pass-through > + - Any Linux version supporting virtio-gpu > + - 16.0.0+ > + * - Vulkan pass-through > + - Linux 5.16+ > + - 24.2.0+ > + * - AMDGPU DRM native context > + - Linux 6.14+ > + - 25.0.0+ > + * - Freedreno DRM native context > + - Linux 6.14+ > + - 23.1.0+ > + * - Intel i915 DRM native context > + - Linux 6.14+ > + - `mr29870`_ > + * - Asahi DRM native context > + - Linux 6.14+ > + - 24.2.0+ > + > +.. _mr29870: https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/29870 > + > virtio-gpu rutabaga > ------------------- > > @@ -133,3 +209,21 @@ 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 Version > + * - Vulkan+Wayland pass-through > + - Linux 6.13+ > + > +.. list-table:: Linux Guest Requirements > + :header-rows: 1 > + > + * - Capability > + - Kernel Version > + - Mesa Version > + * - Vulkan+Wayland pass-through > + - Linux 5.16+ > + - 24.3.0+ > -- > 2.51.0 >
Reviewed-by: Yiwei Zhang <[email protected]>
