[v5,9/9] docs/system: add basic virtio-gpu documentation

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

v4: - Incorporated suggestions by Akihiko Odaki

v5: - Removed pci suffix from examples
    - Verified that -device virtio-gpu-rutabaga works.  Strangely
      enough, I don't remember changing anything, and I remember
      it not working.  I did rebase to top of tree though.
    - Fixed meson examples in crosvm docs
 docs/system/device-emulation.rst   |   1 +
 docs/system/devices/virtio-gpu.rst | 113 +++++++++++++++++++++++++++++
 2 files changed, 114 insertions(+)
 create mode 100644 docs/system/devices/virtio-gpu.rst

Reviewed-by: Emmanouil Pitsidianakis <manos.pitsidianakis@linaro.org>

On Tue, 15 Aug 2023 03:35, Gurchetan Singh <gurchetansingh@chromium.org> wrote:
>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
>
>v4: - Incorporated suggestions by Akihiko Odaki
>
>v5: - Removed pci suffix from examples
>    - Verified that -device virtio-gpu-rutabaga works.  Strangely
>      enough, I don't remember changing anything, and I remember
>      it not working.  I did rebase to top of tree though.
>    - Fixed meson examples in crosvm docs
> docs/system/device-emulation.rst   |   1 +
> docs/system/devices/virtio-gpu.rst | 113 +++++++++++++++++++++++++++++
> 2 files changed, 114 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..8c5c708272
>--- /dev/null
>+++ b/docs/system/devices/virtio-gpu.rst
>@@ -0,0 +1,113 @@
>+..
>+   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.
>+
>+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.
>+
>+.. parsed-literal::
>+    -device virtio-gpu-gl
>+
>+.. _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.
>+
>+At least 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,capset_names=gfxstream-vulkan:cross-domain,
>+       hostmem=8G,wayland_socket_path=/tmp/nonstandard/mock_wayland.sock,
>+       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
>-- 
>2.41.0.694.ge786442a9b-goog
>
>