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
QEMU virtio-gpu variants
QEMU virtio-gpu device variants come in the following form:
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.
The default 2D backend only performs 2D operations. The guest needs to employ a software renderer for 3D graphics.
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.
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.
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
cross-domain for Linux guests. For Android guests, the experimental
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.
wsi option can be set to
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.