From nobody Thu Nov 28 16:42:55 2024 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=chromium.org ARC-Seal: i=1; a=rsa-sha256; t=1691547119; cv=none; d=zohomail.com; s=zohoarc; b=Golv5rGdl0CPm+B9cIyS2SeFmcatk6kprUDBQVvRGlBsvSRToG9hg73O2jC7yYiYVaLbh7+mi1MYUSGA28Ggzuo7LZDuJ8nwVI48uDciJNKHhSE9bvLtyqUZFKDAiZ8KK1AQq8eI7+Q5Ph35QQkpCt6WdPCVWFTs+bDi0raVmGI= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1691547119; h=Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=qeu387dMLSZurhsCi2O3wE5RNhv8cyyTZxpT0Ii8FDQ=; b=iW1Wr5l3ag3LW1LjI/0D0jzAHzi95jMt7Lb+TbIxbDTSN9aGv0MJnPPHQC3smCvxmrglH4i5z1CyyZb2Y2PQsebhbwOVaqd02B4LIJ0BrB97iK2Qmetv3pFqVJdFCuExvfZF4E48eY7bgLYDnpwv1F71fY6ye3gy2YWb1LS5sYg= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=none dis=none) Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1691547119815268.49435050784314; Tue, 8 Aug 2023 19:11:59 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1qTYfX-00077y-T7; Tue, 08 Aug 2023 22:11:27 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1qTYfW-00077M-08 for qemu-devel@nongnu.org; Tue, 08 Aug 2023 22:11:26 -0400 Received: from mail-pf1-x431.google.com ([2607:f8b0:4864:20::431]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1qTYfT-000180-Ri for qemu-devel@nongnu.org; Tue, 08 Aug 2023 22:11:25 -0400 Received: by mail-pf1-x431.google.com with SMTP id d2e1a72fcca58-686bc261111so4537982b3a.3 for ; Tue, 08 Aug 2023 19:11:23 -0700 (PDT) Received: from gurchetansingh0.mtv.corp.google.com ([2620:15c:a7:2:a5a2:f074:e7af:41fe]) by smtp.gmail.com with ESMTPSA id a16-20020aa78650000000b00687494a59bfsm8681887pfo.61.2023.08.08.19.11.21 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 08 Aug 2023 19:11:21 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=chromium.org; s=google; t=1691547082; x=1692151882; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=qeu387dMLSZurhsCi2O3wE5RNhv8cyyTZxpT0Ii8FDQ=; b=en8n2SU0KWQveHK3OsSZJh4N9DxtS+cHa3qp6FIFB9Fg3uZkb6uJCrmgJiRdzigr47 z1MYApln4haeECxo1KnBUwSPgz/Z+4RT42VCIy1eXgPdjL2gGZogmsUIRH8jkSqC9q8B YxQb6xaPuh9LcCYkFvamFTBlIUHPNsmP0iPBM= X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20221208; t=1691547082; x=1692151882; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=qeu387dMLSZurhsCi2O3wE5RNhv8cyyTZxpT0Ii8FDQ=; b=HK+orlKTYYSN4MnrjAkF65NACgeUnbFJ1Rh3Jpb1P76oKmE2VoYADXA36N0Gvdk4dM +gFU/7ow62OhzgpI8HvIZ2irZ8zT7NnSL6CMB+o6wLsqJ+z2x/QYglOF44VOFFyNbYo6 s6sei8U71WBS/oVHQZ5HoXJfs8fCNafYgmIRxOFEzVDmqnnS74sv8gZIgSDbdj0ZLwi5 BvEFbV3MMtc6KeLGW/Oo3B52c8gEOifu1vffr+2111Oxj0fB5wodhAOK3F1bYIDNtqew 7+ODgavE2JoJWjfw/4EczJUSGnXREa5Gsmg+0XD63F64gW/aUsleZVmZg5FTlJOQLoci vhCA== X-Gm-Message-State: AOJu0YxYS/gAi9sx3WKls6kgwuNUsNkLCLFDHWJanOxBJB9nX3WOcGiY SpfDHIJmjpm6JnZDwDCFxNDKbJuAbUS4MQAVRLbk3w== X-Google-Smtp-Source: AGHT+IHQKlJTExob7AP1uyaM5m3QsqazAFZPQXAtJWtKHpJfGabKao5M1Lrym2GOoy+nAXPcVRuAlA== X-Received: by 2002:a05:6a20:551a:b0:13c:3b5e:a12a with SMTP id ko26-20020a056a20551a00b0013c3b5ea12amr1107213pzb.34.1691547082266; Tue, 08 Aug 2023 19:11:22 -0700 (PDT) From: Gurchetan Singh To: qemu-devel@nongnu.org Cc: marcandre.lureau@redhat.com, kraxel@redhat.com, akihiko.odaki@gmail.com, ray.huang@amd.com, alex.bennee@linaro.org, shentey@gmail.com, hi@alyssa.is, ernunes@redhat.com Subject: [PATCH v4 9/9] docs/system: add basic virtio-gpu documentation Date: Tue, 8 Aug 2023 19:11:08 -0700 Message-Id: <20230809021108.674-10-gurchetansingh@chromium.org> X-Mailer: git-send-email 2.31.0 In-Reply-To: <20230809021108.674-1-gurchetansingh@chromium.org> References: <20230809021108.674-1-gurchetansingh@chromium.org> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Received-SPF: pass client-ip=2607:f8b0:4864:20::431; envelope-from=gurchetansingh@chromium.org; helo=mail-pf1-x431.google.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: qemu-devel-bounces+importer=patchew.org@nongnu.org X-ZohoMail-DKIM: pass (identity @chromium.org) X-ZM-MESSAGEID: 1691547121446100007 Content-Type: text/plain; charset="utf-8" This adds basic documentation for virtio-gpu. Suggested-by: Akihiko Odaki Signed-off-by: Gurchetan Singh --- 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-emulatio= n.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/virti= o-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 +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +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=3Dgfxstream-vulkan:cross-= domain, + hostmem=3D8G,wayland_socket_path=3D/tmp/nonstandard/mock_wayland.so= ck, + wsi=3Dheadless + +.. _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/g= fxstream/ +.. _Wayland display passthrough: https://www.youtube.com/watch?v=3DOZJiHMt= IQ2M +.. _gfxstream-enabled rutabaga: https://crosvm.dev/book/appendix/rutabaga_= gfx.html +.. _guest Wayland proxy: https://crosvm.dev/book/devices/wayland.html --=20 2.41.0.640.ga95def55d0-goog