docs: add basic documentation for venus

It probably lacks some details but is a start at least.

Signed-off-by: Chia-I Wu <olvaffe@gmail.com>
Reviewed-by: Erik Faye-Lund <erik.faye-lund@collabora.com>
Part-of: <https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/10988>

2 files changed, 162 insertions, 0 deletions

diff --git a/docs/drivers/venus.rst b/docs/drivers/venus.rst
new file mode 100644
index 00000000000..9e67650e7fa
--- /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
+<https://gitlab.freedesktop.org/olv/venus-protocol>`__.  The renderer is
+hosted at `virglrenderer
+<https://gitlab.freedesktop.org/virgl/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
+  <https://github.com/google/security-research/security/advisories/GHSA-7wq5-phmq-m584>`__)
+
+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
+<https://gitlab.freedesktop.org/virgl/drm-misc-next/-/tree/context-init>`__
+kernel branch paired with `crosvm
+<https://chromium.googlesource.com/chromiumos/platform/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=<path-to-virtio_icd.x86_64.json>
+    $ 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
+<https://gitlab.freedesktop.org/virgl/drm-misc-next/-/tree/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<path-to-virglrenderer>/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 \
+       <path-to-bzImage>
+
+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
+<https://chromium.googlesource.com/chromiumos/third_party/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_<I915-or-your-driver> 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=<path-to-wayland-socket>`` 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=<path-to-locally-built-gl-driver> \
+       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 f3343b306ce..79571e07916 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