aboutsummaryrefslogtreecommitdiff
path: root/docs/system/devices/virtio-gpu.rst
blob: cb73dd799858b8c143d9a929d54d6d5b8ca8416e (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
..
   SPDX-License-Identifier: GPL-2.0-or-later

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
--------------------

virtio-gpu requires a guest Linux kernel built with the
``CONFIG_DRM_VIRTIO_GPU`` option.

QEMU virtio-gpu variants
------------------------

QEMU virtio-gpu device variants come in the following form:

 * ``virtio-vga[-BACKEND]``
 * ``virtio-gpu[-BACKEND][-INTERFACE]``
 * ``vhost-user-vga``
 * ``vhost-user-pci``

**Backends:** QEMU provides a 2D virtio-gpu backend, and two accelerated
backends: virglrenderer ('gl' device label) and rutabaga_gfx ('rutabaga'
device label).  There is a vhost-user backend that runs the graphics stack
in a separate process for improved isolation.

**Interfaces:** QEMU further categorizes virtio-gpu device variants based
on the interface exposed to the guest. The interfaces can be classified
into VGA and non-VGA variants. The VGA ones are prefixed with virtio-vga
or vhost-user-vga while the non-VGA ones are prefixed with virtio-gpu or
vhost-user-gpu.

The VGA ones always use the PCI interface, but for the non-VGA ones, the
user can further pick between MMIO or PCI. For MMIO, the user can suffix
the device name with -device, though vhost-user-gpu does not support MMIO.
For PCI, the user can suffix it with -pci. Without these suffixes, the
platform default will be chosen.

virtio-gpu 2d
-------------

The default 2D backend only performs 2D operations. The guest needs to
employ a software renderer for 3D graphics.

Typically, the software renderer is provided by `Mesa`_ or `SwiftShader`_.
Mesa's implementations (LLVMpipe, Lavapipe and virgl below) work out of box
on typical modern Linux distributions.

.. parsed-literal::
    -device virtio-gpu

.. _Mesa: https://www.mesa3d.org/
.. _SwiftShader: https://github.com/google/swiftshader

virtio-gpu virglrenderer
------------------------

When using virgl accelerated graphics mode in the guest, OpenGL API calls
are translated into an intermediate representation (see `Gallium3D`_). The
intermediate representation is communicated to the host and the
`virglrenderer`_ library on the host translates the intermediate
representation back to OpenGL API calls.

.. parsed-literal::
    -device virtio-gpu-gl

.. _Gallium3D: https://www.freedesktop.org/wiki/Software/gallium/
.. _virglrenderer: https://gitlab.freedesktop.org/virgl/virglrenderer/

virtio-gpu rutabaga
-------------------

virtio-gpu can also leverage rutabaga_gfx to provide `gfxstream`_
rendering and `Wayland display passthrough`_.  With the gfxstream rendering
mode, GLES and Vulkan calls are forwarded to the host with minimal
modification.

The crosvm book provides directions on how to build a `gfxstream-enabled
rutabaga`_ and launch a `guest Wayland proxy`_.

This device does require host blob support (``hostmem`` field below). The
``hostmem`` field specifies the size of virtio-gpu host memory window.
This is typically between 256M and 8G.

At least one virtio-gpu capability set ("capset") must be specified when
starting the device.  The currently capsets supported are ``gfxstream-vulkan``
and ``cross-domain`` for Linux guests. For Android guests, the experimental
``x-gfxstream-gles`` and ``x-gfxstream-composer`` capsets are also supported.

The device will try to auto-detect the wayland socket path if the
``cross-domain`` capset name is set.  The user may optionally specify
``wayland-socket-path`` for non-standard paths.

The ``wsi`` option can be set to ``surfaceless`` or ``headless``.
Surfaceless doesn't create a native window surface, but does copy from the
render target to the Pixman buffer if a virtio-gpu 2D hypercall is issued.
Headless is like surfaceless, but doesn't copy to the Pixman buffer.
Surfaceless is the default if ``wsi`` is not specified.

.. parsed-literal::
    -device virtio-gpu-rutabaga,gfxstream-vulkan=on,cross-domain=on,
       hostmem=8G,wayland-socket-path=/tmp/nonstandard/mock_wayland.sock,
       wsi=headless

.. _gfxstream: https://android.googlesource.com/platform/hardware/google/gfxstream/
.. _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