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 74virtio-gpu rutabaga 75------------------- 76 77virtio-gpu can also leverage rutabaga_gfx to provide `gfxstream`_ 78rendering and `Wayland display passthrough`_. With the gfxstream rendering 79mode, GLES and Vulkan calls are forwarded to the host with minimal 80modification. 81 82The crosvm book provides directions on how to build a `gfxstream-enabled 83rutabaga`_ and launch a `guest Wayland proxy`_. 84 85This device does require host blob support (``hostmem`` field below). The 86``hostmem`` field specifies the size of virtio-gpu host memory window. 87This is typically between 256M and 8G. 88 89At least one virtio-gpu capability set ("capset") must be specified when 90starting the device. The currently capsets supported are ``gfxstream-vulkan`` 91and ``cross-domain`` for Linux guests. For Android guests, the experimental 92``x-gfxstream-gles`` and ``x-gfxstream-composer`` capsets are also supported. 93 94The device will try to auto-detect the wayland socket path if the 95``cross-domain`` capset name is set. The user may optionally specify 96``wayland-socket-path`` for non-standard paths. 97 98The ``wsi`` option can be set to ``surfaceless`` or ``headless``. 99Surfaceless doesn't create a native window surface, but does copy from the 100render target to the Pixman buffer if a virtio-gpu 2D hypercall is issued. 101Headless is like surfaceless, but doesn't copy to the Pixman buffer. 102Surfaceless is the default if ``wsi`` is not specified. 103 104.. parsed-literal:: 105 -device virtio-gpu-rutabaga,gfxstream-vulkan=on,cross-domain=on, 106 hostmem=8G,wayland-socket-path=/tmp/nonstandard/mock_wayland.sock, 107 wsi=headless 108 109.. _gfxstream: https://android.googlesource.com/platform/hardware/google/gfxstream/ 110.. _Wayland display passthrough: https://www.youtube.com/watch?v=OZJiHMtIQ2M 111.. _gfxstream-enabled rutabaga: https://crosvm.dev/book/appendix/rutabaga_gfx.html 112.. _guest Wayland proxy: https://crosvm.dev/book/devices/wayland.html 113