From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.lore.kernel.org (Postfix) with ESMTPS id 9CA1CC0015E for ; Tue, 15 Aug 2023 15:14:59 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1qVvkF-0006lI-4L; Tue, 15 Aug 2023 11:14:07 -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 1qVvkD-0006l3-AK for qemu-devel@nongnu.org; Tue, 15 Aug 2023 11:14:05 -0400 Received: from mail-wr1-x42d.google.com ([2a00:1450:4864:20::42d]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1qVvkB-0002QM-53 for qemu-devel@nongnu.org; Tue, 15 Aug 2023 11:14:05 -0400 Received: by mail-wr1-x42d.google.com with SMTP id ffacd0b85a97d-307d58b3efbso4801984f8f.0 for ; Tue, 15 Aug 2023 08:14:02 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; t=1692112440; x=1692717240; h=content-transfer-encoding:mime-version:message-id:in-reply-to :references:user-agent:subject:cc:to:from:date:from:to:cc:subject :date:message-id:reply-to; bh=wWeCd/oI3iPfKRZCTSGeT5KxGhzuc83RvaYougqokuM=; b=iz15PObzF9vHqnEgUT6RphKOtO+34jqQr/meFfOk2ZYWILgbS36lmiNrSlBST/Gy4e guAFEAqVNwuStshypyZekoPn5dPwUdey4h/l656MnTPBXxRT7HlHSGyaesItNdqDz2Fh goQRsnb8EljseLfcZ7vT7JYiPwIQwbD1bNZ/OZ4DmE9ifEfhHwVMAkeswLNAmuzj1ufY eLpgi8Roq3N/h/RAzM7KLYLDv//VpjVRvd/v2PyesDFlY66nUHK4lCaZGZaQ01Bw8Arj DQFnSwChoVlXogFMbg2qtqi71JZD+R0NmHlRgL+vW2PQIC/xsS3kcrDg9WLHu9DEF5sF 2e5g== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20221208; t=1692112440; x=1692717240; h=content-transfer-encoding:mime-version:message-id:in-reply-to :references:user-agent:subject:cc:to:from:date:x-gm-message-state :from:to:cc:subject:date:message-id:reply-to; bh=wWeCd/oI3iPfKRZCTSGeT5KxGhzuc83RvaYougqokuM=; b=RA3+uL2Zey8S9g9s9UBBy4dIGtkwYvemrsbMAy3W218N2Indbg4wzrGVfg0O7iRFP4 XaIWhHYHLFYKoA6vZva52W3V87RGHvRs4tsNc/HA4VpfWg7XK3baH+LMKt1B6z6CkMjJ j35w9g9S1eONN9HQEyNMQolLoRFeYCSBzlPGLuQx1smlJ0XvHcsp+CWcy9BWd3tmSzTc ON5Xqmq7eQvIArCikvhniMvPVgmAxYN07h6foHaVXuUUPRmWUC3GaYaKzimEaha2Umpl 2vFWJLYB0IpmReM52fPPfox4cgGH9twLb92SxK211XevxvicdESrHWK/4/ILN6akpDeR Z05A== X-Gm-Message-State: AOJu0YxPRAeiCYZCIIdt3juMDFBf926DNAPKX0nVmvIGh5LcDiPOIVf/ 8Pq3orbFbppmmsBUqNtZxsU2zxQk1zhtwvw0+b8= X-Google-Smtp-Source: AGHT+IGo2jZ+iTG5WxqL7AlwqeSLfXOr5Sd9rP8qLmYaBfJBP7ZlnWtrc/Ebfeey0UbtnuKo0JwGdA== X-Received: by 2002:adf:f64c:0:b0:319:6997:942e with SMTP id x12-20020adff64c000000b003196997942emr7183443wrp.8.1692112439965; Tue, 15 Aug 2023 08:13:59 -0700 (PDT) Received: from meli.delivery (adsl-200.109.242.225.tellas.gr. [109.242.225.200]) by smtp.gmail.com with ESMTPSA id l2-20020a5d4bc2000000b003198d274208sm305350wrt.86.2023.08.15.08.13.59 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 15 Aug 2023 08:13:59 -0700 (PDT) Date: Tue, 15 Aug 2023 18:06:38 +0300 From: Manos Pitsidianakis To: qemu-devel@nongnu.org, Gurchetan Singh Cc: marcandre.lureau@redhat.com, akihiko.odaki@gmail.com, dmitry.osipenko@collabora.com, ray.huang@amd.com, alex.bennee@linaro.org, ernunes@redhat.com, hi@alyssa.is, shentey@gmail.com Subject: Re: [PATCH v5 9/9] docs/system: add basic virtio-gpu documentation User-Agent: meli 0.7.3 References: <20230815003526.631-1-gurchetansingh@chromium.org> <20230815003526.631-10-gurchetansingh@chromium.org> In-Reply-To: <20230815003526.631-10-gurchetansingh@chromium.org> Message-ID: MIME-Version: 1.0 Content-Transfer-Encoding: 8bit Content-Type: text/plain; charset=utf-8; format=flowed Received-SPF: pass client-ip=2a00:1450:4864:20::42d; envelope-from=manos.pitsidianakis@linaro.org; helo=mail-wr1-x42d.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, 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+qemu-devel=archiver.kernel.org@nongnu.org Sender: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Reviewed-by: Emmanouil Pitsidianakis On Tue, 15 Aug 2023 03:35, Gurchetan Singh wrote: >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 > >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 > >