diff mbox series

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

Message ID 20230809021108.674-10-gurchetansingh@chromium.org (mailing list archive)
State New, archived
Headers show
Series gfxstream + rutabaga_gfx | expand

Commit Message

Gurchetan Singh Aug. 9, 2023, 2:11 a.m. UTC 
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

 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

Comments

Akihiko Odaki Aug. 9, 2023, 5:18 a.m. UTC | #1 
On 2023/08/09 11:11, Gurchetan Singh 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
> 
>   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..d56524270d
> --- /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.

I think it's better to omit -pci.

By the way you are not adding the aliases for Rutabaga so please do so. 
You can find the table in: softmmu/qdev-monitor.c

> +
> +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.
> +
> +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-pci,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

The build procedure looks almost good, but a command for building gfxstream:
meson -Ddefault_library=static build/

This results in a warning:
WARNING: Running the setup command as `meson [options]` instead of 
`meson setup [options]` is ambiguous and deprecated.

The same goes for the command for guest-side libraries.

> +.. _guest Wayland proxy: https://crosvm.dev/book/devices/wayland.html
Gurchetan Singh Aug. 10, 2023, 1:11 a.m. UTC | #2 
On Tue, Aug 8, 2023 at 10:18 PM Akihiko Odaki <akihiko.odaki@gmail.com>
wrote:

> On 2023/08/09 11:11, Gurchetan Singh 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
> >
> >   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..d56524270d
> > --- /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.
>
> I think it's better to omit -pci.
>

Are you suggesting to use "-device virtio-gpu-rutabaga" or "-device
virtio-gpu-gl" in the examples?  Or "-device virtio-gpu-rutabaga-device" or
"-device virtio-gpu-gl-device"?  The former I believe wouldn't launch, and
the examples should ideally be directly applicable to a user.


>
> By the way you are not adding the aliases for Rutabaga so please do so.
> You can find the table in: softmmu/qdev-monitor.c
>

I don't follow this comment.  Isn't "-device virtio-gpu-rutabaga-pci"
(along with "-device virtio-gpu-rutabaga-device") an alias for the rutabaga
device?  Where would the alias be placed in the doc (we don't explicitly
list aliases for other devices either), outside the "..parsed-literal::"
launch command?


>
> > +
> > +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.
> > +
> > +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-pci,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
>
> The build procedure looks almost good, but a command for building
> gfxstream:
> meson -Ddefault_library=static build/
>
> This results in a warning:
> WARNING: Running the setup command as `meson [options]` instead of
> `meson setup [options]` is ambiguous and deprecated.
>
> The same goes for the command for guest-side libraries.
>
> > +.. _guest Wayland proxy: https://crosvm.dev/book/devices/wayland.html
>
Akihiko Odaki Aug. 10, 2023, 6:55 a.m. UTC | #3 
On 2023/08/10 10:11, Gurchetan Singh wrote:
> 
> 
> On Tue, Aug 8, 2023 at 10:18 PM Akihiko Odaki <akihiko.odaki@gmail.com 
> <mailto:akihiko.odaki@gmail.com>> wrote:
> 
>     On 2023/08/09 11:11, Gurchetan Singh wrote:
>      > This adds basic documentation for virtio-gpu.
>      >
>      > Suggested-by: Akihiko Odaki <akihiko.odaki@daynix.com
>     <mailto:akihiko.odaki@daynix.com>>
>      > Signed-off-by: Gurchetan Singh <gurchetansingh@chromium.org
>     <mailto: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
>      >
>      >   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..d56524270d
>      > --- /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.
> 
>     I think it's better to omit -pci.
> 
> 
> Are you suggesting to use "-device virtio-gpu-rutabaga" or "-device 
> virtio-gpu-gl" in the examples?  Or "-device virtio-gpu-rutabaga-device" 
> or "-device virtio-gpu-gl-device"?  The former I believe wouldn't 
> launch, and the examples should ideally be directly applicable to a user.
> 
> 
>     By the way you are not adding the aliases for Rutabaga so please do so.
>     You can find the table in: softmmu/qdev-monitor.c
> 
> 
> I don't follow this comment.  Isn't "-device virtio-gpu-rutabaga-pci" 
> (along with "-device virtio-gpu-rutabaga-device") an alias for the 
> rutabaga device?  Where would the alias be placed in the doc (we don't 
> explicitly list aliases for other devices either), outside the 
> "..parsed-literal::" launch command?

virtio-gpu-gl should work, and you need add an alias definition to get 
virtio-gpu-rutabaga work.

Your documentation already says:
 > Without these suffixes, the platform default will be chosen.

You should confirm what you say in the documentation and fix the 
documentation or code if something is wrong.
Gurchetan Singh Aug. 10, 2023, 5:54 p.m. UTC | #4 
On Wed, Aug 9, 2023 at 11:55 PM Akihiko Odaki <akihiko.odaki@gmail.com>
wrote:

> On 2023/08/10 10:11, Gurchetan Singh wrote:
> >
> >
> > On Tue, Aug 8, 2023 at 10:18 PM Akihiko Odaki <akihiko.odaki@gmail.com
> > <mailto:akihiko.odaki@gmail.com>> wrote:
> >
> >     On 2023/08/09 11:11, Gurchetan Singh wrote:
> >      > This adds basic documentation for virtio-gpu.
> >      >
> >      > Suggested-by: Akihiko Odaki <akihiko.odaki@daynix.com
> >     <mailto:akihiko.odaki@daynix.com>>
> >      > Signed-off-by: Gurchetan Singh <gurchetansingh@chromium.org
> >     <mailto: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
> >      >
> >      >   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..d56524270d
> >      > --- /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.
> >
> >     I think it's better to omit -pci.
> >
> >
> > Are you suggesting to use "-device virtio-gpu-rutabaga" or "-device
> > virtio-gpu-gl" in the examples?  Or "-device virtio-gpu-rutabaga-device"
> > or "-device virtio-gpu-gl-device"?  The former I believe wouldn't
> > launch, and the examples should ideally be directly applicable to a user.
> >
> >
> >     By the way you are not adding the aliases for Rutabaga so please do
> so.
> >     You can find the table in: softmmu/qdev-monitor.c
> >
> >
> > I don't follow this comment.  Isn't "-device virtio-gpu-rutabaga-pci"
> > (along with "-device virtio-gpu-rutabaga-device") an alias for the
> > rutabaga device?  Where would the alias be placed in the doc (we don't
> > explicitly list aliases for other devices either), outside the
> > "..parsed-literal::" launch command?
>
> virtio-gpu-gl should work, and you need add an alias definition to get
> virtio-gpu-rutabaga work.
>

I see the problem: virtio-gpu-gl as a device works, but virtio-gpu-rutabaga
doesn't.  But the aliases for the gl device and rutabaga device are the
same in softmmu/qdev-monitor.c?

    { "virtio-gpu-gl-device", "virtio-gpu-gl", QEMU_ARCH_VIRTIO_MMIO },
    { "virtio-gpu-gl-pci", "virtio-gpu-gl", QEMU_ARCH_VIRTIO_PCI },
    { "virtio-gpu-rutabaga-device", "virtio-gpu-rutabaga",
      QEMU_ARCH_VIRTIO_MMIO },
    { "virtio-gpu-rutabaga-pci", "virtio-gpu-rutabaga",
QEMU_ARCH_VIRTIO_PCI },

What else needs to be added?


> Your documentation already says:
>  > Without these suffixes, the platform default will be chosen.
>
> You should confirm what you say in the documentation and fix the
> documentation or code if something is wrong.
diff mbox series

Patch

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..d56524270d
--- /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.
+
+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-pci,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