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 <dverkamp@chromium.org>
Reviewed-by: Keiichi Watanabe <keiichiw@chromium.org>
Reviewed-by: Dennis Kempin <denniskempin@google.com>
Tested-by: kokoro <noreply+kokoro@google.com>
Commit-Queue: Alexandre Courbot <acourbot@chromium.org>

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