[02/20] drm/doc: Light drm-kms-helper.rst cleanup
diff mbox

Message ID 1470750091-16627-3-git-send-email-daniel.vetter@ffwll.ch
State New
Headers show

Commit Message

Daniel Vetter Aug. 9, 2016, 1:41 p.m. UTC
- 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

Comments

Sean Paul Aug. 9, 2016, 4:19 p.m. UTC | #1
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

Patch
diff mbox

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