[v5,8/8] docs/system: Expand the virtio-gpu documentation

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: Dmitry Osipenko <dmitry.osipenko@collabora.com>
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, 88 insertions(+), 6 deletions(-)

On 2025/01/20 21:23, Alex Bennée wrote:
> Akihiko Odaki <akihiko.odaki@daynix.com> writes:
> 
>> On 2025/01/20 7:00, 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: Dmitry Osipenko <dmitry.osipenko@collabora.com>
>>> 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, 88 insertions(+), 6 deletions(-)
>>> diff --git a/docs/system/devices/virtio-gpu.rst
>>> b/docs/system/devices/virtio-gpu.rst
>>> index f20c60016376..79af291a9316 100644
>>> --- a/docs/system/devices/virtio-gpu.rst
>>> +++ b/docs/system/devices/virtio-gpu.rst
>>> @@ -4,14 +4,96 @@
>>>    virtio-gpu
>>>    ==========
>>>    -This document explains the setup and usage of the virtio-gpu
>>> device.
>>> -The virtio-gpu device paravirtualizes the GPU and display controller.
>>> -
>>> -Linux kernel support
>>> ---------------------
>>> +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.
>>> +
>>> +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.
>>> +
>>> +Host requirements
>>> +-----------------
>>> +
>>> +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.
>>> +
>>> +.. list-table:: Host Requirements
>>> +  :header-rows: 1
>>> +
>>> +  * - Mode
>>> +    - Kernel
>>> +    - Userspace
>>> +  * - virtio-gpu
>>> +    - framebuffer enabled
>>> +    - GTK or SDL display
>>> +  * - virtio-gpu-gl (OpenGL pass-through)
>>> +    - GPU enabled
>>> +    - libvirglrenderer (virgl support)
>>> +  * - virtio-gpu-gl (rutabaga/gfxstream)
>>> +    - GPU enabled
>>> +    - aemu/rutabaga_gfx_ffi or vhost-user client with support
>>> +  * - virtio-gpu-gl (Vulkan pass-through)
>>> +    - Linux 6.13+
>>> +    - libvirglrenderer (>= 1.0.0, venus support)
>>> +  * - virtio-gpu-gl (vDRM native context/AMD)
>>> +    - Linux 6.13+
>>> +    - libvirglrenderer (>= 1.1.0, DRM renderer support)
>>> +  * - virtio-gpu-gl (vDRM native context/Freedreno)
>>> +    - Linux 6.13+
>>> +    - libvirglrenderer (>= 1.0.0, DRM renderer support)
>>> +  * - virtio-gpu-gl (vDRM native context/Intel i915)
>>> +    - Linux 6.13+
>>> +    - libvirglrenderer (`mr1384`_, DRM renderer support)
>>> +
>>> +.. _mr1384: https://gitlab.freedesktop.org/virgl/virglrenderer/-/merge_requests/1384
>>> +
>>> +Guest requirements
>>> +------------------
>>>      virtio-gpu requires a guest Linux kernel built with the
>>> -``CONFIG_DRM_VIRTIO_GPU`` option.
>>> +``CONFIG_DRM_VIRTIO_GPU`` option. Otherwise for 3D accelerations you
>>> +will need support from Mesa configured for whichever encapsulation you
>>> +need.
>>> +
>>> +.. list-table:: Guest Requirements
>>> +  :header-rows: 1
>>> +
>>> +  * - Mode
>>> +    - Mesa Version
>>> +    - Mesa build flags
>>> +  * - virtio-gpu
>>> +    - n/a
>>> +    - n/a
>>> +  * - virtio-gpu-gl (OpenGL pass-through)
>>> +    - 20.3.0+
>>> +    - -Dgallium-drivers=virgl
>>> +  * - virtio-gpu-gl (rutabaga/gfxstream)
>>> +    - 24.3.0+
>>> +    - -Dvulkan-drivers=gfxstream
>>> +  * - virtio-gpu-gl (Vulkan pass-through)
>>> +    - 24.2+
>>> +    - -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
>>> +
>>> +.. _mr29870: https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/29870
>>
>> I feel the dependency information for virglrenderer and Mesa are more
>> suited for the Mesa documentation as they are not specific to QEMU and
>> potentially useful also for e.g., libkrun and crosvm.
> 
> I think while everything is in so much flux it doesn't hurt to include
> in our docs. I don't know if mesa currently has a dedicated page for GPU
> virtualisation.

