system/devices/virtio-gpu.rst

2    SPDX-License-Identifier: GPL-2.0-or-later
4 virtio-gpu
7 This document explains the setup and usage of the virtio-gpu device.
8 The virtio-gpu device paravirtualizes the GPU and display controller.
11 --------------------
13 virtio-gpu requires a guest Linux kernel built with the
16 QEMU virtio-gpu variants
17 ------------------------
19 QEMU virtio-gpu device variants come in the following form:
21  * ``virtio-vga[-BACKEND]``
22  * ``virtio-gpu[-BACKEND][-INTERFACE]``
23  * ``vhost-user-vga``
24  * ``vhost-user-pci``
26 **Backends:** QEMU provides a 2D virtio-gpu backend, and two accelerated
28 device label).  There is a vhost-user backend that runs the graphics stack
31 **Interfaces:** QEMU further categorizes virtio-gpu device variants based
33 into VGA and non-VGA variants. The VGA ones are prefixed with virtio-vga
34 or vhost-user-vga while the non-VGA ones are prefixed with virtio-gpu or
35 vhost-user-gpu.
37 The VGA ones always use the PCI interface, but for the non-VGA ones, the
39 the device name with -device, though vhost-user-gpu does not support MMIO.
40 For PCI, the user can suffix it with -pci. Without these suffixes, the
43 virtio-gpu 2d
44 -------------
46 The default 2D backend only performs 2D operations. The guest needs to
53 .. parsed-literal::
54     -device virtio-gpu
59 virtio-gpu virglrenderer
60 ------------------------
68 .. parsed-literal::
69     -device virtio-gpu-gl
75 v1.0.0 using `venus`_ protocol. ``Venus`` virtio-gpu capability set ("capset")
78 of virtio-gpu host memory window. This is typically between 256M and 8G.
80 .. parsed-literal::
81     -device virtio-gpu-gl,hostmem=8G,blob=true,venus=true
83 .. _venus: https://gitlab.freedesktop.org/virgl/venus-protocol/
85 virtio-gpu rutabaga
86 -------------------
88 virtio-gpu can also leverage rutabaga_gfx to provide `gfxstream`_
89 rendering and `Wayland display passthrough`_.  With the gfxstream rendering
93 The crosvm book provides directions on how to build a `gfxstream-enabled
97 ``hostmem`` field specifies the size of virtio-gpu host memory window.
100 At least one virtio-gpu capability set ("capset") must be specified when
101 starting the device.  The currently capsets supported are ``gfxstream-vulkan``
102 and ``cross-domain`` for Linux guests. For Android guests, the experimental
103 ``x-gfxstream-gles`` and ``x-gfxstream-composer`` capsets are also supported.
105 The 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.
111 render target to the Pixman buffer if a virtio-gpu 2D hypercall is issued.
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,
121 .. _Wayland display passthrough: https://www.youtube.com/watch?v=OZJiHMtIQ2M
122 .. _gfxstream-enabled rutabaga: https://crosvm.dev/book/appendix/rutabaga_gfx.html