docs: move Mir documentation from Discourse (#3311)

The Mir documentation from https://mir-server.io/docs needs moving into
readthedocs.

Once this is released we'll create redirects and edit the Discourse
topics to include links to the new locations.

Author: AlanGriffiths

doc/sphinx/custom_conf.py

@@ -87,7 +87,7 @@
     # Change to the discourse instance you want to be able to link to
     # using the :discourse: metadata at the top of a file
     # (use an empty value if you don't want to link)
-    'discourse': 'https://discourse.ubuntu.com/c/mir/15',
+    'discourse': 'https://discourse.ubuntu.com/',
 
     # Change to the Mattermost channel you want to link to
     # (use an empty value if you don't want to link)
@@ -255,3 +255,6 @@
 # Mermaid
 mermaid_version = "10.5.0"
 mermaid_d3_zoom = True
+
+# MyST
+myst_heading_anchors = 3

doc/sphinx/explanation/architecture.md

@@ -4,12 +4,6 @@ This document introduces the architecture of *Mir* at a high-level.
 ## Audience
 This document is intended to provide contributors to *Mir* an overview of *Mir*'s systems. It is *not* intended to guide compositor authors.
 
-## Index
-- [APIs for compositor authors](#apis-for-compositor-authors)
-- [The Mir Engine](#the-mir-engine)
-- [Platforms](#platforms)
-- [Supporting Libraries](#supporting-libraries)
-
 ## APIs for compositor authors
 ```{mermaid} high_level_diagram.mmd
 ```

doc/sphinx/explanation/dialog_540p.gif

@@ -2,11 +2,17 @@
 These pages provide additional detail about a number of aspects related to using Mir.
 
 - [Architecture](architecture): an overview of Mir's architecture for contributors
+- [Graphics support](mir-graphics-support): what's required to run Mir compositors
+- [What is Wayland anyway?](ok-so-what-is-this-wayland-thing-anyway): so what is it?
+- [Windowing paradigms](window-positions-under-wayland): how are windows managed?
 - [Component reports](component_reports): information on Mir's debug and performance reporting infrastructure
 
 ```{toctree}
 :hidden:
 
 architecture
+mir-graphics-support
+ok-so-what-is-this-wayland-thing-anyway
+window-positions-under-wayland
 component_reports
 ```

doc/sphinx/explanation/index.md

@@ -0,0 +1,85 @@
+---
+discourse: 13185
+---
+
+# Mir graphics support
+
+This document describes the requirements for running Mir.
+
+---
+
+Mir supports graphics and input “platforms” by using modules loadable at runtime. This means that applications built with Mir can run across a range of graphics stacks.
+
+There are Mir platforms supplied with Mir and the potential to develop more. There is also one platform we know of developed by a third party.
+
+The most widely used and tested platform is “mesa-kms” which works with the Mesa collection of open-source graphics drivers. That’s used on Intel-graphics based desktops and a variety of SBCs and other devices.
+
+## Summary list of current Mir graphics platforms
+
+Platform|Status|Description
+--|--|--
+gbm-kms|Released|Works with any driver providing KMS, `libgbm` and an EGL supporting [EGL_WL_bind_wayland_display](https://www.khronos.org/registry/EGL/extensions/WL/EGL_WL_bind_wayland_display.txt). The open-source Mesa drivers are the obvious example, but other drivers supporting these interfaces should work - for example, the binary MALI drivers provided by ARM have been tested on some devices.
+x11|Released|Provides “Mir-on-X11” primarily for development.
+eglstream-kms|Released|Works with proprietary Nvidia drivers.
+wayland|Released|Provides “Mir-on-Wayland” both for nested compositors and for development.
+android|Released|3rd party (UBports) works with a libhybris container for Android drivers. (Typically for phone hardware with Android-only drivers.)
+dispmanx|Released|Works with Broadcom proprietary DispmanX API.
+
+Each of these platforms depends on having the corresponding kernel and userspace drivers installed on the system. On startup Mir will “probe” the system for support of the above and select the best supported platform.
+
+## Choosing hardware and drivers
+
+When configuring a system for use with Mir it is not only necessary to check the hardware and drivers for compatibility with Mir, but also with the application software.
+
+For example, if the application software uses 3D or video acceleration, then that needs to be supported by the application (possibly through a supporting library) on the selected drivers and hardware. It is very possible that the support differs between the open-source drivers and the proprietary ones. Video decoding, in particular, varies a lot between graphics stacks.
+
+There’s a further complication in that Mir expects applications to use Wayland and some features on some drivers don’t work with Wayland. (An example is that the  intel-vaapi-driver for Ubuntu 18.04 doesn’t work with Wayland. That is fixed in more recent versions, but may need to be addressed for core18 snaps.)
+
+Also, there are applications that do not support Wayland directly. These can be supported with Xwayland - a program that translates from X11 to Wayland for the application. But that leads to further limitations as the GL acceleration support through Xwayland depends upon the graphics drivers. It works with Intel on Mesa, but beyond that it is patchy.
+
+## Some hardware examples
+
+### RPi 3
+
+GPU: VideoCore IV
+
+Mesa open-source graphics stack|Proprietary driver
+--|--
+VC4 - open source kernel/mesa stack.|Dispmanx - Broadcom proprietary(ish) stack.
+Mir works, and is tested on this.|Mir works, not yet incorporated into CI lab testing
+Supports GL.|Requires out-of-tree patches to https://github.com/raspberrypi/userland to enable 3D and video decode clients.
+Does not support OMX.<br/>May support some video encode/decode via mmal interface. This is apparently slower than OMX.|Potentially higher performance (particularly OMX for video decode)
+As a mesa/gbm-based platform, would expect 3D to work in XWayland.<br/>Mmal may work in XWayland.|As a non-mesa/gbm platform would likely not have 3D (or video decode) in XWayland.
+
+### i.MX6
+GPU: Vivante GC something ([varies by model](https://en.wikipedia.org/wiki/I.MX#i.MX_6_series))
+
+Mesa open-source graphics stack|Proprietary driver
+--|--
+Etnaviv - Full open-source stack, using standard KMS/dma-buf/gbm interfaces. Reverse-engineered.<br/>_As it’s using a full open-source stack, this would be easiest to support._|Vivante - proprietary driver.
+Mir would use same platform as on the desktop - gbm-kms.<br/> _We've tested the Boundary Devices i.MX6 on classic Ubuntu. Ubuntu Core would require some enablement work (adding the etnaviv driver)._|Would require writing a Mir platform (this is clearly possible; there are patches for Weston to support vivante)
+Supports 3D (mesa GL) + video decoding (CODA v4l2)|Supports 3D + video decoding
+Performance may be an issue (for example, https://github.com/Igalia/meta-webkit/issues/13)|Performance may be better; supported by downstream projects (again, cf: https://github.com/Igalia/meta-webkit/wiki/i.MX6)
+Notably - the open source stack should provide 3D acceleration (and potentially video acceleration) in XWayland.|Support for 3D in XWayland is unknown; would likely require significant out-of-tree patches.
+
+### i.MX8
+GPU: Vivante GC7000
+Mesa open-source graphics stack|Proprietary driver
+--|--
+Etnaviv - Full open-source stack, using standard KMS/dma-buf/gbm interfaces. Reverse-engineered.|Vivante - proprietary driver.
+Same comments as etnaviv on i.MX6 apply, but the GPU is newer and the driver support is likewise newer; there may be more missing features/bugs than i.MX6 support.|same comments as i.MX6. <br/>_It’s likely that a Mir vivante platform would work on both i.MX6 and i.MX8; likewise, there is apparently Weston support (again, in the form of out-of-tree patches)_
+Looks like there might not be open-source video decode support (cf: https://community.nxp.com/thread/489829#comment-1160206). Unknown whether we could interface the IMX bits with the etnaviv DRM bits.|Proprietary video decode solution.
+
+## Driver requirements
+
+Different Mir platforms require different features of the underlying driver stack. The features needed to enable a given Mir platform are:
+
+### gbm-kms
+
+The gbm-kms platform requires a DRM device node with KMS support, a `libgbm` implementation for buffer allocation, and an EGL implementation supporting at least [EGL_KHR_platform_gbm](https://www.khronos.org/registry/EGL/extensions/KHR/EGL_KHR_platform_gbm.txt) (or the equivalent [EGL_MESA_platform_gbm](https://www.khronos.org/registry/EGL/extensions/MESA/EGL_MESA_platform_gbm.txt) extension) and [EGL_WL_bind_wayland_display](https://www.khronos.org/registry/EGL/extensions/WL/EGL_WL_bind_wayland_display.txt).
+
+Optionally, the EGL implementation can support [EGL_EXT_image_dma_buf_import](https://www.khronos.org/registry/EGL/extensions/EXT/EGL_EXT_image_dma_buf_import.txt), [EGL_EXT_image_dma_buf_import_modifiers](https://www.khronos.org/registry/EGL/extensions/EXT/EGL_EXT_image_dma_buf_import_modifiers.txt), and use the [zwp_linux_dmabuf_unstable_v1](https://gitlab.freedesktop.org/wayland/wayland-protocols/-/blob/master/unstable/linux-dmabuf/linux-dmabuf-unstable-v1.xml) Wayland protocol for client buffer transfer. Support for this was added in Mir 2.3. Composite-bypass support depends on this implementation. Some future performance improvements, such as overlay plane usage, are likely to require this support from the driver stack.
+
+### eglstream-kms
+
+The eglstream-kms platform requires a DRM device node with Atomic KMS support and an EGL implementation supporting [EGL_EXT_platform_base](https://www.khronos.org/registry/EGL/extensions/EXT/EGL_EXT_platform_base.txt), [EGL_EXT_platform_device](https://www.khronos.org/registry/EGL/extensions/EXT/EGL_EXT_platform_device.txt), [EGL_EXT_device_base](https://www.khronos.org/registry/EGL/extensions/EXT/EGL_EXT_device_base.txt), [EGL_EXT_device_drm](https://www.khronos.org/registry/EGL/extensions/EXT/EGL_EXT_device_drm.txt), and [EGL_EXT_output_base](https://www.khronos.org/registry/EGL/extensions/EXT/EGL_EXT_output_base.txt).

doc/sphinx/explanation/mir-graphics-support.md

@@ -0,0 +1,65 @@
+---
+discourse: 8484
+---
+
+# OK, so what is this Wayland thing anyway?
+
+**Or: things are complicated. Let's see if one more explanation will incrementally reduce the Internet's Wrongness™**
+
+We've recently (ok, recently-ish) released [Mir 1.0](https://github.com/MirServer/mir/releases/tag/v1.0.0) with usable Wayland support. Yay!
+
+That brought a bunch of publicity, including on [LWN](https://lwn.net/Articles/766178/). Some of the comments there and elsewhere betray a misunderstanding about what Wayland *is* (and is not), and this still occasionally comes up in ``#wayland``, so I'll dust off an old blog post, polish up the rusty bits, and see if I can make this clearer for people again! 
+
+I'll give a run-down as to what the various projects in this space are and aim to do, throwing in X11 as a reference point.
+
+## Wayland, Mir, and X - different projects, with different goals
+
+### X11, and X.org
+
+Everyone's familiar with their friendly neighbourhood X server. This is what we've currently got as the default desktop Linux display server. For the purposes of this blog post, X consists of:
+
+#### The X11 protocol
+
+You're all familiar with the X11 protocol, right? This gentle beast specifies how to talk to an X server - both the binary format of the messages you'll send and receive, and what you can expect the server to do with any given message (the semantics). There are also plenty of protocol extensions; new messages to make the server do new things, like handle more than one monitor in a non-stupid way.
+
+#### The X11 client libraries
+
+No-one actually fiddles with X by sending raw binary data down a socket; they use the client libraries - the modern XCB, or the boring old Xlib (also known as ``libX11.so.6``). They do the boring work of throwing binary data at the server and present the client with a more civilised view of the X server, one where you can just ``XOpenDisplay(NULL)`` and start doing stuff.
+
+Actually, the above is a bit of a lie. Almost all the time people don't even use XCB or Xlib, they use toolkits such as GTK+ or Qt, and *they* use XLib or XCB.
+
+#### The Xorg server
+
+This would be the bit most obviously associated with X - the one, the only, the X.org X server! This is the actual ``/usr/bin/X`` display server we all know and love. Although there are other implementations of X11, this is all you'll ever see on the free desktop. Or on OS X, for that matter.
+
+So that's our baseline stack - a protocol, one or more client libraries, a display server implementation. How about Wayland and Mir?
+
+### Wayland
+
+
+#### The Wayland protocol
+
+The Wayland protocol is, like the X11 protocol, a definition of the binary data you can expect to send and receive over a Wayland socket, and the semantics associated with those binary bits. This is handled a bit differently to X11; the protocol is specified in XML, which is processed by a scanner and turned into C code. There is a binary protocol, and you can *technically* implement that protocol without using the ``wayland-scanner``-generated code, but since the Wayland EGL platform is defined in terms of the ``wl_display*`` structure from ``libwayland`` your implementation will need to be ABI compatible with the existing implementation in order for 3D accelerated clients to work.
+
+Also different from X11 is that everything's treated as an extension - you deal with all the interfaces in the core protocol the same way as you deal with any extensions you create. And you create a lot of extensions - for example, the core protocol doesn't have any buffer-passing mechanism other than SHM, so there's an extension for drm buffers in Mesa. Likewise, the NVIDIA drivers define their own internal protocol and a protocol for the compositor to support. The Weston reference compositor also has a bunch of extensions, both for ad-hoc things like the compositor<->desktop-shell interface, and for things like XWayland.
+
+#### The Wayland client library
+
+Or ``libwayland``. A bit like XCB and Xlib, this is basically just an IPC library. Unlike XCB and Xlib it can also used by a Wayland server for server→client communication. Also unlike XCB and Xlib, it's programmatically generated from the protocol definition. It's quite a nice IPC library, really. Like XCB and Xlib, you're not really expected to use this, anyway; you're expected to use a toolkit like Qt or GTK+, and EGL + your choice of Khronos drawing API if you want to be funky.
+There's also a library for reading X cursor themes in there.
+
+#### The Wayland server?
+
+This is where it diverges; there *is no* Wayland server in the sense that there's an Xorg server. There's Weston, the reference compositor, which is growing ``libweston`` to do some custom shell work and is used in various places. There's ``mutter``, the GNOME window manager which has grown a Wayland server implementation. Likewise, there's ``kwin``, KDE's window manager that grew a Wayland server implementation. There's also a swathe of lesser-known display-server-compositor-window-manager projects, like [sway](https://swaywm.org/).
+
+Of course, there's also now anything based on Mir ☺. [Unity8](https://unity8.io/) and [EGMDE](https://github.com/AlanGriffiths/egmde) are both now Wayland servers!
+
+Desktop environments are expected to write their own Wayland server, using the protocol and client libraries, and they have.
+
+### Mir
+
+And so we get to Mir.
+
+Where the Wayland libraries are all about IPC, Mir is about producing a library to do the drudge work of a display-server-compositor-window-manager-thing, so in this way it's more like Xorg than Wayland.
+
+Mir *does* still have a (not-guaranteed-stable) protocol and client library in ``libmirclient`` - the Wayland server implementation is an *additional* client frontend to Mir's core - but ``libmirclient`` is deprecated and we will not be pursuing further development of it. Supporting the standard desktop Wayland window management extensions means much less work for the Mir team - we only need to focus on the Mir code itself, not *also* on an EGL platform + associated Mesa patches and GTK+ patches and Qt patches and SDL patches and…

doc/sphinx/explanation/ok-so-what-is-this-wayland-thing-anyway.md

@@ -0,0 +1,60 @@
+---
+discourse: 29925
+---
+
+# Window positions under Wayland
+
+## Preamble
+
+Design is all about balance, and the design of graphical user interfaces has a lot of interests to be balanced. In the context of Wayland, the principle interested parties are the designer of the compositor/window manager/shell [server] and the designer of the application toolkit/application [client]. Wayland is the "language" these two parties use to communicate.
+
+A [recent thread](https://www.mail-archive.com/[email protected]/msg41597.html) on the wayland-devel mailing list highlighted once again that these interests are not identical. The thread focuses on the placement of windows and that is what I want to address here.
+
+## The designers
+
+For the designer of a server it is clear that applications ought to be "well behaved" and not be allowed to place windows in arbitrary positions. There are even security concerns about placing windows to intercept input such as passwords. And only the server can provide consistent window behaviours across multiple applications and toolkits.
+
+For the designer of a client it is clear that the toolkit is best placed to decide where windows are best placed. And only the client can provide consistent window behaviours across multiple servers and operating systems.
+
+## The conflict
+
+Both sides have a point that they should be "in control", but clearly that isn't going to happen.
+
+Legacy windowing systems such as X11 allowed clients complete freedom, and the issues that caused were among the motivations for doing things differently in Wayland.
+
+Throughout the design of Wayland the approach has been for the client to make requests and the server to make the final decisions.
+
+Obviously, that approach leads to frustration on the part of designers of clients as they are losing some of the flexibility they are accustomed to.
+
+## The balance
+
+Although a lot of freedom is indeed being lost, when looking at applications in the real world they only use a small fraction of that and for some specific cases. That's not surprising, as they are supporting some visual "idioms" that users recognise because they are shared across applications.
+
+1. Regular or "top level" windows
+![regular_540p|690x388](regular_540p.gif)
+These are handled by `xdg-shell`'s `xdg_toplevel`.
+
+2. Dialog windows
+![dialog_540p|690x388](dialog_540p.gif)
+These are handled by `xdg-shell`'s `xdg_toplevel` with the "parent" set.
+
+3. Menu and Popup windows
+![popup_540p|690x388](popup_540p.gif)
+These are handled by `xdg-shell`'s `xdg_popup` with a "grab"
+
+4. Tooltip and hover windows
+![tip_540p|690x388](tip_540p.gif)
+These are handled by `xdg-shell`'s `xdg_popup`.
+
+5. Satellite and toolbox windows
+![sattelite_540p|690x388](satellite_540p.gif)
+These are not currently handled by a Wayland extension, but could be added in a way consistent with the support for other window types.
+
+## Conclusion
+
+While client developers (of applications and toolkits) may be surprised that they can't set absolute geometry there are a number of objections to allowing it:
+1. preventing placement of windows to interfere with elements of the shell such as docks;
+2. allowing for how the shell is laid out (docs, multi-screen display walls, etc);
+3. no need for application to know how its own windows are laid out
+
+The approach taken by Wayland supports most of the windowing idioms recognised by users and can be extended to cover more without allowing clients complete freedom.