Re: [PATCH v7 10/10] docs/system: virtio-gpu: Document host/guest requirements

[Dmitry Osipenko <dmitry.osipenko@collabora.com>]

On 2/3/25 09:04, Akihiko Odaki wrote:
> On 2025/02/03 8:21, 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 | 92 +++++++++++++++++++++++++++++-
>>   1 file changed, 91 insertions(+), 1 deletion(-)
>>
>> diff --git a/docs/system/devices/virtio-gpu.rst b/docs/system/devices/
>> virtio-gpu.rst
>> index ea3eb052df3c..56950a76aa2e 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
>>   --------------------
>> @@ -56,6 +58,17 @@ on typical modern Linux distributions.
>>   .. _Mesa: https://www.mesa3d.org/
>>   .. _SwiftShader: https://github.com/google/swiftshader
>>   +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.
>> +
> 
> What about having a bigger section for "host requirements" that includes
> the "Linux kernel support" and "3D acceleration" section?
> 
> Also it's better to note that the details of 3D acceleration
> requirements are described later as this section only contains an
> abstract description.
> 
>>   virtio-gpu virglrenderer
>>   ------------------------
>>   @@ -94,6 +107,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:: Linux Host Requirements
>> +  :header-rows: 1
>> +
>> +  * - Mode
> 
> "Mode" is not a word used elsewhere. Perhaps you may call it "capability".
> 
>> +    - Kernel
>> +    - libvirglrenderer build flags
> 
> Just "virglrenderer" for consistency.
> 
>> +  * - OpenGL pass-through
>> +    - Linux any stable version
> QEMU's support policy is different from Linux's own idea of stable
> releases. Perhaps you may refer to any Linux version compatible with QEMU.
> 
>> +    - N/A
>> +  * - Vulkan pass-through
>> +    - Linux 6.13+
>> +    - -Dvenus=true -Drender-server=true
>> +  * - AMDGPU DRM native context
>> +    - Linux 6.13+
>> +    - -Ddrm-renderers=amdgpu-experimental
>> +  * - Freedreno DRM native context
>> +    - Linux 6.4+
>> +    - -Ddrm-renderers=msm
>> +  * - Intel i915 DRM native context
>> +    - Linux 6.13+
>> +    - -Ddrm-renderers=i915-experimental `mr1384`_
>> +  * - Asahi DRM native context
>> +    - Linux 6.13+
> 
> Asahi does not need patches for virglrenderer but requires patches for
> the kernel too as the upstream kernel doesn't have the GPU support at all.
> 
>> +    - -Ddrm-renderers=asahi-experimental `mr1274`_
>> +
>> +.. _mr1384: https://gitlab.freedesktop.org/virgl/virglrenderer/-/
>> merge_requests/1384
>> +.. _mr1274: https://gitlab.freedesktop.org/virgl/virglrenderer/-/
>> merge_requests/1274
>> +
>> +.. list-table:: Linux Guest Requirements
>> +  :header-rows: 1
>> +
>> +  * - Mode
>> +    - Mesa Version
>> +    - Mesa build flags
>> +  * - OpenGL pass-through
>> +    - 16.0.0+
>> +    - -Dgallium-drivers=virgl
>> +  * - Vulkan pass-through
>> +    - 24.2.0+
>> +    - -Dvulkan-drivers=virtio
>> +  * - AMDGPU DRM native context
>> +    - 25.0.0+
>> +    - -Dgallium-drivers=radeonsi -Dvulkan-drivers=amd -Damdgpu-
>> virtio=true
>> +  * - Freedreno DRM native context
>> +    - 23.1.0+
>> +    - -Dgallium-drivers=freedreno -Dvulkan-drivers=freedreno
>> +  * - Intel i915 DRM native context
>> +    - `mr29870`_
>> +    - -Dgallium-drivers=iris -Dvulkan-drivers=intel -Dintel-virtio-
>> experimental=true
>> +  * - Asahi DRM native context
>> +    - 24.2.0+
>> +    - -Dgallium-drivers=asahi -Dvulkan-drivers=asahi
>> +
>> +.. _mr29870: https://gitlab.freedesktop.org/mesa/mesa/-/
>> merge_requests/29870
>> +
>>   virtio-gpu rutabaga
>>   -------------------
>>   @@ -133,3 +201,25 @@ 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
>> +
>> +  * - Mode
>> +    - Kernel
>> +    - Userspace
>> +  * - rutabaga-gfxstream
> 
> This notation is not consistent with the table for virglrenderer.
> Following the description of capsets will allow creating a consistent
> table.
> 
>> +    - Linux 6.13+
>> +    - rutabaga_gfx_ffi or vhost-user client with `gfxstream support`_
> 
> rutabaga_gfx_ffi is a crate name but not mentioned in other
> documentations. This page already contains a link to
> https://crosvm.dev/book/appendix/rutabaga_gfx.html so let's make it
> consistent with it.
> 
> vhost-user is irrelevant with virtio-gpu-rutabaga. Also note that QEMU
> has its own vhost-user-gpu implementation that doesn't use Rutabaga in
> contrib/vhost-user-gpu.

Thanks for the review! I applied all your suggestions for v8. If I
missed or got anything wrong, please comment on v8.

-- 
Best regards,
Dmitry