From 52c64d44fcea8c930a3f5b62e8d7639aaddfbff8 Mon Sep 17 00:00:00 2001 From: Bilal Elmoussaoui Date: Fri, 5 Jan 2024 09:47:23 +0100 Subject: [PATCH] docs: Move kms abstractions to a separate file Part-of: --- doc/reference/meta/kms-abstractions.md | 85 ++++++++++++++++++++++++ doc/reference/meta/meta.toml.in | 1 + src/backends/native/meta-kms.c | 92 -------------------------- 3 files changed, 86 insertions(+), 92 deletions(-) create mode 100644 doc/reference/meta/kms-abstractions.md diff --git a/doc/reference/meta/kms-abstractions.md b/doc/reference/meta/kms-abstractions.md new file mode 100644 index 000000000..2883fb080 --- /dev/null +++ b/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. diff --git a/doc/reference/meta/meta.toml.in b/doc/reference/meta/meta.toml.in index 3aec9f462..d0e6d22ce 100644 --- a/doc/reference/meta/meta.toml.in +++ b/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", diff --git a/src/backends/native/meta-kms.c b/src/backends/native/meta-kms.c index 8e03adde5..87be05bd9 100644 --- a/src/backends/native/meta-kms.c +++ b/src/backends/native/meta-kms.c @@ -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,