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

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 | 107 ++++++++++++++++++++++++++++-
 1 file changed, 106 insertions(+), 1 deletion(-)

On 2025/01/27 5:11, 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 | 107 ++++++++++++++++++++++++++++-
>   1 file changed, 106 insertions(+), 1 deletion(-)
> 
> diff --git a/docs/system/devices/virtio-gpu.rst b/docs/system/devices/virtio-gpu.rst
> index ea3eb052df3c..b3db984ff2d3 100644
> --- a/docs/system/devices/virtio-gpu.rst
> +++ b/docs/system/devices/virtio-gpu.rst
> @@ -5,7 +5,9 @@ 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
>   --------------------
> @@ -13,6 +15,24 @@ Linux kernel support
>   virtio-gpu requires a guest Linux kernel built with the
>   ``CONFIG_DRM_VIRTIO_GPU`` option.
>   
> +Dependencies
> +............
> +
> +.. note::
> +  GPU virtualisation is still an evolving field. Depending on the mode
> +  you are running you may need to override distribution supplied
> +  libraries with more recent versions or enable build options.

s/virtualisation/virtualization/ for consistency with other documentations.

> +
> +  Depending on the mode there are a number of requirements the host must
> +  meet to be able to be able to support guests. For 3D acceleration QEMU
> +  must be able to access the hosts GPU and for the best performance be
> +  able to reliably share GPU memory with the guest.
> +
> +  Virtio-gpu requires a guest Linux kernel built with the
> +  ``CONFIG_DRM_VIRTIO_GPU`` option. For 3D accelerations you
> +  will need support from guest Mesa configured for whichever encapsulation
> +  you need.

This section is part of the "Linux kernel support" chapter, which used 
to describe the guest Linux kernel requirement, but this section 
discusses a broader topic that includes the host requirements and guest 
Mesa. This section needs to be re-structured.

It says "GPU virtualisation is still an evolving field", but I believe 
the main evolving field is 3D acceleration. The later parts also 
repetitively mention 3D acceleration. Instead of repeating the same 
phrase, let the reader know that this section talks about 3D 
acceleration at the beginning. It will make the section more concise and 
allows readers to skip it when they do not care 3D acceleration.

The ``CONFIG_DRM_VIRTIO_GPU`` option is already described earlier so its 
description is redundant.

> +
>   QEMU virtio-gpu variants
>   ------------------------
>   
> @@ -56,6 +76,16 @@ on typical modern Linux distributions.
>   .. _Mesa: https://www.mesa3d.org/
>   .. _SwiftShader: https://github.com/google/swiftshader
>   
> +.. list-table:: Host Requirements
> +  :header-rows: 1
> +
> +  * - Mode
> +    - Kernel
> +    - Userspace
> +  * - virtio-gpu
> +    - Framebuffer enabled

It is not clear what "framebuffer enabled" means, and it is also 
inconsistent with the host requirements tables in later sections that 
describes the Linux kernel version. Also be aware that virtio-gpu works 
effectively anywhere, not just Linux.

> +    - GTK or SDL display

It is also inconsistent with later section that describes acceleration 
backends instead of the display. virtio-gpu also works with any display 
and is not restricted to GTK or SDL.

> +
>   virtio-gpu virglrenderer
>   ------------------------
>   
> @@ -94,6 +124,61 @@ 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:: Host Requirements
> +  :header-rows: 1
> +
> +  * - Mode
> +    - Kernel
> +    - Userspace
> +  * - virtio-gpu-gl (OpenGL pass-through)

It's already in the "virtio-gpu virglrenderer" setion so you don't have 
to mention "virtio-gpu-gl" again here.

> +    - GPU enabled> +    - libvirglrenderer (virgl support)> +  * - virtio-gpu-gl (Vulkan 
pass-through)
> +    - Linux 6.13+
> +    - libvirglrenderer (>= 1.0.0, venus support)

"venus support" is a vague wording. I can guess it means it requires a 
build flag, but it's not clear for a novice.

Perhaps you may write the build flag as you did for Mesa.

> +  * - virtio-gpu-gl (vDRM native context/AMD)

The later part of documentation calls it "DRM native context", not "vDRM 
native context"; let's keep them consistent. "vDRM native context" seems 
rarely used; I could only find one example of existing literature:
https://www.collabora.com/news-and-blog/blog/2025/01/15/the-state-of-gfx-virtualization-using-virglrenderer/

Mesa has a directory named vdrm but it is mentioned in no user-facing 
documentation.

