From 978d4659862e19d547ff295eb43430caf9e27e92 Mon Sep 17 00:00:00 2001 From: Chia-I Wu Date: Tue, 25 May 2021 13:11:25 -0700 Subject: [PATCH] docs: add basic documentation for venus It probably lacks some details but is a start at least. Signed-off-by: Chia-I Wu Reviewed-by: Erik Faye-Lund Part-of: --- docs/drivers/venus.rst | 161 +++++++++++++++++++++++++++++++++++++++++++++++++ docs/index.rst | 1 + 2 files changed, 162 insertions(+) create mode 100644 docs/drivers/venus.rst diff --git a/docs/drivers/venus.rst b/docs/drivers/venus.rst new file mode 100644 index 0000000..9e67650 --- /dev/null +++ b/docs/drivers/venus.rst @@ -0,0 +1,161 @@ +Virtio-GPU Venus +================ + +Venus is a Virtio-GPU protocol for Vulkan command serialization. The protocol +definition and codegen are hosted at `venus-protocol +`__. The renderer is +hosted at `virglrenderer +`__. + +The protocol is still under development. This driver and the renderer are +both considered experimental. + +Requirements +------------ + +The Venus renderer requires + +- Vulkan 1.1 +- ``VK_EXT_external_memory_dma_buf`` +- ``VK_EXT_image_drm_format_modifier`` +- ``VK_EXT_queue_family_foreign`` + +from the host driver. However, it violates the spec in some places currently +and also relies on implementation-defined behaviors in others. It is not +expected to work on all drivers meeting the requirements. It has only been +tested with + +- ANV 21.1 or later +- RADV 21.1 or later (the host kernel must have + ``CONFIG_TRANSPARENT_HUGEPAGE`` disabled because of this `KVM issue + `__) + +The Venus driver requires supports for + +- ``VIRTGPU_PARAM_RESOURCE_BLOB`` +- ``VIRTGPU_PARAM_HOST_VISIBLE`` +- ``VIRTGPU_PARAM_CROSS_DEVICE`` +- ``VIRTGPU_PARAM_CONTEXT_INIT`` + +from the virtio-gpu kernel driver, unless vtest is used. Currently, this +means the `context-init +`__ +kernel branch paired with `crosvm +`__. + +vtest +----- + +The simplest way to test Venus is to use virglrenderer's vtest server. To +build virglrenderer with Venus support and to start the vtest server, + +.. code-block:: console + + $ git clone https://gitlab.freedesktop.org/virgl/virglrenderer.git + $ cd virglrenderer + $ meson out -Dvenus-experimental=true + $ ninja -C out + $ ./out/vtest/virgl_test_server --venus + +In another shell, + +.. code-block:: console + + $ export VK_ICD_FILENAMES= + $ export VN_DEBUG=vtest + $ vulkaninfo + $ vkcube + +If the host driver of the system is not new enough, it is a good idea to build +the host driver as well when building the Venus driver. Just remember to set +:envvar:`VK_ICD_FILENAMES` when starting the vtest server so that the vtest +server finds the locally built host driver. + +Virtio-GPU +---------- + +Because the driver requires ``VIRTGPU_PARAM_CONTEXT_INIT`` from the virtio-gpu +kernel driver, one must make sure the guest kernel includes the changes from +the `context-init +`__ +branch. + +To build crosvm, + +.. code-block:: console + + $ mkdir crosvm + $ cd crosvm + $ wget https://storage.googleapis.com/git-repo-downloads/repo + $ chmod +x repo + $ ./repo init -g crosvm -u https://chromium.googlesource.com/chromiumos/manifest.git + $ ./repo sync + $ cd src/platform/crosvm + $ RUSTFLAGS="-L/out/src" cargo build \ + --features "x virgl_renderer virgl_renderer_next default-no-sandbox" + +Note that crosvm must be built with ``default-no-sandbox`` or started with +``--disable-sandbox`` in this setup. + +This is how one might want to start crosvm + +.. code-block:: console + + $ sudo LD_LIBRARY_PATH=<...> VK_ICD_FILENAMES=<...> ./target/debug/crosvm run \ + --gpu vulkan=true \ + --display-window-keyboard \ + --display-window-mouse \ + --host_ip 192.168.0.1 \ + --netmask 255.255.255.0 \ + --mac 12:34:56:78:9a:bc \ + --rwdisk disk.qcow2 \ + -p root=/dev/vda1 \ + + +assuming a working system is installed to partition 1 of ``disk.qcow2``. +``sudo`` or ``CAP_NET_ADMIN`` is needed to set up the TAP network device. + +Virtio-GPU and Virtio-WL +------------------------ + +In this setup, the guest userspace uses Xwayland and a special Wayland +compositor to connect guest X11/Wayland clients to the host Wayland +compositor, using Virtio-WL as the transport. This setup is more tedious, but +that should hopefully change over time. + +For now, the guest kernel must be built from the ``chromeos-5.10`` branch of +the `Chrome OS kernel +`__. crosvm +should also be built with ``wl-dmabuf`` feature rather than ``x`` feature. + +To build minigbm and to enable minigbm support in virglrenderer, + +.. code-block:: console + + $ git clone https://chromium.googlesource.com/chromiumos/platform/minigbm + $ cd minigbm + $ CFLAGS=-DDRV_ OUT=out DESTDIR=out/install make install + $ cd ../virglrenderer + $ meson configure out -Dminigbm_allocation=true + $ ninja -C out + +Make sure a host Wayland compositor is running. Replace +``--display-window-keyboard --display-window-mouse`` by +``--wayland-sock=`` when starting crosvm. + +In the guest, build and start sommelier, the special Wayland compositor, + +.. code-block:: console + + $ git clone https://chromium.googlesource.com/chromiumos/platform2 + $ cd platform2/vm_tools/sommelier + $ meson out -Dxwayland_path=/usr/bin/Xwayland -Dxwayland_gl_driver_path=/usr/lib/dri + $ ninja -C out + $ sudo chmod 777 /dev/wl0 + $ ./out/sommelier -X --glamor + --xwayland-gl-driver-path= \ + sleep infinity + +sommelier requires ``xdg-shell-unstable-v6`` rather than the stable +``xdg-shell`` from the host compositor. One must make sure the host +compositor still supports the older extension. diff --git a/docs/index.rst b/docs/index.rst index f3343b3..79571e0 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -91,6 +91,7 @@ Linux, FreeBSD, and other operating systems. drivers/panfrost drivers/v3d drivers/vc4 + drivers/venus drivers/vmware-guest drivers/zink -- 2.7.4