Mesa has pages for VirGL and Venus, which can be linked from the 
respective parts of this documentation. gfxstream is not documented but 
I think most people will use it only for Android anyway. A documentation 
for DRM native context will be a nice addition for Mesa. I will not 
object if you put this information to QEMU documentation though.

> 
> 
>>
>>> +
>>> +Further information
>>> +...................
>>
>> I'm not sure about putting the below sections behind "Further
>> information". Anyone who want to use this feature will need to know
>> the command line described below.
>>
>>>      QEMU virtio-gpu variants
>>>    ------------------------
>

On 1/21/25 07:26, Akihiko Odaki wrote:
...
>>> I feel the dependency information for virglrenderer and Mesa are more
>>> suited for the Mesa documentation as they are not specific to QEMU and
>>> potentially useful also for e.g., libkrun and crosvm.
>>
>> I think while everything is in so much flux it doesn't hurt to include
>> in our docs. I don't know if mesa currently has a dedicated page for GPU
>> virtualisation.
> 
> Mesa has pages for VirGL and Venus, which can be linked from the
> respective parts of this documentation. gfxstream is not documented but
> I think most people will use it only for Android anyway. A documentation
> for DRM native context will be a nice addition for Mesa. I will not
> object if you put this information to QEMU documentation though.

Adding native context doc to Mesa indeed will be a good move, as well as
adding links to the Mesa virgl/venus pages in QEMU.

RE requirements documentation, it's also a valid point that stuff like
build flags should belong to the relevant projects. On the other hand,
it's a common headache for a newcoming people to figure everything out
from scratch and having more centralized documentation helps. The build
requirements aren't cleanly documented anywhere AFAICT, and the
requirements also differ based on VMM. I'll update and keep this patch
in v6, the requirements info should stay actual for a next couple years
IMO. Let's discuss it further in v6 if more objections will arise.

On 2025/01/27 3:06, Dmitry Osipenko wrote:
> On 1/21/25 07:26, Akihiko Odaki wrote:
> ...
>>>> I feel the dependency information for virglrenderer and Mesa are more
>>>> suited for the Mesa documentation as they are not specific to QEMU and
>>>> potentially useful also for e.g., libkrun and crosvm.
>>>
>>> I think while everything is in so much flux it doesn't hurt to include
>>> in our docs. I don't know if mesa currently has a dedicated page for GPU
>>> virtualisation.
>>
>> Mesa has pages for VirGL and Venus, which can be linked from the
>> respective parts of this documentation. gfxstream is not documented but
>> I think most people will use it only for Android anyway. A documentation
>> for DRM native context will be a nice addition for Mesa. I will not
>> object if you put this information to QEMU documentation though.
> 
> Adding native context doc to Mesa indeed will be a good move, as well as
> adding links to the Mesa virgl/venus pages in QEMU.
> 
> RE requirements documentation, it's also a valid point that stuff like
> build flags should belong to the relevant projects. On the other hand,
> it's a common headache for a newcoming people to figure everything out
> from scratch and having more centralized documentation helps. The build
> requirements aren't cleanly documented anywhere AFAICT, and the
> requirements also differ based on VMM. I'll update and keep this patch
> in v6, the requirements info should stay actual for a next couple years
> IMO. Let's discuss it further in v6 if more objections will arise.
> 

I think it's fine to require one click to reach the relevant documentation.

How do the requirements described here vary with VMM?

I'm not entirely sure the documentation will stay as is for that long. 
The requirements of Intel native context refer to merge requests that 
can be merged sooner or later. Asahi may need more updates if you 
document it too because its DRM ABI is still unstable.

On 1/27/25 07:57, Akihiko Odaki wrote:
> On 2025/01/27 3:06, Dmitry Osipenko wrote:
>> On 1/21/25 07:26, Akihiko Odaki wrote:
>> ...
>>>>> I feel the dependency information for virglrenderer and Mesa are more
>>>>> suited for the Mesa documentation as they are not specific to QEMU and
>>>>> potentially useful also for e.g., libkrun and crosvm.
>>>>
>>>> I think while everything is in so much flux it doesn't hurt to include
>>>> in our docs. I don't know if mesa currently has a dedicated page for
>>>> GPU
>>>> virtualisation.
>>>
>>> Mesa has pages for VirGL and Venus, which can be linked from the
>>> respective parts of this documentation. gfxstream is not documented but
>>> I think most people will use it only for Android anyway. A documentation
>>> for DRM native context will be a nice addition for Mesa. I will not
>>> object if you put this information to QEMU documentation though.
>>
>> Adding native context doc to Mesa indeed will be a good move, as well as
>> adding links to the Mesa virgl/venus pages in QEMU.
>>
>> RE requirements documentation, it's also a valid point that stuff like
>> build flags should belong to the relevant projects. On the other hand,
>> it's a common headache for a newcoming people to figure everything out
>> from scratch and having more centralized documentation helps. The build
>> requirements aren't cleanly documented anywhere AFAICT, and the
>> requirements also differ based on VMM. I'll update and keep this patch
>> in v6, the requirements info should stay actual for a next couple years
>> IMO. Let's discuss it further in v6 if more objections will arise.
>>
> 
> I think it's fine to require one click to reach the relevant documentation.
> 
> How do the requirements described here vary with VMM?

