From 6aa1026600c3b2bd085c96bace7b5855a8ceb325 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jonas=20=C3=85dahl?= <jadahl@gmail.com>
Date: Fri, 5 Apr 2019 15:32:41 +0200
Subject: [PATCH] kms: Add high level code documentation

Document the high level components of the KMS abstraction.

https://gitlab.gnome.org/GNOME/mutter/issues/548
https://gitlab.gnome.org/GNOME/mutter/merge_requests/525
---
 src/backends/native/meta-kms.c | 90 ++++++++++++++++++++++++++++++++++
 1 file changed, 90 insertions(+)

diff --git a/src/backends/native/meta-kms.c b/src/backends/native/meta-kms.c
index c13360a1d..976eae230 100644
--- a/src/backends/native/meta-kms.c
+++ b/src/backends/native/meta-kms.c
@@ -28,6 +28,96 @@
 #include "backends/native/meta-kms-update-private.h"
 #include "backends/native/meta-udev.h"
 
+/**
+ * SECTION:kms
+ * @short description: KMS abstraction
+ * @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.
+ *
+ * #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.
+ *
+ *
+ * There are also these private objects, without public facing API:
+ *
+ * #MetaKmsImpl:
+ *
+ * The KMS backend implementation, running in the impl context. #MetaKmsImpl
+ * itself is an abstract object, with potentially multiple implementations.
+ * Currently only #MetaKmsImplSimple exists.
+ *
+ * #MetaKmsImplSimple:
+ *
+ * A KMS backend implementation using the non-atomic drmMode* API. While it's
+ * interacted with using the transactional API, the #MetaKmsUpdate is processed
+ * non-atomically.
+ *
+ * #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.
+ *
+ * #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.
+ *
+ */
+
 typedef struct _MetaKmsCallbackData
 {
   MetaKmsCallback callback;