docs/system/devices/virtio/virtio-gpu.rst - qemu - Git at Google

 ..
    SPDX-License-Identifier: GPL-2.0-or-later

 .. _virtio_gpu:

 VirtIO GPU
 ==========

 This document explains the setup and usage of the virtio-gpu device.
 The virtio-gpu device provides a GPU and display controller
 paravirtualized using VirtIO. It supports a number of different modes
 from simple 2D displays to fully accelerated 3D graphics.

 Linux guest kernel support
 --------------------------

 virtio-gpu requires a guest Linux kernel built with the
 ``CONFIG_DRM_VIRTIO_GPU`` option.

 3D acceleration
 ---------------

 3D acceleration of a virtualized GPU is still an evolving field.
 Depending on the 3D mode you are running you may need to override
 distribution supplied libraries with more recent versions or enable
 build options. There are a number of requirements the host must meet
 to be able to be able to support guests. QEMU must be able to access the
 host's GPU and for the best performance be able to reliably share GPU
 memory with the guest. Details of 3D acceleration requirements are
 described in a further sections.

 QEMU virtio-gpu variants
 ------------------------

 QEMU virtio-gpu device variants come in the following form:

  * ``virtio-vga[-BACKEND]``
  * ``virtio-gpu[-BACKEND][-INTERFACE]``
  * ``vhost-user-vga``
  * ``vhost-user-pci``

 **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.

 virtio-gpu 2d
 -------------

 The default 2D backend only performs 2D operations. The guest needs to
 employ a software renderer for 3D graphics.

 Typically, the software renderer is provided by `Mesa`_ or `SwiftShader`_.
 Mesa's implementations (LLVMpipe, Lavapipe and virgl below) work out of box
 on typical modern Linux distributions.

 .. parsed-literal::
     -device virtio-gpu

 .. _Mesa: https://www.mesa3d.org/
 .. _SwiftShader: https://github.com/google/swiftshader

 virtio-gpu virglrenderer
 ------------------------

 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.

 By default OpenGL version on guest is limited to 4.3. In order to enable
 OpenGL 4.6 support, virtio-gpu  host blobs feature (``hostmem`` and ``blob``
 fields) should be enabled.  The ``hostmem`` field specifies the size of
 virtio-gpu host memory window. This is typically between 256M and 8G.

 .. parsed-literal::
     -device virtio-gpu-gl
     -device virtio-gpu-gl,hostmem=8G,blob=true

 .. _virgl: https://docs.mesa3d.org/drivers/virgl.html
 .. _Gallium3D: https://www.freedesktop.org/wiki/Software/gallium/
 .. _virglrenderer: https://gitlab.freedesktop.org/virgl/virglrenderer/

 Translation of Vulkan API calls is supported since release of `virglrenderer`_
 v1.0.0 using `venus`_ protocol. ``Venus`` virtio-gpu capability set ("capset")
 requires host blob support (``hostmem`` and ``blob`` fields) and should
 be enabled using ``venus`` field. The ``hostmem`` field specifies the size
 of virtio-gpu host memory window. This is typically between 256M and 8G.

 .. parsed-literal::
     -device virtio-gpu-gl,hostmem=8G,blob=true,venus=true

 .. _venus: https://docs.mesa3d.org/drivers/venus.html

 DRM native context is supported since release of `virglrenderer`_ v1.0.0
 using `drm`_ protocol.  ``DRM`` virtio-gpu capability set ("capset") requires
 host blob support (``hostmem`` and ``blob`` fields) and should be enabled
 using ``drm_native_context`` field.  The ``hostmem`` field specifies the size
 of virtio-gpu host memory window. This is typically between 256M and 8G.

 .. parsed-literal::
     -device virtio-gpu-gl,hostmem=8G,blob=on,drm_native_context=on

 .. _drm: https://gitlab.freedesktop.org/virgl/virglrenderer/-/tree/main/src/drm

 .. list-table:: Linux Host Requirements
   :header-rows: 1

   * - Capability
     - Kernel Version
     - Libvirglrenderer Version
   * - OpenGL pass-through
     - Any Linux version compatible with QEMU if not using host blobs feature,
       Linux 6.13+ otherwise
     - 0.8.2+
   * - Vulkan pass-through
     - Linux 6.13+
     - 1.0.0+
   * - AMDGPU DRM native context
     - Linux 6.13+
     - 1.1.0+
   * - Freedreno DRM native context
     - Linux 6.4+
     - 1.0.0+
   * - Intel i915 DRM native context
     - Linux 6.13+
     - 1.3.0+
   * - Asahi DRM native context
     - `Downstream version`_ of Asahi Linux kernel
     - 1.2.0+
   * - Panfrost native context
     - Linux 6.13+
     - 1.3.0+

 .. _Downstream version: https://github.com/AsahiLinux/linux

 .. list-table:: Linux Guest Requirements
   :header-rows: 1

   * - Capability
     - Kernel Version
     - Mesa Version
   * - OpenGL pass-through
     - Any Linux version supporting virtio-gpu
     - 16.0.0+
   * - Vulkan pass-through
     - Linux 5.16+
     - 24.2.0+
   * - AMDGPU DRM native context
     - Linux 6.14+
     - 25.0.0+
   * - Freedreno DRM native context
     - Linux 6.14+
     - 23.1.0+
   * - Intel i915 DRM native context
     - Linux 6.14+
     - 26.1.0+
   * - Asahi DRM native context
     - Linux 6.14+
     - 24.2.0+
   * - Panfrost native context
     - Linux 6.14+
     - `mr36814`_

 .. _mr36814: https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/36814

 virtio-gpu rutabaga
 -------------------

 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.

 The crosvm book provides directions on how to build a `gfxstream-enabled
 rutabaga`_ and launch a `guest Wayland proxy`_.

 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 ``gfxstream-vulkan``
 and ``cross-domain`` for Linux guests. For Android guests, the experimental
 ``x-gfxstream-gles`` and ``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.

 The ``wsi`` option can be set to ``surfaceless`` or ``headless``.
 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.

 .. parsed-literal::
     -device virtio-gpu-rutabaga,gfxstream-vulkan=on,cross-domain=on,
        hostmem=8G,wayland-socket-path=/tmp/nonstandard/mock_wayland.sock,
        wsi=headless

 .. _gfxstream: https://android.googlesource.com/platform/hardware/google/gfxstream/
 .. _Wayland display passthrough: https://www.youtube.com/watch?v=OZJiHMtIQ2M
 .. _gfxstream-enabled rutabaga: https://crosvm.dev/book/appendix/rutabaga_gfx.html
 .. _guest Wayland proxy: https://crosvm.dev/book/devices/wayland.html

 .. list-table:: Linux Host Requirements
   :header-rows: 1

   * - Capability
     - Kernel Version
   * - Vulkan+Wayland pass-through
     - Linux 6.13+

 .. list-table:: Linux Guest Requirements
   :header-rows: 1

   * - Capability
     - Kernel Version
     - Mesa Version
   * - Vulkan+Wayland pass-through
     - Linux 5.16+
     - 24.3.0+
	..
	SPDX-License-Identifier: GPL-2.0-or-later

	.. _virtio_gpu:

	VirtIO GPU
	==========

	This document explains the setup and usage of the virtio-gpu device.
	The virtio-gpu device provides a GPU and display controller
	paravirtualized using VirtIO. It supports a number of different modes
	from simple 2D displays to fully accelerated 3D graphics.

	Linux guest kernel support
	--------------------------

	virtio-gpu requires a guest Linux kernel built with the
	``CONFIG_DRM_VIRTIO_GPU`` option.

	3D acceleration
	---------------

	3D acceleration of a virtualized GPU is still an evolving field.
	Depending on the 3D mode you are running you may need to override
	distribution supplied libraries with more recent versions or enable
	build options. There are a number of requirements the host must meet
	to be able to be able to support guests. QEMU must be able to access the
	host's GPU and for the best performance be able to reliably share GPU
	memory with the guest. Details of 3D acceleration requirements are
	described in a further sections.

	QEMU virtio-gpu variants
	------------------------

	QEMU virtio-gpu device variants come in the following form:

	* ``virtio-vga[-BACKEND]``
	* ``virtio-gpu[-BACKEND][-INTERFACE]``
	* ``vhost-user-vga``
	* ``vhost-user-pci``

	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.

	virtio-gpu 2d
	-------------

	The default 2D backend only performs 2D operations. The guest needs to
	employ a software renderer for 3D graphics.

	Typically, the software renderer is provided by `Mesa`_ or `SwiftShader`_.
	Mesa's implementations (LLVMpipe, Lavapipe and virgl below) work out of box
	on typical modern Linux distributions.

	.. parsed-literal::
	-device virtio-gpu

	.. _Mesa: https://www.mesa3d.org/
	.. _SwiftShader: https://github.com/google/swiftshader

	virtio-gpu virglrenderer
	------------------------

	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.

	By default OpenGL version on guest is limited to 4.3. In order to enable
	OpenGL 4.6 support, virtio-gpu host blobs feature (``hostmem`` and ``blob``
	fields) should be enabled. The ``hostmem`` field specifies the size of
	virtio-gpu host memory window. This is typically between 256M and 8G.

	.. parsed-literal::
	-device virtio-gpu-gl
	-device virtio-gpu-gl,hostmem=8G,blob=true

	.. _virgl: https://docs.mesa3d.org/drivers/virgl.html
	.. _Gallium3D: https://www.freedesktop.org/wiki/Software/gallium/
	.. _virglrenderer: https://gitlab.freedesktop.org/virgl/virglrenderer/

	Translation of Vulkan API calls is supported since release of `virglrenderer`_
	v1.0.0 using `venus`_ protocol. ``Venus`` virtio-gpu capability set ("capset")
	requires host blob support (``hostmem`` and ``blob`` fields) and should
	be enabled using ``venus`` field. The ``hostmem`` field specifies the size
	of virtio-gpu host memory window. This is typically between 256M and 8G.

	.. parsed-literal::
	-device virtio-gpu-gl,hostmem=8G,blob=true,venus=true

	.. _venus: https://docs.mesa3d.org/drivers/venus.html

	DRM native context is supported since release of `virglrenderer`_ v1.0.0
	using `drm`_ protocol. ``DRM`` virtio-gpu capability set ("capset") requires
	host blob support (``hostmem`` and ``blob`` fields) and should be enabled
	using ``drm_native_context`` field. The ``hostmem`` field specifies the size
	of virtio-gpu host memory window. This is typically between 256M and 8G.

	.. parsed-literal::
	-device virtio-gpu-gl,hostmem=8G,blob=on,drm_native_context=on

	.. _drm: https://gitlab.freedesktop.org/virgl/virglrenderer/-/tree/main/src/drm

	.. list-table:: Linux Host Requirements
	:header-rows: 1

	* - Capability
	- Kernel Version
	- Libvirglrenderer Version
	* - OpenGL pass-through
	- Any Linux version compatible with QEMU if not using host blobs feature,
	Linux 6.13+ otherwise
	- 0.8.2+
	* - Vulkan pass-through
	- Linux 6.13+
	- 1.0.0+
	* - AMDGPU DRM native context
	- Linux 6.13+
	- 1.1.0+
	* - Freedreno DRM native context
	- Linux 6.4+
	- 1.0.0+
	* - Intel i915 DRM native context
	- Linux 6.13+
	- 1.3.0+
	* - Asahi DRM native context
	- `Downstream version`_ of Asahi Linux kernel
	- 1.2.0+
	* - Panfrost native context
	- Linux 6.13+
	- 1.3.0+

	.. _Downstream version: https://github.com/AsahiLinux/linux

	.. list-table:: Linux Guest Requirements
	:header-rows: 1

	* - Capability
	- Kernel Version
	- Mesa Version
	* - OpenGL pass-through
	- Any Linux version supporting virtio-gpu
	- 16.0.0+
	* - Vulkan pass-through
	- Linux 5.16+
	- 24.2.0+
	* - AMDGPU DRM native context
	- Linux 6.14+
	- 25.0.0+
	* - Freedreno DRM native context
	- Linux 6.14+
	- 23.1.0+
	* - Intel i915 DRM native context
	- Linux 6.14+
	- 26.1.0+
	* - Asahi DRM native context
	- Linux 6.14+
	- 24.2.0+
	* - Panfrost native context
	- Linux 6.14+
	- `mr36814`_

	.. _mr36814: https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/36814

	virtio-gpu rutabaga
	-------------------

	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.

	The crosvm book provides directions on how to build a `gfxstream-enabled
	rutabaga`_ and launch a `guest Wayland proxy`_.

	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 ``gfxstream-vulkan``
	and ``cross-domain`` for Linux guests. For Android guests, the experimental
	``x-gfxstream-gles`` and ``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.

	The ``wsi`` option can be set to ``surfaceless`` or ``headless``.
	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.

	.. parsed-literal::
	-device virtio-gpu-rutabaga,gfxstream-vulkan=on,cross-domain=on,
	hostmem=8G,wayland-socket-path=/tmp/nonstandard/mock_wayland.sock,
	wsi=headless

	.. _gfxstream: https://android.googlesource.com/platform/hardware/google/gfxstream/
	.. _Wayland display passthrough: https://www.youtube.com/watch?v=OZJiHMtIQ2M
	.. _gfxstream-enabled rutabaga: https://crosvm.dev/book/appendix/rutabaga_gfx.html
	.. _guest Wayland proxy: https://crosvm.dev/book/devices/wayland.html

	.. list-table:: Linux Host Requirements
	:header-rows: 1

	* - Capability
	- Kernel Version
	* - Vulkan+Wayland pass-through
	- Linux 6.13+

	.. list-table:: Linux Guest Requirements
	:header-rows: 1

	* - Capability
	- Kernel Version
	- Mesa Version
	* - Vulkan+Wayland pass-through
	- Linux 5.16+
	- 24.3.0+