> +    - Linux 6.13+
> +    - libvirglrenderer (>= 1.1.0, DRM renderer support)
> +  * - virtio-gpu-gl (vDRM native context/Freedreno)
> +    - Linux 6.4+
> +    - libvirglrenderer (>= 1.0.0, DRM renderer support)
> +  * - virtio-gpu-gl (vDRM native context/Intel i915)
> +    - Linux 6.13+
> +    - libvirglrenderer (`mr1384`_, DRM renderer support)
> +  * - virtio-gpu-gl (vDRM native context/Asahi)
> +    - Linux 6.13+
> +    - libvirglrenderer (`mr1274`_, DRM renderer support)
> +
> +.. _mr1384: https://gitlab.freedesktop.org/virgl/virglrenderer/-/merge_requests/1384
> +.. _mr1274: https://gitlab.freedesktop.org/virgl/virglrenderer/-/merge_requests/1274
 > +> +.. list-table:: Guest Requirements
> +  :header-rows: 1
> +
> +  * - Mode
> +    - Mesa Version
> +    - Mesa build flags
> +  * - virtio-gpu-gl (OpenGL pass-through)
> +    - 20.3.0+
> +    - -Dgallium-drivers=virgl
> +  * - virtio-gpu-gl (Vulkan pass-through)
> +    - 24.2.0+
> +    - -Dvulkan-drivers=virtio
> +  * - virtio-gpu-gl (vDRM native context/AMD)
> +    - 25.0.0+
> +    - -Dgallium-drivers=radeonsi -Dvulkan-drivers=amd -Damdgpu-virtio=true
> +  * - virtio-gpu-gl (vDRM native context/Freedreno)
> +    - 23.1.0+
> +    - -Dgallium-drivers=freedreno -Dvulkan-drivers=freedreno
> +  * - virtio-gpu-gl (vDRM native context/Intel i915)
> +    - `mr29870`_
> +    - -Dgallium-drivers=iris -Dvulkan-drivers=intel -Dintel-virtio-experimental=true
> +  * - virtio-gpu-gl (vDRM native context/Asahi)
> +    - 24.2.0+
> +    - -Dgallium-drivers=asahi -Dvulkan-drivers=asahi
> +
> +.. _mr29870: https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/29870
> +
>   virtio-gpu rutabaga
>   -------------------
>   
> @@ -133,3 +218,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:: Host Requirements
> +  :header-rows: 1
> +
> +  * - Mode
> +    - Kernel
> +    - Userspace
> +  * - virtio-gpu-gl (rutabaga/gfxstream)
> +    - GPU enabled
> +    - aemu/rutabaga_gfx_ffi or vhost-user client with support

Let's omit the mention of aemu. It is a dependency of rutabaga_gfx_ffi 
and referring to dependencies of our dependencies will make the 
documentation too cluttered. Users should also see rutabaga_gfx_ffi 
needs aemu anyway in its build guide; the reference of aemu here is 
effectively redundant.

I don't see the vhost-user support in Rutabaga. Does it really exist?

> +
> +.. list-table:: Guest Requirements
> +  :header-rows: 1
> +
> +  * - Mode
> +    - Mesa Version
> +    - Mesa build flags
> +  * - virtio-gpu-gl (rutabaga/gfxstream)
> +    - 24.3.0+
> +    - -Dvulkan-drivers=gfxstream

Akihiko Odaki <akihiko.odaki@daynix.com> writes:

> On 2025/01/27 5:11, 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]
<snip>
>>   virtio-gpu rutabaga
>>   -------------------
>>   @@ -133,3 +218,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:: Host Requirements
>> +  :header-rows: 1
>> +
>> +  * - Mode
>> +    - Kernel
>> +    - Userspace
>> +  * - virtio-gpu-gl (rutabaga/gfxstream)
>> +    - GPU enabled
>> +    - aemu/rutabaga_gfx_ffi or vhost-user client with support
>
> Let's omit the mention of aemu. It is a dependency of rutabaga_gfx_ffi
> and referring to dependencies of our dependencies will make the
> documentation too cluttered. Users should also see rutabaga_gfx_ffi
> needs aemu anyway in its build guide; the reference of aemu here is
> effectively redundant.
>
> I don't see the vhost-user support in Rutabaga. Does it really exist?

vhost-device-gpu supports gfxstream although the 3D acceleration parts
of that are still WIP:

  https://github.com/rust-vmm/vhost-device/tree/main/staging/vhost-device-gpu

>
>> +
>> +.. list-table:: Guest Requirements
>> +  :header-rows: 1
>> +
>> +  * - Mode
>> +    - Mesa Version
>> +    - Mesa build flags
>> +  * - virtio-gpu-gl (rutabaga/gfxstream)
>> +    - 24.3.0+
>> +    - -Dvulkan-drivers=gfxstream