Move wayland section to its own chapter

[trhodes]

Summary

At the request of several, this patch will move (no content changes except section headers being added) the Wayland section from x11/_index.adoc to wayland/_index.adoc. The build works, and after some research, I was able to ensure that all chapter numbers will bump +1. This chapter will appear after the x11 chapter. After this is complete, we can go through some of the recommended changes and updates people have discussed in D32436. I just want one or two people to verify this is the correct method for creating a new chapter (something I was not prepared to do earlier).

Test Plan

"make run" and manual review in a browser.

[pauamma_gundo.com]

Given that chapter numbers apparently need to be bumped manually, this looks right at a glance, but I'm not confident enough (since I never added a chapter either) that there isn't a subtle hitch.

[2khramtsov_gmail.com]

Thank you for continuing your valuable effort to document Wayland ecosystem on FreeBSD.

I left some comments, but I didn't get much into the detail and didn't test the mentioned configurations, for now. I hope to get more time to continue improving Wayland documentation.
Some of the comments that I left are critical (e.g. NVIDIA support) and I would prefer to see them merged with a bit higher priority in order to avoid user confusion, e.g.:
https://www.reddit.com/r/freebsd/comments/udyrh7/nvidia_and_wayland_on_freebsd/

handbook/wayland/_index.adoc

53

new display server, but [...]

54–56

The most major change for a user is that Wayland is designed for every frame to be perfect, so no frame is present in intermediate state. This goal is achieved by Wayland server and clients (applications) negotiating Wayland surface (window) state, and Wayland compositor rendering the last consistent state. Wayland compositor doesn't render beyond the output (display) refresh rate (e.g. 30 Hz, 60 Hz, 120 Hz, 144 Hz, or variable refresh rate) unlike X11 where rendering is not synchronized with the display's refresh rate, resulting in visual tearing artifacts on X11, whereas Wayland presents the last frame per display refresh, resulting in visually perfect frames. Additionally, clients that render continuously (show animations) can use frame callbacks to render on demand by compositor, in order to save system resources when client is minimized, off-screen, or in any other state when continuous rendering isn't optimal. Performance can also be improved compared to X11, as nowadays modern applications don't use underlying X11 drawing primitives, so X11 is often odd and becomes overhead in the graphics pipeline. Wayland also provides easier use of modern zero-copy APIs such as dmabuf which are used in e.g. high performance video processing for high resolutions such as 4K and beyond.

57–58

Wayland also features better isolation by design. Communication between clients and compositor is based on Wayland protocol, which consists of interfaces which define the list of messages: requests, which are sent by client to the server, and events, which are sent by the server to client. Wayland compositor, which is granted permission to access evdev by seat daemon described below, dispatches events from seats, or groups of input devices (keyboard, mouse, or other events that can be handled via libinput), to appropriate Wayland clients. Additionally, clients cannot access other clients' surfaces or know their global position. This model provides improved security over X11 where state is global and accessible to any application with X11 socket access.

59–62

Wayland is state of the art display server maintained by various contributors, and its ecosystem is actively expanding. Graphical toolkits such as GTK3+, Qt 5 (with qt5-wayland package), SDL2, standalone Wayland clients such as multimedia/mpv, Web browsers such as www/firefox with WebRTC screen sharing via multimedia/pipewire with XDG portal, and WebKitGTK+ and GTK3+ based browsers have Wayland support, and this list is not exhausting, as many items on the https://arewewaylandyet.com/ and beyond are in the FreeBSD ports collection living in various categories, including Wayland's own category, wayland/. There is also a seamless compatibility layer for X11 software called XWayland, but the need for it will diminish over the time as more software gains Wayland support or becomes Wayland-only.

65–67

Wayland compositors have various backends to render frames on, including the DRM backend where Wayland compositor is launched via DRM enabled vt(4) console, or X11 and Wayland backends for Wayland-on-X11 or Wayland-on-Wayland nesting respectively.

DRM mode is supported on AMD and Intel GPUs via graphics/drm-kmod. NVIDIA graphics driver doesn't provide DRM enabled vt(4) console, thus only nesting is possible on NVIDIA GPUs, and the usability on NVIDIA is questionable.

74–75

AFAIK it was regressed sometime and wasn't fixed. No idea if it is the case now, I don't want to build KDE to test and I don't trust non-reproducible packages from pkg.FreeBSD.org.

93

DRM and evdev, or use "The seatd daemon helps manage [...]" instead below, or use the description in my comments above.

110–111

XDG_RUNTIME_DIR is concatenated with WAYLAND_DISPLAY to form the path to unix(4) socket used for Wayland transport method, and can be used as a path for shared memory for use with e.g. mmap(), so placing it on ZFS would be suboptimal, maybe suggest that tmpfs is the only acceptable option.

125

traditional -> legacy

182

Does swaylock require consolekit session nowadays when under DRM backend?

487–488

I don't think XWayland binds and listens a network socket, check yourself via e.g. sockstat -l -v6 (or v4).

557–558

Did I mention net/waypipe in the previous review?

572–573

I would prefer something like [::] (or "::" if wayvnc accepts only that for some reason) instead, as IPv4 is legacy and new deployments shouldn't use it. Besides, a warning that either 0.0.0.0 or [::] listen on every configured IP address on any interface and makes wayvnc accessible to the whole Internet would be nice.

580–581

TLS is hard to get right and might be wrong to describe, and I think ipsec(4) suits better, but fine, this is nitpicking.

[2khramtsov_gmail.com]

handbook/wayland/_index.adoc

131

Maybe mention dbus and seatd-launch, e.g. dbus enable and "seatd-launch dbus-run-session sway" ?

[2khramtsov_gmail.com]

I realized that I want to create a separate revision with my suggestions instead (planned sometime this month).

I went here because the initial revision was committed without addressing some of the older suggestions, and I thought that because it also wasn't properly closed, for any new comments I should not use it, and decided to put new comments here instead, wrongly.

[carlavilla]

I'll take this.
I'll back to you tomorrow. But seems ok!

[carlavilla]

Sorry for the delay.
For me is ok. Moving this to a new chapter I think is a good idea.
And since the content is the same. We can improve it in future commits.

[carlavilla]

Ok, I'm gonna commit this. I'm gonna add some aliases too to handle well the redirections and don't get a 404.

[carlavilla]

I made the commit.

Thanks for this. Can we move all the changes of the chapter to the other review?
I'm gonna close this one.