[PATCH 02/21] drm/doc: Light drm-kms-helper.rst cleanup
Daniel Vetter
daniel.vetter at ffwll.ch
Fri Aug 12 20:48:38 UTC 2016
- 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.
v2:
- Remove bogus files accidentally added (Sean).
- Spelling fixes (Sean).
Cc: Sean Paul <seanpaul at chromium.org>
Signed-off-by: Daniel Vetter <daniel.vetter at intel.com>
---
Documentation/gpu/drm-kms-helpers.rst | 208 +++++++++++++++++-----------------
Documentation/gpu/drm-uapi.rst | 3 +
2 files changed, 107 insertions(+), 104 deletions(-)
diff --git a/Documentation/gpu/drm-kms-helpers.rst b/Documentation/gpu/drm-kms-helpers.rst
index 0b302fedf1af..34f755bc9133 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. The 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. First the generic bridge
+ helpers for handling encoder and transcoder IP blocks. Second 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/Documentation/gpu/drm-uapi.rst b/Documentation/gpu/drm-uapi.rst
index 536bf3eaadd4..94876938aef3 100644
--- a/Documentation/gpu/drm-uapi.rst
+++ b/Documentation/gpu/drm-uapi.rst
@@ -33,6 +33,9 @@ Primary Nodes, DRM Master and Authentication
.. kernel-doc:: include/drm/drm_auth.h
:internal:
+Open-Source Userspace Requirements
+==================================
+
Render nodes
============
--
2.8.1
More information about the dri-devel
mailing list