| 1 | .. |
| 2 | SPDX-License-Identifier: GPL-2.0-or-later |
| 3 | |
| 4 | .. _virtio_gpu: |
| 5 | |
| 6 | VirtIO GPU |
| 7 | ========== |
| 8 | |
| 9 | This document explains the setup and usage of the virtio-gpu device. |
| 10 | The virtio-gpu device provides a GPU and display controller |
| 11 | paravirtualized using VirtIO. It supports a number of different modes |
| 12 | from simple 2D displays to fully accelerated 3D graphics. |
| 13 | |
| 14 | Linux guest kernel support |
| 15 | -------------------------- |
| 16 | |
| 17 | virtio-gpu requires a guest Linux kernel built with the |
| 18 | ``CONFIG_DRM_VIRTIO_GPU`` option. |
| 19 | |
| 20 | 3D acceleration |
| 21 | --------------- |
| 22 | |
| 23 | 3D acceleration of a virtualized GPU is still an evolving field. |
| 24 | Depending on the 3D mode you are running you may need to override |
| 25 | distribution supplied libraries with more recent versions or enable |
| 26 | build options. There are a number of requirements the host must meet |
| 27 | to be able to be able to support guests. QEMU must be able to access the |
| 28 | host's GPU and for the best performance be able to reliably share GPU |
| 29 | memory with the guest. Details of 3D acceleration requirements are |
| 30 | described in a further sections. |
| 31 | |
| 32 | QEMU virtio-gpu variants |
| 33 | ------------------------ |
| 34 | |
| 35 | QEMU virtio-gpu device variants come in the following form: |
| 36 | |
| 37 | * ``virtio-vga[-BACKEND]`` |
| 38 | * ``virtio-gpu[-BACKEND][-INTERFACE]`` |
| 39 | * ``vhost-user-vga`` |
| 40 | * ``vhost-user-pci`` |
| 41 | |
| 42 | **Backends:** QEMU provides a 2D virtio-gpu backend, and two accelerated |
| 43 | backends: virglrenderer ('gl' device label) and rutabaga_gfx ('rutabaga' |
| 44 | device label). There is a vhost-user backend that runs the graphics stack |
| 45 | in a separate process for improved isolation. |
| 46 | |
| 47 | **Interfaces:** QEMU further categorizes virtio-gpu device variants based |
| 48 | on the interface exposed to the guest. The interfaces can be classified |
| 49 | into VGA and non-VGA variants. The VGA ones are prefixed with virtio-vga |
| 50 | or vhost-user-vga while the non-VGA ones are prefixed with virtio-gpu or |
| 51 | vhost-user-gpu. |
| 52 | |
| 53 | The VGA ones always use the PCI interface, but for the non-VGA ones, the |
| 54 | user can further pick between MMIO or PCI. For MMIO, the user can suffix |
| 55 | the device name with -device, though vhost-user-gpu does not support MMIO. |
| 56 | For PCI, the user can suffix it with -pci. Without these suffixes, the |
| 57 | platform default will be chosen. |
| 58 | |
| 59 | virtio-gpu 2d |
| 60 | ------------- |
| 61 | |
| 62 | The default 2D backend only performs 2D operations. The guest needs to |
| 63 | employ a software renderer for 3D graphics. |
| 64 | |
| 65 | Typically, the software renderer is provided by `Mesa`_ or `SwiftShader`_. |
| 66 | Mesa's implementations (LLVMpipe, Lavapipe and virgl below) work out of box |
| 67 | on typical modern Linux distributions. |
| 68 | |
| 69 | .. parsed-literal:: |
| 70 | -device virtio-gpu |
| 71 | |
| 72 | .. _Mesa: https://www.mesa3d.org/ |
| 73 | .. _SwiftShader: https://github.com/google/swiftshader |
| 74 | |
| 75 | virtio-gpu virglrenderer |
| 76 | ------------------------ |
| 77 | |
| 78 | When using `virgl`_ accelerated graphics mode in the guest, OpenGL API calls |
| 79 | are translated into an intermediate representation (see `Gallium3D`_). The |
| 80 | intermediate representation is communicated to the host and the |
| 81 | `virglrenderer`_ library on the host translates the intermediate |
| 82 | representation back to OpenGL API calls. |
| 83 | |
| 84 | By default OpenGL version on guest is limited to 4.3. In order to enable |
| 85 | OpenGL 4.6 support, virtio-gpu host blobs feature (``hostmem`` and ``blob`` |
| 86 | fields) should be enabled. The ``hostmem`` field specifies the size of |
| 87 | virtio-gpu host memory window. This is typically between 256M and 8G. |
| 88 | |
| 89 | .. parsed-literal:: |
| 90 | -device virtio-gpu-gl |
| 91 | -device virtio-gpu-gl,hostmem=8G,blob=true |
| 92 | |
| 93 | .. _virgl: https://docs.mesa3d.org/drivers/virgl.html |
| 94 | .. _Gallium3D: https://www.freedesktop.org/wiki/Software/gallium/ |
| 95 | .. _virglrenderer: https://gitlab.freedesktop.org/virgl/virglrenderer/ |
| 96 | |
| 97 | Translation of Vulkan API calls is supported since release of `virglrenderer`_ |
| 98 | v1.0.0 using `venus`_ protocol. ``Venus`` virtio-gpu capability set ("capset") |
| 99 | requires host blob support (``hostmem`` and ``blob`` fields) and should |
| 100 | be enabled using ``venus`` field. The ``hostmem`` field specifies the size |
| 101 | of virtio-gpu host memory window. This is typically between 256M and 8G. |
| 102 | |
| 103 | .. parsed-literal:: |
| 104 | -device virtio-gpu-gl,hostmem=8G,blob=true,venus=true |
| 105 | |
| 106 | .. _venus: https://docs.mesa3d.org/drivers/venus.html |
| 107 | |
| 108 | DRM native context is supported since release of `virglrenderer`_ v1.0.0 |
| 109 | using `drm`_ protocol. ``DRM`` virtio-gpu capability set ("capset") requires |
| 110 | host blob support (``hostmem`` and ``blob`` fields) and should be enabled |
| 111 | using ``drm_native_context`` field. The ``hostmem`` field specifies the size |
| 112 | of virtio-gpu host memory window. This is typically between 256M and 8G. |
| 113 | |
| 114 | .. parsed-literal:: |
| 115 | -device virtio-gpu-gl,hostmem=8G,blob=on,drm_native_context=on |
| 116 | |
| 117 | .. _drm: https://gitlab.freedesktop.org/virgl/virglrenderer/-/tree/main/src/drm |
| 118 | |
| 119 | .. list-table:: Linux Host Requirements |
| 120 | :header-rows: 1 |
| 121 | |
| 122 | * - Capability |
| 123 | - Kernel Version |
| 124 | - Libvirglrenderer Version |
| 125 | * - OpenGL pass-through |
| 126 | - Any Linux version compatible with QEMU if not using host blobs feature, |
| 127 | Linux 6.13+ otherwise |
| 128 | - 0.8.2+ |
| 129 | * - Vulkan pass-through |
| 130 | - Linux 6.13+ |
| 131 | - 1.0.0+ |
| 132 | * - AMDGPU DRM native context |
| 133 | - Linux 6.13+ |
| 134 | - 1.1.0+ |
| 135 | * - Freedreno DRM native context |
| 136 | - Linux 6.4+ |
| 137 | - 1.0.0+ |
| 138 | * - Intel i915 DRM native context |
| 139 | - Linux 6.13+ |
| 140 | - 1.3.0+ |
| 141 | * - Asahi DRM native context |
| 142 | - `Downstream version`_ of Asahi Linux kernel |
| 143 | - 1.2.0+ |
| 144 | * - Panfrost native context |
| 145 | - Linux 6.13+ |
| 146 | - 1.3.0+ |
| 147 | |
| 148 | .. _Downstream version: https://github.com/AsahiLinux/linux |
| 149 | |
| 150 | .. list-table:: Linux Guest Requirements |
| 151 | :header-rows: 1 |
| 152 | |
| 153 | * - Capability |
| 154 | - Kernel Version |
| 155 | - Mesa Version |
| 156 | * - OpenGL pass-through |
| 157 | - Any Linux version supporting virtio-gpu |
| 158 | - 16.0.0+ |
| 159 | * - Vulkan pass-through |
| 160 | - Linux 5.16+ |
| 161 | - 24.2.0+ |
| 162 | * - AMDGPU DRM native context |
| 163 | - Linux 6.14+ |
| 164 | - 25.0.0+ |
| 165 | * - Freedreno DRM native context |
| 166 | - Linux 6.14+ |
| 167 | - 23.1.0+ |
| 168 | * - Intel i915 DRM native context |
| 169 | - Linux 6.14+ |
| 170 | - 26.1.0+ |
| 171 | * - Asahi DRM native context |
| 172 | - Linux 6.14+ |
| 173 | - 24.2.0+ |
| 174 | * - Panfrost native context |
| 175 | - Linux 6.14+ |
| 176 | - `mr36814`_ |
| 177 | |
| 178 | .. _mr36814: https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/36814 |
| 179 | |
| 180 | virtio-gpu rutabaga |
| 181 | ------------------- |
| 182 | |
| 183 | virtio-gpu can also leverage rutabaga_gfx to provide `gfxstream`_ |
| 184 | rendering and `Wayland display passthrough`_. With the gfxstream rendering |
| 185 | mode, GLES and Vulkan calls are forwarded to the host with minimal |
| 186 | modification. |
| 187 | |
| 188 | The crosvm book provides directions on how to build a `gfxstream-enabled |
| 189 | rutabaga`_ and launch a `guest Wayland proxy`_. |
| 190 | |
| 191 | This device does require host blob support (``hostmem`` field below). The |
| 192 | ``hostmem`` field specifies the size of virtio-gpu host memory window. |
| 193 | This is typically between 256M and 8G. |
| 194 | |
| 195 | At least one virtio-gpu capability set ("capset") must be specified when |
| 196 | starting the device. The currently capsets supported are ``gfxstream-vulkan`` |
| 197 | and ``cross-domain`` for Linux guests. For Android guests, the experimental |
| 198 | ``x-gfxstream-gles`` and ``x-gfxstream-composer`` capsets are also supported. |
| 199 | |
| 200 | The device will try to auto-detect the wayland socket path if the |
| 201 | ``cross-domain`` capset name is set. The user may optionally specify |
| 202 | ``wayland-socket-path`` for non-standard paths. |
| 203 | |
| 204 | The ``wsi`` option can be set to ``surfaceless`` or ``headless``. |
| 205 | Surfaceless doesn't create a native window surface, but does copy from the |
| 206 | render target to the Pixman buffer if a virtio-gpu 2D hypercall is issued. |
| 207 | Headless is like surfaceless, but doesn't copy to the Pixman buffer. |
| 208 | Surfaceless is the default if ``wsi`` is not specified. |
| 209 | |
| 210 | .. parsed-literal:: |
| 211 | -device virtio-gpu-rutabaga,gfxstream-vulkan=on,cross-domain=on, |
| 212 | hostmem=8G,wayland-socket-path=/tmp/nonstandard/mock_wayland.sock, |
| 213 | wsi=headless |
| 214 | |
| 215 | .. _gfxstream: https://android.googlesource.com/platform/hardware/google/gfxstream/ |
| 216 | .. _Wayland display passthrough: https://www.youtube.com/watch?v=OZJiHMtIQ2M |
| 217 | .. _gfxstream-enabled rutabaga: https://crosvm.dev/book/appendix/rutabaga_gfx.html |
| 218 | .. _guest Wayland proxy: https://crosvm.dev/book/devices/wayland.html |
| 219 | |
| 220 | .. list-table:: Linux Host Requirements |
| 221 | :header-rows: 1 |
| 222 | |
| 223 | * - Capability |
| 224 | - Kernel Version |
| 225 | * - Vulkan+Wayland pass-through |
| 226 | - Linux 6.13+ |
| 227 | |
| 228 | .. list-table:: Linux Guest Requirements |
| 229 | :header-rows: 1 |
| 230 | |
| 231 | * - Capability |
| 232 | - Kernel Version |
| 233 | - Mesa Version |
| 234 | * - Vulkan+Wayland pass-through |
| 235 | - Linux 5.16+ |
| 236 | - 24.3.0+ |