From 3e28ed0f5f91c25f4dcad0edc02f25b77a7213d3 Mon Sep 17 00:00:00 2001 From: Alexandre Courbot Date: Thu, 17 Mar 2022 15:39:08 +0900 Subject: [PATCH] mdbook: add instructions for enabling and running Wayland It is now relatively easy to build and run sommelier against a regular Linux guest, and doing so enables the powerful feature of being able to show guest Wayland clients on a compositor running on the host. Document the process for those interested in doing it. BUG=None TEST=mdbook serve TEST=./tools/fmt --check Change-Id: I45b99243481ee66c1e88e597669a219a4e5b9376 Reviewed-on: https://chromium-review.googlesource.com/c/chromiumos/platform/crosvm/+/3531694 Reviewed-by: Daniel Verkamp Reviewed-by: Keiichi Watanabe Reviewed-by: Dennis Kempin Tested-by: kokoro Commit-Queue: Alexandre Courbot --- .../book/src/running_crosvm/advanced_usage.md | 96 +++++++++++++++++-- 1 file changed, 89 insertions(+), 7 deletions(-) diff --git a/docs/book/src/running_crosvm/advanced_usage.md b/docs/book/src/running_crosvm/advanced_usage.md index 660a708f96..8c069cab3d 100644 --- a/docs/book/src/running_crosvm/advanced_usage.md +++ b/docs/book/src/running_crosvm/advanced_usage.md @@ -130,14 +130,95 @@ will run in a jailed child process of crosvm. The appropriate minijail seccomp p present either in `/usr/share/policy/crosvm` or in the path specified by the `--seccomp-policy-dir` argument. The sandbox can be disabled for testing with the `--disable-sandbox` option. -## Virtio Wayland +## Wayland forwarding to host -Virtio Wayland support requires special support on the part of the guest and as such is unlikely to -work out of the box unless you are using a Chrome OS kernel along with a `termina` rootfs. +If you have a Wayland compositor running on your host, it is possible to display and control guest +applications from it. This requires: -To use it, ensure that the `XDG_RUNTIME_DIR` enviroment variable is set and that the path -`$XDG_RUNTIME_DIR/wayland-0` points to the socket of the Wayland compositor you would like the guest -to use. +- A guest kernel version 5.16 or above with `CONFIG_DRM_VIRTIO_GPU` enabled, +- The `sommelier` Wayland proxy in your guest image. + +This section will walk you through the steps needed to get this to work. + +### Guest kernel requirements + +Wayland support on crosvm relies on virtio-gpu contexts, which have been introduced in Linux 5.16. +Make sure your guest kernel is either this version or a more recent one, and that +`CONFIG_DRM_VIRTIO_GPU` is enabled in your kernel configuration. + +### Crosvm requirements + +Wayland forwarding requires the GPU feature and any non-2d virtio-gpu mode to be enabled, so pass +them to your `cargo build` or `cargo run` command, e.g: + +```sh +cargo build --features "gpu,virgl_renderer,virgl_renderer_next" +``` + +### Building sommelier + +[Sommelier] is a proxy Wayland compositor that forwards the Wayland protocol from a guest to a +compositor running on the host through the guest GPU device. As it is not a standard tool, we will +have to build it by ourselves. It is recommended to do this from the guest +[with networking enabled](./example_usage.md#add-networking-support). + +Clone Chrome OS' `platform2` repository, which contains the source for sommelier: + +```sh +git clone https://chromium.googlesource.com/chromiumos/platform2 +``` + +Go into the sommelier directory and prepare for building: + +```sh +cd platform2/vm_tools/sommelier/ +meson setup build -Dwith_tests=false +``` + +This setup step will check for all libraries required to build sommelier. If some are missing, +install them using your guest's distro package manager and re-run `meson setup` until it passes. + +Finally, build sommelier and install it: + +```sh +meson compile -C build +sudo meson install -C build +``` + +This last step will put the `sommelier` binary into `/usr/local/bin`. + +### Running guest Wayland apps + +Crosvm can connect to a running Wayland server (e.g. [weston]) on the host and forward the protocol +from all Wayland guest applications to it. To enable this you need to know the socket of the Wayland +server running on your host - typically it would be `$XDG_RUNTIME_DIR/wayland-0`. + +Once you have confirmed the socket, create a GPU device and enable forwarding by adding the +`--gpu --wayland-sock $XDG_RUNTIME_DIR/wayland-0` arguments to your crosvm command-line. + +You can now run Wayland clients through sommelier, e.g: + +```sh +sommelier --virtgpu-channel weston-terminal +``` + +Or + +```sh +sommelier --virtgpu-channel gedit +``` + +Applications started that way should appear on and be controllable from the Wayland server running +on your host. + +The `--virtgpu-channel` option is currently necessary for sommelier to work with the setup of this +document, but will likely not be required in the future. + +If you have `Xwayland` installed in the guest you can also run X applications: + +```sh +sommelier -X --xwayland-path=/usr/bin/Xwayland xeyes +``` ## GDB Support @@ -170,10 +251,11 @@ The following are crosvm's default arguments and how to override them. - 1 virtual CPU (set with `-c`) - no block devices (set with `-r`, `-d`, or `--rwdisk`) - no network (set with `--host_ip`, `--netmask`, and `--mac`) -- virtio wayland support if `XDG_RUNTIME_DIR` enviroment variable is set (disable with `--no-wl`) - only the kernel arguments necessary to run with the supported devices (add more with `-p`) - run in multiprocess mode (run in single process mode with `--disable-sandbox`) - no control socket (set with `-s`) [gdb remote serial protocol]: https://sourceware.org/gdb/onlinedocs/gdb/Remote-Protocol.html [kernel documentation]: https://www.kernel.org/doc/html/latest/dev-tools/gdb-kernel-debugging.html +[sommelier]: https://chromium.googlesource.com/chromiumos/platform2/+/master/vm_tools/sommelier +[weston]: https://github.com/wayland-project/weston