Requirements don't vary much. For example virglrenderer minigbm support
is mandatory for crosvm, while for QEMU it's not.

> I'm not entirely sure the documentation will stay as is for that long.
> The requirements of Intel native context refer to merge requests that
> can be merged sooner or later. Asahi may need more updates if you
> document it too because its DRM ABI is still unstable.

The unstable parts of course will need to be updated sooner, but the
stable should be solid for years. I expect that about a year later
requirements will need to be revisited.

On 2025/02/03 7:08, Dmitry Osipenko wrote:
> On 1/27/25 07:57, Akihiko Odaki wrote:
>> On 2025/01/27 3:06, Dmitry Osipenko wrote:
>>> On 1/21/25 07:26, Akihiko Odaki wrote:
>>> ...
>>>>>> I feel the dependency information for virglrenderer and Mesa are more
>>>>>> suited for the Mesa documentation as they are not specific to QEMU and
>>>>>> potentially useful also for e.g., libkrun and crosvm.
>>>>>
>>>>> I think while everything is in so much flux it doesn't hurt to include
>>>>> in our docs. I don't know if mesa currently has a dedicated page for
>>>>> GPU
>>>>> virtualisation.
>>>>
>>>> Mesa has pages for VirGL and Venus, which can be linked from the
>>>> respective parts of this documentation. gfxstream is not documented but
>>>> I think most people will use it only for Android anyway. A documentation
>>>> for DRM native context will be a nice addition for Mesa. I will not
>>>> object if you put this information to QEMU documentation though.
>>>
>>> Adding native context doc to Mesa indeed will be a good move, as well as
>>> adding links to the Mesa virgl/venus pages in QEMU.
>>>
>>> RE requirements documentation, it's also a valid point that stuff like
>>> build flags should belong to the relevant projects. On the other hand,
>>> it's a common headache for a newcoming people to figure everything out
>>> from scratch and having more centralized documentation helps. The build
>>> requirements aren't cleanly documented anywhere AFAICT, and the
>>> requirements also differ based on VMM. I'll update and keep this patch
>>> in v6, the requirements info should stay actual for a next couple years
>>> IMO. Let's discuss it further in v6 if more objections will arise.
>>>
>>
>> I think it's fine to require one click to reach the relevant documentation.
>>
>> How do the requirements described here vary with VMM?
> 
> Requirements don't vary much. For example virglrenderer minigbm support
> is mandatory for crosvm, while for QEMU it's not.

Is that true? It seems that virglrenderer uses builds without minigbm 
support to run tests on GitLab CI.

Anyway, if there is any variance in the build procedure, that may 
justify having a separate build instruction in QEMU tree to avoid 
confusion. Otherwise, it's better to have a documentation shared with 
other VMMs.

> 
>> I'm not entirely sure the documentation will stay as is for that long.
>> The requirements of Intel native context refer to merge requests that
>> can be merged sooner or later. Asahi may need more updates if you
>> document it too because its DRM ABI is still unstable.
> 
> The unstable parts of course will need to be updated sooner, but the
> stable should be solid for years. I expect that about a year later
> requirements will need to be revisited.
> 

It will be some burden in the future. Now you are adding this 
documentation just for QEMU, but crosvm and libkrun may gain similar 
documentation. The DRM native context support for Intel and Asahi is in 
development, and I guess nvk will support it someday.

So, a very rough estimation of future documentation updates will be:
(number of VMMs) * (number of DRM native contexts in development)
= 3 * 3
= 9

That's manageable but suboptimal.

Regards,
Akihiko Odaki

On 2/3/25 08:31, Akihiko Odaki wrote:
...
>> Requirements don't vary much. For example virglrenderer minigbm support
>> is mandatory for crosvm, while for QEMU it's not.
> 
> Is that true? It seems that virglrenderer uses builds without minigbm
> support to run tests on GitLab CI.

