| Message ID | 20230803235502.373-10-gurchetansingh@google.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | gfxstream + rutabaga_gfx | expand |
On 2023/08/04 8:55, Gurchetan Singh wrote: > From: Gurchetan Singh <gurchetansingh@chromium.org> > > This adds basic documentation for virtio-gpu. > > Suggested-by: Akihiko Odaki <akihiko.odaki@daynix.com> > Signed-off-by: Gurchetan Singh <gurchetansingh@chromium.org> > > --- > v2: - Incorporated suggestions by Akihiko Odaki > - Listed the currently supported capset_names (Bernard) > > v3: - Incorporated suggestions by Akihiko Odaki and Alyssa Ross > > docs/system/device-emulation.rst | 1 + > docs/system/devices/virtio-gpu.rst | 115 +++++++++++++++++++++++++++++ > 2 files changed, 116 insertions(+) > create mode 100644 docs/system/devices/virtio-gpu.rst > > diff --git a/docs/system/device-emulation.rst b/docs/system/device-emulation.rst > index 4491c4cbf7..1167f3a9f2 100644 > --- a/docs/system/device-emulation.rst > +++ b/docs/system/device-emulation.rst > @@ -91,6 +91,7 @@ Emulated Devices > devices/nvme.rst > devices/usb.rst > devices/vhost-user.rst > + devices/virtio-gpu.rst > devices/virtio-pmem.rst > devices/vhost-user-rng.rst > devices/canokey.rst > diff --git a/docs/system/devices/virtio-gpu.rst b/docs/system/devices/virtio-gpu.rst > new file mode 100644 > index 0000000000..2b8ecdac32 > --- /dev/null > +++ b/docs/system/devices/virtio-gpu.rst > @@ -0,0 +1,115 @@ > +.. > + SPDX-License-Identifier: GPL-2.0 > + > +virtio-gpu > +========== > + > +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 > +``CONFIG_DRM_VIRTIO_GPU`` option. > + > +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. > + > +This document uses the PCI interface in examples. > + > +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-pci > + > +.. _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. > + > +.. parsed-literal:: > + -device virtio-gpu-gl-pci > + > +.. _Gallium3D: https://www.freedesktop.org/wiki/Software/gallium/ > +.. _virglrenderer: https://gitlab.freedesktop.org/virgl/virglrenderer/ > + > +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. > + > +Atleast one capset (see colon separated ``capset_names`` below) must be "At least". > +specified when starting the device. The currently supported > +``capset_names`` are ``gfxstream-vulkan`` and ``cross-domain`` on Linux > +guests. For Android guests, ``gfxstream-gles`` is 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-pci,capset_names=gfxstream-vulkan:cross-domain, > + hostmem=8G,wayland_socket_path="$XDG_RUNTIME_DIR/$WAYLAND_DISPLAY", You will no longer want to specify: wayland_socket_path="$XDG_RUNTIME_DIR/$WAYLAND_DISPLAY" > + wsi=headless > + > +.. _rutabaga_gfx: https://github.com/google/crosvm/blob/main/rutabaga_gfx/ffi/src/include/rutabaga_gfx_ffi.h > +.. _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
diff --git a/docs/system/device-emulation.rst b/docs/system/device-emulation.rst index 4491c4cbf7..1167f3a9f2 100644 --- a/docs/system/device-emulation.rst +++ b/docs/system/device-emulation.rst @@ -91,6 +91,7 @@ Emulated Devices devices/nvme.rst devices/usb.rst devices/vhost-user.rst + devices/virtio-gpu.rst devices/virtio-pmem.rst devices/vhost-user-rng.rst devices/canokey.rst diff --git a/docs/system/devices/virtio-gpu.rst b/docs/system/devices/virtio-gpu.rst new file mode 100644 index 0000000000..2b8ecdac32 --- /dev/null +++ b/docs/system/devices/virtio-gpu.rst @@ -0,0 +1,115 @@ +.. + SPDX-License-Identifier: GPL-2.0 + +virtio-gpu +========== + +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 +``CONFIG_DRM_VIRTIO_GPU`` option. + +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. + +This document uses the PCI interface in examples. + +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-pci + +.. _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. + +.. parsed-literal:: + -device virtio-gpu-gl-pci + +.. _Gallium3D: https://www.freedesktop.org/wiki/Software/gallium/ +.. _virglrenderer: https://gitlab.freedesktop.org/virgl/virglrenderer/ + +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. + +Atleast one capset (see colon separated ``capset_names`` below) must be +specified when starting the device. The currently supported +``capset_names`` are ``gfxstream-vulkan`` and ``cross-domain`` on Linux +guests. For Android guests, ``gfxstream-gles`` is 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-pci,capset_names=gfxstream-vulkan:cross-domain, + hostmem=8G,wayland_socket_path="$XDG_RUNTIME_DIR/$WAYLAND_DISPLAY", + wsi=headless + +.. _rutabaga_gfx: https://github.com/google/crosvm/blob/main/rutabaga_gfx/ffi/src/include/rutabaga_gfx_ffi.h +.. _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