Commit bcb32b69 authored by Daniel Vetter's avatar Daniel Vetter

drm/doc: Light drm-kms-helper.rst cleanup

- 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@chromium.org>
Reviewed-by: default avatarSean Paul <seanpaul@chromium.org>
Signed-off-by: default avatarDaniel Vetter <daniel.vetter@intel.com>
Link: http://patchwork.freedesktop.org/patch/msgid/1471034937-651-2-git-send-email-daniel.vetter@ffwll.ch
parent 62cacc79
...@@ -2,38 +2,45 @@ ...@@ -2,38 +2,45 @@
Mode Setting Helper Functions Mode Setting Helper Functions
============================= =============================
The plane, CRTC, encoder and connector functions provided by the drivers The DRM subsystem aims for a strong separation between core code and helper
implement the DRM API. They're called by the DRM core and ioctl handlers libraries. Core code takes care of general setup and teardown and decoding
to handle device state changes and configuration request. As userspace requests to kernel internal objects. Everything else is handled by a
implementing those functions often requires logic not specific to large set of helper libraries, which can be combined freely to pick and choose
drivers, mid-layer helper functions are available to avoid duplicating for each driver what fits, and avoid shared code where special behaviour is
boilerplate code. needed.
The DRM core contains one mid-layer implementation. The mid-layer This distinction between core code and helpers is especially strong in the
provides implementations of several plane, CRTC, encoder and connector modesetting code, where there's a shared userspace ABI for all drivers. This is
functions (called from the top of the mid-layer) that pre-process in contrast to the render side, where pretty much everything (with very few
requests and call lower-level functions provided by the driver (at the exceptions) can be considered optional helper code.
bottom of the mid-layer). For instance, the
:c:func:`drm_crtc_helper_set_config()` function can be used to There are a few areas these helpers can grouped into:
fill the :c:type:`struct drm_crtc_funcs <drm_crtc_funcs>`
set_config field. When called, it will split the set_config operation * Helpers to implement modesetting. The important ones here are the atomic
in smaller, simpler operations and call the driver to handle them. 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
To use the mid-layer, drivers call that would have been a great fit in the deprecated fbdev subsystem) there's
:c:func:`drm_crtc_helper_add()`, also the simple display pipe helpers.
:c:func:`drm_encoder_helper_add()` and
:c:func:`drm_connector_helper_add()` functions to install their * There's a big pile of helpers for handling outputs. First the generic bridge
mid-layer bottom operations handlers, and fill the :c:type:`struct helpers for handling encoder and transcoder IP blocks. Second the panel helpers
drm_crtc_funcs <drm_crtc_funcs>`, :c:type:`struct for handling panel-related information and logic. Plus then a big set of
drm_encoder_funcs <drm_encoder_funcs>` and :c:type:`struct helpers for the various sink standards (DisplayPort, HDMI, MIPI DSI). Finally
drm_connector_funcs <drm_connector_funcs>` structures with there's also generic helpers for handling output probing, and for dealing with
pointers to the mid-layer top API functions. Installing the mid-layer EDIDs.
bottom operation handlers is best done right after registering the
corresponding KMS object. * The last group of helpers concerns itself with the frontend side of a display
pipeline: Planes, handling rectangles for visibility checking and scissoring,
The mid-layer is not split between CRTC, encoder and connector flip queues and assorted bits.
operations. To use it, a driver must provide bottom functions for all of
the three KMS entities. 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 Atomic Modeset Helper Functions Reference
========================================= =========================================
...@@ -62,33 +69,27 @@ Atomic State Reset and Initialization ...@@ -62,33 +69,27 @@ Atomic State Reset and Initialization
.. kernel-doc:: drivers/gpu/drm/drm_atomic_helper.c .. kernel-doc:: drivers/gpu/drm/drm_atomic_helper.c
:export: :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 Legacy CRTC/Modeset Helper Functions Reference
============================================== ==============================================
.. kernel-doc:: drivers/gpu/drm/drm_crtc_helper.c .. kernel-doc:: drivers/gpu/drm/drm_crtc_helper.c
:export: :doc: overview
.. kernel-doc:: drivers/gpu/drm/drm_crtc_helper.c .. 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 .. kernel-doc:: include/drm/drm_simple_kms_helper.h
:doc: output probing helper overview :internal:
.. kernel-doc:: drivers/gpu/drm/drm_probe_helper.c .. kernel-doc:: drivers/gpu/drm/drm_simple_kms_helper.c
:export: :export:
.. kernel-doc:: drivers/gpu/drm/drm_simple_kms_helper.c
:doc: overview
fbdev Helper Functions Reference fbdev Helper Functions Reference
================================ ================================
...@@ -110,6 +111,36 @@ Framebuffer CMA Helper Functions Reference ...@@ -110,6 +111,36 @@ Framebuffer CMA Helper Functions Reference
.. kernel-doc:: drivers/gpu/drm/drm_fb_cma_helper.c .. kernel-doc:: drivers/gpu/drm/drm_fb_cma_helper.c
:export: :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 Display Port Helper Functions Reference
======================================= =======================================
...@@ -158,6 +189,15 @@ MIPI DSI Helper Functions Reference ...@@ -158,6 +189,15 @@ MIPI DSI Helper Functions Reference
.. kernel-doc:: drivers/gpu/drm/drm_mipi_dsi.c .. kernel-doc:: drivers/gpu/drm/drm_mipi_dsi.c
:export: :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 EDID Helper Functions Reference
=============================== ===============================
...@@ -176,18 +216,6 @@ Rectangle Utilities Reference ...@@ -176,18 +216,6 @@ Rectangle Utilities Reference
.. kernel-doc:: drivers/gpu/drm/drm_rect.c .. kernel-doc:: drivers/gpu/drm/drm_rect.c
:export: :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 HDMI Infoframes Helper Reference
================================ ================================
...@@ -202,59 +230,31 @@ libraries and hence is also included here. ...@@ -202,59 +230,31 @@ libraries and hence is also included here.
.. kernel-doc:: drivers/video/hdmi.c .. kernel-doc:: drivers/video/hdmi.c
:export: :export:
Plane Helper Reference Flip-work 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
Default bridge callback sequence .. kernel-doc:: include/drm/drm_flip_work.h
-------------------------------- :doc: flip utils
.. kernel-doc:: drivers/gpu/drm/drm_bridge.c .. kernel-doc:: include/drm/drm_flip_work.h
:doc: bridge callbacks :internal:
.. kernel-doc:: drivers/gpu/drm/drm_bridge.c .. kernel-doc:: drivers/gpu/drm/drm_flip_work.c
:export: :export:
Panel Helper Reference Plane Helper Reference
====================== ======================
.. kernel-doc:: include/drm/drm_panel.h .. kernel-doc:: drivers/gpu/drm/drm_plane_helper.c
:internal: :doc: overview
.. kernel-doc:: drivers/gpu/drm/drm_panel.c .. kernel-doc:: drivers/gpu/drm/drm_plane_helper.c
:export: :export:
.. kernel-doc:: drivers/gpu/drm/drm_panel.c Tile group
:doc: drm panel ==========
Simple KMS Helper Reference
===========================
.. kernel-doc:: include/drm/drm_simple_kms_helper.h
:internal:
.. kernel-doc:: drivers/gpu/drm/drm_simple_kms_helper.c # FIXME: This should probably be moved into a property documentation section
:export:
.. kernel-doc:: drivers/gpu/drm/drm_simple_kms_helper.c .. kernel-doc:: drivers/gpu/drm/drm_crtc.c
:doc: overview :doc: Tile group
...@@ -33,6 +33,9 @@ Primary Nodes, DRM Master and Authentication ...@@ -33,6 +33,9 @@ Primary Nodes, DRM Master and Authentication
.. kernel-doc:: include/drm/drm_auth.h .. kernel-doc:: include/drm/drm_auth.h
:internal: :internal:
Open-Source Userspace Requirements
==================================
Render nodes Render nodes
============ ============
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment