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: 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, 91 insertions(+), 3 deletions(-)
diff --git a/docs/system/devices/virtio-gpu.rst b/docs/system/devices/virtio-gpu.rst
index ea3eb052df3c..3e4a1e2c87a0 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,56 @@ 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
+ * - OpenGL pass-through
+ - Any Linux version compatible with QEMU if not using host blobs feature,
+ Linux 6.13+ otherwise
+ * - Vulkan pass-through
+ - Linux 6.13+
+ * - AMDGPU DRM native context
+ - Linux 6.13+
+ * - Freedreno DRM native context
+ - Linux 6.4+
+ * - Intel i915 DRM native context `mr1384`_
+ - Linux 6.13+
+ * - Asahi DRM native context `mr1274`_
+ - `Downstream version`_ of Asahi Linux kernel
+
+.. _mr1384: https://gitlab.freedesktop.org/virgl/virglrenderer/-/merge_requests/1384
+.. _mr1274: https://gitlab.freedesktop.org/virgl/virglrenderer/-/merge_requests/1274
+.. _Downstream version: https://gitlab.freedesktop.org/asahi/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 +203,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.48.1
On 2025/03/10 20:12, 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: 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, 91 insertions(+), 3 deletions(-) > > diff --git a/docs/system/devices/virtio-gpu.rst b/docs/system/devices/virtio-gpu.rst > index ea3eb052df3c..3e4a1e2c87a0 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,56 @@ 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 > + * - OpenGL pass-through > + - Any Linux version compatible with QEMU if not using host blobs feature, > + Linux 6.13+ otherwise > + * - Vulkan pass-through > + - Linux 6.13+ > + * - AMDGPU DRM native context > + - Linux 6.13+ > + * - Freedreno DRM native context > + - Linux 6.4+ > + * - Intel i915 DRM native context `mr1384`_ > + - Linux 6.13+ > + * - Asahi DRM native context `mr1274`_ > + - `Downstream version`_ of Asahi Linux kernel > + > +.. _mr1384: https://gitlab.freedesktop.org/virgl/virglrenderer/-/merge_requests/1384 > +.. _mr1274: https://gitlab.freedesktop.org/virgl/virglrenderer/-/merge_requests/1274 These links to virglrenderer merge requests are nice additions. It's better to have a column for virglrenderer like the "Mesa Version" column in the "Linux Guest Requirements" table. > +.. _Downstream version: https://gitlab.freedesktop.org/asahi/linux I think you want to refer to: https://github.com/AsahiLinux/linux The linked repository of Asahi says it had a last update a year ago. The repository on GitHub is updated 4 days ago so it's newer. > + > +.. 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 +203,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+
On 3/10/25 14:35, Akihiko Odaki wrote: > On 2025/03/10 20:12, 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: 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, 91 insertions(+), 3 deletions(-) >> >> diff --git a/docs/system/devices/virtio-gpu.rst b/docs/system/devices/ >> virtio-gpu.rst >> index ea3eb052df3c..3e4a1e2c87a0 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,56 @@ 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 >> + * - OpenGL pass-through >> + - Any Linux version compatible with QEMU if not using host blobs >> feature, >> + Linux 6.13+ otherwise >> + * - Vulkan pass-through >> + - Linux 6.13+ >> + * - AMDGPU DRM native context >> + - Linux 6.13+ >> + * - Freedreno DRM native context >> + - Linux 6.4+ >> + * - Intel i915 DRM native context `mr1384`_ >> + - Linux 6.13+ >> + * - Asahi DRM native context `mr1274`_ >> + - `Downstream version`_ of Asahi Linux kernel >> + >> +.. _mr1384: https://gitlab.freedesktop.org/virgl/virglrenderer/-/ >> merge_requests/1384 >> +.. _mr1274: https://gitlab.freedesktop.org/virgl/virglrenderer/-/ >> merge_requests/1274 > > These links to virglrenderer merge requests are nice additions. It's > better to have a column for virglrenderer like the "Mesa Version" column > in the "Linux Guest Requirements" table. Ack >> +.. _Downstream version: https://gitlab.freedesktop.org/asahi/linux > > I think you want to refer to: https://github.com/AsahiLinux/linux > The linked repository of Asahi says it had a last update a year ago. > The repository on GitHub is updated 4 days ago so it's newer. That's why I wasn't adding links to Asahi, it's odd and non-upstream :) Will change the link. -- Best regards, Dmitry
© 2016 - 2025 Red Hat, Inc.