CI is running in a headless mode using software renderer. For a
full-featured crosvm support running on a baremetal, minigbm should be
needed, along with other downstream features.

> Anyway, if there is any variance in the build procedure, that may
> justify having a separate build instruction in QEMU tree to avoid
> confusion. Otherwise, it's better to have a documentation shared with
> other VMMs.
> 
>>
>>> I'm not entirely sure the documentation will stay as is for that long.
>>> The requirements of Intel native context refer to merge requests that
>>> can be merged sooner or later. Asahi may need more updates if you
>>> document it too because its DRM ABI is still unstable.
>>
>> The unstable parts of course will need to be updated sooner, but the
>> stable should be solid for years. I expect that about a year later
>> requirements will need to be revisited.
>>
> 
> It will be some burden in the future. Now you are adding this
> documentation just for QEMU, but crosvm and libkrun may gain similar
> documentation. The DRM native context support for Intel and Asahi is in
> development, and I guess nvk will support it someday.
> 
> So, a very rough estimation of future documentation updates will be:
> (number of VMMs) * (number of DRM native contexts in development)
> = 3 * 3
> = 9
> 
> That's manageable but suboptimal.

I don't mind deferring the doc addition if that's preferred. Either way
is fine with me. Yet it's better to have doc than not.

In my view crosvm and libkrun exist separately from QEMU, they serve a
different purpose. Majority of QEMU users likely never heard about those
other VMMs. A unified doc won't be a worthwhile effort, IMO.

On 2025/02/06 2:40, Dmitry Osipenko wrote:
> On 2/3/25 08:31, Akihiko Odaki wrote:
> ...
>>> Requirements don't vary much. For example virglrenderer minigbm support
>>> is mandatory for crosvm, while for QEMU it's not.
>>
>> Is that true? It seems that virglrenderer uses builds without minigbm
>> support to run tests on GitLab CI.
> 
> CI is running in a headless mode using software renderer. For a
> full-featured crosvm support running on a baremetal, minigbm should be
> needed, along with other downstream features.

That makes sense.

Based on your input, for QEMU, I don't think we need a separate 
documentation to describe libvirglrenderer's build flags though crosvm 
should have some documentation saying it requires minigbm.

> 
>> Anyway, if there is any variance in the build procedure, that may
>> justify having a separate build instruction in QEMU tree to avoid
>> confusion. Otherwise, it's better to have a documentation shared with
>> other VMMs.
>>
>>>
>>>> I'm not entirely sure the documentation will stay as is for that long.
>>>> The requirements of Intel native context refer to merge requests that
>>>> can be merged sooner or later. Asahi may need more updates if you
>>>> document it too because its DRM ABI is still unstable.
>>>
>>> The unstable parts of course will need to be updated sooner, but the
>>> stable should be solid for years. I expect that about a year later
>>> requirements will need to be revisited.
>>>
>>
>> It will be some burden in the future. Now you are adding this
>> documentation just for QEMU, but crosvm and libkrun may gain similar
>> documentation. The DRM native context support for Intel and Asahi is in
>> development, and I guess nvk will support it someday.
>>
>> So, a very rough estimation of future documentation updates will be:
>> (number of VMMs) * (number of DRM native contexts in development)
>> = 3 * 3
>> = 9
>>
>> That's manageable but suboptimal.
> 
> I don't mind deferring the doc addition if that's preferred. Either way
> is fine with me. Yet it's better to have doc than not.

My suggestion is not to defer the addition, but to add it to Mesa, which 
does not require deferring.

> 
> In my view crosvm and libkrun exist separately from QEMU, they serve a
> different purpose. Majority of QEMU users likely never heard about those
> other VMMs. A unified doc won't be a worthwhile effort, IMO.
> 

When evaluating the utility of a unified documentation, Whether the 
majority of Mesa/Virgl users care VMMs other than QEMU matters more. And 
I think it is true; libkrun and crosvm are excellent options for 
graphics-accelerated VMs.

If we have a unified documentation, any VM can point to it for the build 
instruction of Mesa and virglrenderer. Once that's done, QEMU users who 
want graphics acceleration can take the following steps:
1. See docs/system/devices/virtio-gpu.rst
2. Figure out that they need Mesa and virglrenderer
3. Click the link to the unified documentation
4. Build Mesa and virglrenderer accordingly

No other VMMs will bother them in this procedure.

Regards,
Akihiko Odaki