mirror of
https://github.com/brl/mutter.git
synced 2024-11-25 01:20:42 -05:00
docs: Move kms abstractions to a separate file
Part-of: <https://gitlab.gnome.org/GNOME/mutter/-/merge_requests/3489>
This commit is contained in:
Bilal Elmoussaoui
Marge Bot
parent
00b4d4c4bc
commit
52c64d44fc
85
doc/reference/meta/kms-abstractions.md
Normal file
85
doc/reference/meta/kms-abstractions.md
Normal file
@ -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.
|
||||
@ -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",
|
||||
|
||||
@ -31,98 +31,6 @@
|
||||
|
||||
#include "meta-private-enum-types.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.
|
||||
*
|
||||
* #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.
|
||||
*
|
||||
*/
|
||||
|
||||
enum
|
||||
{
|
||||
RESOURCES_CHANGED,
|
||||
|
||||
Loading…
Reference in New Issue
Block a user