docs: Move kms abstractions to a separate file

Part-of: <https://gitlab.gnome.org/GNOME/mutter/-/merge_requests/3489>

doc/reference/meta/kms-abstractions.md

@@ -0,0 +1,85 @@
+Title: KMS abstraction
+
+The KMS abstraction consists of various building blocks for helping out with
+interacting with the various drm API's, enabling users to use a
+transactional API, aiming to hide all interaction with the underlying APIs.
+
+The subsystem defines two separate contexts, the "main" context, and the
+"impl" context. The main context is the context of which mutter as a whole
+runs in. It uses the main GLib main loop and main context and always runs in
+the main thread.
+
+The impl context is where all underlying API is being executed. While in the
+current state, it always runs in the main thread, the aim is to be able to
+execute the impl context in a dedicated thread.
+
+The public facing MetaKms API is always assumed to be executed from the main
+context.
+
+The KMS abstraction consists of the following public components:
+
+### `MetaKms`
+
+Main entry point; used by the native backend to create devices, post updates
+etc.
+
+### `MetaKmsDevice`
+
+A device (usually /dev/dri/cardN, where N being a number). Used to get KMS
+objects, such as connectors, CRTCs, planes, as well as basic meta data such
+as device path etc.
+
+### `MetaKmsCrtc`
+
+Represents a CRTC. It manages a representation of the current CRTC state,
+including current mode, coordinates, possible clones.
+
+### `MetaKmsConnector`
+
+Represents a connector, e.g. a display port connection. It also manages a
+representation of the current state, including meta data such as physical
+dimension of the connected, available modes, EDID, tile info etc. It also
+contains helper functions for configuration, as well as methods for adding
+configuration to a transaction (See `MetaKmsUpdate`).
+
+### `MetaKmsPlane`
+
+Represents a hardware plane. A plane is used to define the content of what
+should be presented on a CRTC. Planes can either be primary planes, used as
+a backdrop for CRTCs, overlay planes, and cursor planes.
+
+### `MetaKmsMode`
+
+Represents a mode a CRTC and connector can be configured with.
+Represents both modes directly derived from the devices, as well as
+fall back modes when the CRTC supports scaling.
+
+### `MetaKmsUpdate`
+
+A KMS transaction object, meant to be processed potentially atomically when
+posted. An update consists of plane assignments, mode sets and KMS object
+property entries. The user adds updates to the object, and then posts it via
+MetaKms. It will then be processed by the MetaKms backend (See
+`MetaKmsImpl`), potentially atomically. Each `MetaKmsUpdate` deals with
+updating a single device.
+
+There are also these private objects, without public facing API:
+
+### `MetaKmsImpl`
+
+The KMS impl context object, managing things in the impl context.
+
+### `MetaKmsImplDevice`
+
+An object linked to a `MetaKmsDevice`, but where it is executed in the impl
+context. It takes care of the updating of the various KMS object (CRTC,
+connector, ..) states.
+
+This is an abstract type, with currently `MetaKmsImplDeviceSimple`
+implementing mode setting and page flipping using legacy DRM API.
+
+### `MetaKmsPageFlip`
+
+A object representing a page flip. It's created when a page flip is queued,
+and contains information necessary to provide feedback to the one requesting
+the page flip.

doc/reference/meta/meta.toml.in

@@ -39,6 +39,7 @@ base_url = "https://gitlab.gnome.org/GNOME/mutter/-/blob/@vcs_tag@/"
 [extra]
 # The same order will be used when generating the index
 content_files = [
+  "kms-abstractions.md",
 ]
 content_images = [
   "logo.svg",