On Tue, Aug 9, 2016 at 9:41 AM, Daniel Vetter daniel.vetter@ffwll.ch wrote:

• 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

s/This important/The important/

• 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

s/Firs/First,/

• helpers for handling encoder and transcoder IP blocks, and the panel helpers

s/, and/. Second, /

I'm taking a bit of creative license, assuming this is what you're trying to say :)

• 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)
  

How about DSI?

I wonder if this logic should be pulled out into its own helper drm_helper_is_connector_internal, or similar. Seems like something that is likely to get sprinkled around and hardish to keep current.

•                   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

2.8.1

---

Intel-gfx mailing list Intel-gfx@lists.freedesktop.org https://lists.freedesktop.org/mailman/listinfo/intel-gfx