diff mbox series

[v10,10/10] docs/system: virtio-gpu: Document host/guest requirements

Message ID 20250310111234.145891-11-dmitry.osipenko@collabora.com (mailing list archive)
State New
Headers show
Series Support virtio-gpu DRM native context | expand

Commit Message

Dmitry Osipenko March 10, 2025, 11:12 a.m. UTC 
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(-)

Comments

Akihiko Odaki March 10, 2025, 11:35 a.m. UTC | #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+
Dmitry Osipenko March 10, 2025, 11:44 a.m. UTC | #2 
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.
diff mbox series

Patch

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+