- Move the common vtable stuff to the top - Move "Tile Group" to a more appropriate heading level - Throw away the old intro for the crtc helpers (it's entirely stale, e.g. helpers have become modular years ago), and replace it with a general intro about the motivation behind helpers. - Reorder helpers to group them together a bit better, and explain that grouping in the intro. - Make sure the introductory DOC section is always first.
Signed-off-by: Daniel Vetter daniel.vetter@intel.com --- Documentation/gpu/drm-kms-helpers.rst | 208 +++++++++++++++++----------------- drivers/gpu/drm/drm_kms_helper.c | 66 +++++++++++ include/drm/drm_kms_helper.h | 30 +++++ 3 files changed, 200 insertions(+), 104 deletions(-) create mode 100644 drivers/gpu/drm/drm_kms_helper.c create mode 100644 include/drm/drm_kms_helper.h
diff --git a/Documentation/gpu/drm-kms-helpers.rst b/Documentation/gpu/drm-kms-helpers.rst index 0b302fedf1af..23458252f198 100644 --- a/Documentation/gpu/drm-kms-helpers.rst +++ b/Documentation/gpu/drm-kms-helpers.rst @@ -2,38 +2,45 @@ Mode Setting Helper Functions =============================
-The plane, CRTC, encoder and connector functions provided by the drivers -implement the DRM API. They're called by the DRM core and ioctl handlers -to handle device state changes and configuration request. As -implementing those functions often requires logic not specific to -drivers, mid-layer helper functions are available to avoid duplicating -boilerplate code. - -The DRM core contains one mid-layer implementation. The mid-layer -provides implementations of several plane, CRTC, encoder and connector -functions (called from the top of the mid-layer) that pre-process -requests and call lower-level functions provided by the driver (at the -bottom of the mid-layer). For instance, the -:c:func:`drm_crtc_helper_set_config()` function can be used to -fill the :c:type:`struct drm_crtc_funcs <drm_crtc_funcs>` -set_config field. When called, it will split the set_config operation -in smaller, simpler operations and call the driver to handle them. - -To use the mid-layer, drivers call -:c:func:`drm_crtc_helper_add()`, -:c:func:`drm_encoder_helper_add()` and -:c:func:`drm_connector_helper_add()` functions to install their -mid-layer bottom operations handlers, and fill the :c:type:`struct -drm_crtc_funcs <drm_crtc_funcs>`, :c:type:`struct -drm_encoder_funcs <drm_encoder_funcs>` and :c:type:`struct -drm_connector_funcs <drm_connector_funcs>` structures with -pointers to the mid-layer top API functions. Installing the mid-layer -bottom operation handlers is best done right after registering the -corresponding KMS object. - -The mid-layer is not split between CRTC, encoder and connector -operations. To use it, a driver must provide bottom functions for all of -the three KMS entities. +The DRM subsystem aims for a strong separation between core code and helper +libraries. Core code takes care of general setup and teardown and decoding +userspace requests to kernel internal objects. Everything else is handled by a +large set of helper libraries, which can be combined freely to pick and choose +for each driver what fits, and avoid shared code where special behaviour is +needed. + +This distinction between core code and helpers is especially strong in the +modesetting code, where there's a shared userspace ABI for all drivers. This is +in contrast to the render side, where pretty much everything (with very few +exceptions) can be considered optional helper code. + +There are a few areas these helpers can grouped into: + +* Helpers to implement modesetting. This important ones here are the atomic + helpers. Old drivers still often use the legacy CRTC helpers. They both share + the same set of common helper vtables. For really simple drivers (anything + that would have been a great fit in the deprecated fbdev subsystem) there's + also the simple display pipe helpers. + +* There's a big pile of helpers for handling outputs. Firs the generic bridge + helpers for handling encoder and transcoder IP blocks, and the panel helpers + for handling panel-related information and logic. Plus then a big set of + helpers for the various sink standards (DisplayPort, HDMI, MIPI DSI). Finally + there's also generic helpers for handling output probing, and for dealing with + EDIDs. + +* The last group of helpers concerns itself with the frontend side of a display + pipeline: Planes, handling rectangles for visibility checking and scissoring, + flip queues and assorted bits. + +Modeset Helper Reference for Common Vtables +=========================================== + +.. kernel-doc:: include/drm/drm_modeset_helper_vtables.h + :internal: + +.. kernel-doc:: include/drm/drm_modeset_helper_vtables.h + :doc: overview
Atomic Modeset Helper Functions Reference ========================================= @@ -62,33 +69,27 @@ Atomic State Reset and Initialization .. kernel-doc:: drivers/gpu/drm/drm_atomic_helper.c :export:
-Modeset Helper Reference for Common Vtables -=========================================== - -.. kernel-doc:: include/drm/drm_modeset_helper_vtables.h - :internal: - -.. kernel-doc:: include/drm/drm_modeset_helper_vtables.h - :doc: overview - Legacy CRTC/Modeset Helper Functions Reference ==============================================
.. kernel-doc:: drivers/gpu/drm/drm_crtc_helper.c - :export: + :doc: overview
.. kernel-doc:: drivers/gpu/drm/drm_crtc_helper.c - :doc: overview + :export:
-Output Probing Helper Functions Reference -========================================= +Simple KMS Helper Reference +===========================
-.. kernel-doc:: drivers/gpu/drm/drm_probe_helper.c - :doc: output probing helper overview +.. kernel-doc:: include/drm/drm_simple_kms_helper.h + :internal:
-.. kernel-doc:: drivers/gpu/drm/drm_probe_helper.c +.. kernel-doc:: drivers/gpu/drm/drm_simple_kms_helper.c :export:
+.. kernel-doc:: drivers/gpu/drm/drm_simple_kms_helper.c + :doc: overview + fbdev Helper Functions Reference ================================
@@ -110,6 +111,36 @@ Framebuffer CMA Helper Functions Reference .. kernel-doc:: drivers/gpu/drm/drm_fb_cma_helper.c :export:
+Bridges +======= + +Overview +-------- + +.. kernel-doc:: drivers/gpu/drm/drm_bridge.c + :doc: overview + +Default bridge callback sequence +-------------------------------- + +.. kernel-doc:: drivers/gpu/drm/drm_bridge.c + :doc: bridge callbacks + +.. kernel-doc:: drivers/gpu/drm/drm_bridge.c + :export: + +Panel Helper Reference +====================== + +.. kernel-doc:: include/drm/drm_panel.h + :internal: + +.. kernel-doc:: drivers/gpu/drm/drm_panel.c + :export: + +.. kernel-doc:: drivers/gpu/drm/drm_panel.c + :doc: drm panel + Display Port Helper Functions Reference =======================================
@@ -158,6 +189,15 @@ MIPI DSI Helper Functions Reference .. kernel-doc:: drivers/gpu/drm/drm_mipi_dsi.c :export:
+Output Probing Helper Functions Reference +========================================= + +.. kernel-doc:: drivers/gpu/drm/drm_probe_helper.c + :doc: output probing helper overview + +.. kernel-doc:: drivers/gpu/drm/drm_probe_helper.c + :export: + EDID Helper Functions Reference ===============================
@@ -176,18 +216,6 @@ Rectangle Utilities Reference .. kernel-doc:: drivers/gpu/drm/drm_rect.c :export:
-Flip-work Helper Reference -========================== - -.. kernel-doc:: include/drm/drm_flip_work.h - :doc: flip utils - -.. kernel-doc:: include/drm/drm_flip_work.h - :internal: - -.. kernel-doc:: drivers/gpu/drm/drm_flip_work.c - :export: - HDMI Infoframes Helper Reference ================================
@@ -202,59 +230,31 @@ libraries and hence is also included here. .. kernel-doc:: drivers/video/hdmi.c :export:
-Plane Helper Reference -====================== - -.. kernel-doc:: drivers/gpu/drm/drm_plane_helper.c - :export: - -.. kernel-doc:: drivers/gpu/drm/drm_plane_helper.c - :doc: overview - -Tile group ----------- - -.. kernel-doc:: drivers/gpu/drm/drm_crtc.c - :doc: Tile group - -Bridges -======= - -Overview --------- - -.. kernel-doc:: drivers/gpu/drm/drm_bridge.c - :doc: overview +Flip-work Helper Reference +==========================
-Default bridge callback sequence --------------------------------- +.. kernel-doc:: include/drm/drm_flip_work.h + :doc: flip utils
-.. kernel-doc:: drivers/gpu/drm/drm_bridge.c - :doc: bridge callbacks +.. kernel-doc:: include/drm/drm_flip_work.h + :internal:
-.. kernel-doc:: drivers/gpu/drm/drm_bridge.c +.. kernel-doc:: drivers/gpu/drm/drm_flip_work.c :export:
-Panel Helper Reference +Plane Helper Reference ======================
-.. kernel-doc:: include/drm/drm_panel.h - :internal: +.. kernel-doc:: drivers/gpu/drm/drm_plane_helper.c + :doc: overview
-.. kernel-doc:: drivers/gpu/drm/drm_panel.c +.. kernel-doc:: drivers/gpu/drm/drm_plane_helper.c :export:
-.. kernel-doc:: drivers/gpu/drm/drm_panel.c - :doc: drm panel - -Simple KMS Helper Reference -=========================== - -.. kernel-doc:: include/drm/drm_simple_kms_helper.h - :internal: +Tile group +==========
-.. kernel-doc:: drivers/gpu/drm/drm_simple_kms_helper.c - :export: +# FIXME: This should probably be moved into a property documentation section
-.. kernel-doc:: drivers/gpu/drm/drm_simple_kms_helper.c - :doc: overview +.. kernel-doc:: drivers/gpu/drm/drm_crtc.c + :doc: Tile group diff --git a/drivers/gpu/drm/drm_kms_helper.c b/drivers/gpu/drm/drm_kms_helper.c new file mode 100644 index 000000000000..127f574d29a4 --- /dev/null +++ b/drivers/gpu/drm/drm_kms_helper.c @@ -0,0 +1,66 @@ +/* + * Copyright (c) 2016 Intel Corporation + * + * Permission to use, copy, modify, distribute, and sell this software and its + * documentation for any purpose is hereby granted without fee, provided that + * the above copyright notice appear in all copies and that both that copyright + * notice and this permission notice appear in supporting documentation, and + * that the name of the copyright holders not be used in advertising or + * publicity pertaining to distribution of the software without specific, + * written prior permission. The copyright holders make no representations + * about the suitability of this software for any purpose. It is provided "as + * is" without express or implied warranty. + * + * THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, + * INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO + * EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY SPECIAL, INDIRECT OR + * CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, + * DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER + * TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE + * OF THIS SOFTWARE. + */ + +#include <drm/drm_kms_helper.h> +#include <drm/drm_crtc.h> +#include <drm/drm_fourcc.h> +#include <drm/drm_crtc_helper.h> +#include <drm/drm_fb_helper.h> +#include <drm/drm_plane_helper.h> +#include <drm/drm_atomic_helper.h> +#include <drm/drm_edid.h> + +/** + * DOC: aux kms helpers + * + * This helper library contains various one-off functions which don't really fit + * anywhere else in the DRM modeset helper library. + */ + +/** + * drm_helper_move_panel_connectors_to_head() - move panels to the front in the + * connector list + * @dev: drm device to operate on + * + * Some userspace presumes that the first connected connector is the main + * display, where it's supposed to display e.g. the login screen. For + * laptops, this should be the main panel. Use this function to sort all + * (eDP/LVDS) panels to the front of the connector list, instead of + * painstakingly trying to initialize them in the right order. + */ +void drm_helper_move_panel_connectors_to_head(struct drm_device *dev) +{ + struct drm_connector *connector, *tmp; + struct list_head panel_list; + + INIT_LIST_HEAD(&panel_list); + + list_for_each_entry_safe(connector, tmp, + &dev->mode_config.connector_list, head) { + if (connector->connector_type == DRM_MODE_CONNECTOR_LVDS || + connector->connector_type == DRM_MODE_CONNECTOR_eDP) + list_move_tail(&connector->head, &panel_list); + } + + list_splice(&panel_list, &dev->mode_config.connector_list); +} +EXPORT_SYMBOL(drm_helper_move_panel_connectors_to_head); diff --git a/include/drm/drm_kms_helper.h b/include/drm/drm_kms_helper.h new file mode 100644 index 000000000000..9f3ffb27c871 --- /dev/null +++ b/include/drm/drm_kms_helper.h @@ -0,0 +1,30 @@ +/* + * Copyright (c) 2016 Intel Corporation + * + * Permission to use, copy, modify, distribute, and sell this software and its + * documentation for any purpose is hereby granted without fee, provided that + * the above copyright notice appear in all copies and that both that copyright + * notice and this permission notice appear in supporting documentation, and + * that the name of the copyright holders not be used in advertising or + * publicity pertaining to distribution of the software without specific, + * written prior permission. The copyright holders make no representations + * about the suitability of this software for any purpose. It is provided "as + * is" without express or implied warranty. + * + * THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, + * INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO + * EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY SPECIAL, INDIRECT OR + * CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, + * DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER + * TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE + * OF THIS SOFTWARE. + */ + +#ifndef __DRM_KMS_HELPER_H__ +#define __DRM_KMS_HELPER_H__ + +#include <drm/drmP.h> + +extern void drm_helper_move_panel_connectors_to_head(struct drm_device *); + +#endif