Commit 6aa10266 authored by Jonas Ådahl's avatar Jonas Ådahl Committed by Georges Basile Stavracas Neto

kms: Add high level code documentation

Document the high level components of the KMS abstraction.

GNOME/mutter#548
GNOME/mutter!525
parent 75dff3e7
......@@ -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;
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment