1..
2   SPDX-License-Identifier: GPL-2.0-or-later
3
4virtio-gpu
5==========
6
7This document explains the setup and usage of the virtio-gpu device.
8The virtio-gpu device paravirtualizes the GPU and display controller.
9
10Linux kernel support
11--------------------
12
13virtio-gpu requires a guest Linux kernel built with the
14``CONFIG_DRM_VIRTIO_GPU`` option.
15
16QEMU virtio-gpu variants
17------------------------
18
19QEMU virtio-gpu device variants come in the following form:
20
21 * ``virtio-vga[-BACKEND]``
22 * ``virtio-gpu[-BACKEND][-INTERFACE]``
23 * ``vhost-user-vga``
24 * ``vhost-user-pci``
25
26**Backends:** QEMU provides a 2D virtio-gpu backend, and two accelerated
27backends: virglrenderer ('gl' device label) and rutabaga_gfx ('rutabaga'
28device label).  There is a vhost-user backend that runs the graphics stack
29in a separate process for improved isolation.
30
31**Interfaces:** QEMU further categorizes virtio-gpu device variants based
32on the interface exposed to the guest. The interfaces can be classified
33into VGA and non-VGA variants. The VGA ones are prefixed with virtio-vga
34or vhost-user-vga while the non-VGA ones are prefixed with virtio-gpu or
35vhost-user-gpu.
36
37The VGA ones always use the PCI interface, but for the non-VGA ones, the
38user can further pick between MMIO or PCI. For MMIO, the user can suffix
39the device name with -device, though vhost-user-gpu does not support MMIO.
40For PCI, the user can suffix it with -pci. Without these suffixes, the
41platform default will be chosen.
42
43virtio-gpu 2d
44-------------
45
46The default 2D backend only performs 2D operations. The guest needs to
47employ a software renderer for 3D graphics.
48
49Typically, the software renderer is provided by `Mesa`_ or `SwiftShader`_.
50Mesa's implementations (LLVMpipe, Lavapipe and virgl below) work out of box
51on typical modern Linux distributions.
52
53.. parsed-literal::
54    -device virtio-gpu
55
56.. _Mesa: https://www.mesa3d.org/
57.. _SwiftShader: https://github.com/google/swiftshader
58
59virtio-gpu virglrenderer
60------------------------
61
62When using virgl accelerated graphics mode in the guest, OpenGL API calls
63are translated into an intermediate representation (see `Gallium3D`_). The
64intermediate representation is communicated to the host and the
65`virglrenderer`_ library on the host translates the intermediate
66representation back to OpenGL API calls.
67
68.. parsed-literal::
69    -device virtio-gpu-gl
70
71.. _Gallium3D: https://www.freedesktop.org/wiki/Software/gallium/
72.. _virglrenderer: https://gitlab.freedesktop.org/virgl/virglrenderer/
73
74Translation of Vulkan API calls is supported since release of `virglrenderer`_
75v1.0.0 using `venus`_ protocol. ``Venus`` virtio-gpu capability set ("capset")
76requires host blob support (``hostmem`` and ``blob`` fields) and should
77be enabled using ``venus`` field. The ``hostmem`` field specifies the size
78of virtio-gpu host memory window. This is typically between 256M and 8G.
79
80.. parsed-literal::
81    -device virtio-gpu-gl,hostmem=8G,blob=true,venus=true
82
83.. _venus: https://gitlab.freedesktop.org/virgl/venus-protocol/
84
85virtio-gpu rutabaga
86-------------------
87
88virtio-gpu can also leverage rutabaga_gfx to provide `gfxstream`_
89rendering and `Wayland display passthrough`_.  With the gfxstream rendering
90mode, GLES and Vulkan calls are forwarded to the host with minimal
91modification.
92
93The crosvm book provides directions on how to build a `gfxstream-enabled
94rutabaga`_ and launch a `guest Wayland proxy`_.
95
96This device does require host blob support (``hostmem`` field below). The
97``hostmem`` field specifies the size of virtio-gpu host memory window.
98This is typically between 256M and 8G.
99
100At least one virtio-gpu capability set ("capset") must be specified when
101starting the device.  The currently capsets supported are ``gfxstream-vulkan``
102and ``cross-domain`` for Linux guests. For Android guests, the experimental
103``x-gfxstream-gles`` and ``x-gfxstream-composer`` capsets are also supported.
104
105The device will try to auto-detect the wayland socket path if the
106``cross-domain`` capset name is set.  The user may optionally specify
107``wayland-socket-path`` for non-standard paths.
108
109The ``wsi`` option can be set to ``surfaceless`` or ``headless``.
110Surfaceless doesn't create a native window surface, but does copy from the
111render target to the Pixman buffer if a virtio-gpu 2D hypercall is issued.
112Headless is like surfaceless, but doesn't copy to the Pixman buffer.
113Surfaceless is the default if ``wsi`` is not specified.
114
115.. parsed-literal::
116    -device virtio-gpu-rutabaga,gfxstream-vulkan=on,cross-domain=on,
117       hostmem=8G,wayland-socket-path=/tmp/nonstandard/mock_wayland.sock,
118       wsi=headless
119
120.. _gfxstream: https://android.googlesource.com/platform/hardware/google/gfxstream/
121.. _Wayland display passthrough: https://www.youtube.com/watch?v=OZJiHMtIQ2M
122.. _gfxstream-enabled rutabaga: https://crosvm.dev/book/appendix/rutabaga_gfx.html
123.. _guest Wayland proxy: https://crosvm.dev/book/devices/wayland.html
124