Commit 3150c7d0 authored by Daniel Vetter's avatar Daniel Vetter

drm: Docbook integration and over sections for all the new helpers

In all cases the text requires that new drivers are converted to the
atomic interfaces.

v2: Add overview for state handling.

v3: Review from Sean: Some spelling fixes and drop the misguided
hunk to remove rgba8888 from the plane helpers compat list.

Cc: Sean Paul <seanpaul@chromium.org>
Reviewed-by: default avatarSean Paul <seanpaul@chromium.org>
Signed-off-by: default avatarDaniel Vetter <daniel.vetter@ffwll.ch>
parent d461701c
...@@ -2323,9 +2323,26 @@ void intel_crt_init(struct drm_device *dev) ...@@ -2323,9 +2323,26 @@ void intel_crt_init(struct drm_device *dev)
</listitem> </listitem>
</itemizedlist> </itemizedlist>
</sect2> </sect2>
<sect2>
<title>Atomic Modeset Helper Functions Reference</title>
<sect3>
<title>Overview</title>
!Pdrivers/gpu/drm/drm_atomic_helper.c overview
</sect3>
<sect3>
<title>Implementing Asynchronous Atomic Commit</title>
!Pdrivers/gpu/drm/drm_atomic_helper.c implementing async commit
</sect3>
<sect3>
<title>Atomic State Reset and Initialization</title>
!Pdrivers/gpu/drm/drm_atomic_helper.c atomic state reset and initialization
</sect3>
!Edrivers/gpu/drm/drm_atomic_helper.c
</sect2>
<sect2> <sect2>
<title>Modeset Helper Functions Reference</title> <title>Modeset Helper Functions Reference</title>
!Edrivers/gpu/drm/drm_crtc_helper.c !Edrivers/gpu/drm/drm_crtc_helper.c
!Pdrivers/gpu/drm/drm_crtc_helper.c overview
</sect2> </sect2>
<sect2> <sect2>
<title>Output Probing Helper Functions Reference</title> <title>Output Probing Helper Functions Reference</title>
...@@ -2379,7 +2396,8 @@ void intel_crt_init(struct drm_device *dev) ...@@ -2379,7 +2396,8 @@ void intel_crt_init(struct drm_device *dev)
</sect2> </sect2>
<sect2> <sect2>
<title id="drm-kms-planehelpers">Plane Helper Reference</title> <title id="drm-kms-planehelpers">Plane Helper Reference</title>
!Edrivers/gpu/drm/drm_plane_helper.c Plane Helpers !Edrivers/gpu/drm/drm_plane_helper.c
!Pdrivers/gpu/drm/drm_plane_helper.c overview
</sect2> </sect2>
</sect1> </sect1>
......
...@@ -32,6 +32,27 @@ ...@@ -32,6 +32,27 @@
#include <drm/drm_atomic_helper.h> #include <drm/drm_atomic_helper.h>
#include <linux/fence.h> #include <linux/fence.h>
/**
* DOC: overview
*
* This helper library provides implementations of check and commit functions on
* top of the CRTC modeset helper callbacks and the plane helper callbacks. It
* also provides convenience implementations for the atomic state handling
* callbacks for drivers which don't need to subclass the drm core structures to
* add their own additional internal state.
*
* This library also provides default implementations for the check callback in
* drm_atomic_helper_check and for the commit callback with
* drm_atomic_helper_commit. But the individual stages and callbacks are expose
* to allow drivers to mix and match and e.g. use the plane helpers only
* together with a driver private modeset implementation.
*
* This library also provides implementations for all the legacy driver
* interfaces on top of the atomic interface. See drm_atomic_helper_set_config,
* drm_atomic_helper_disable_plane, drm_atomic_helper_disable_plane and the
* various functions to implement set_property callbacks. New drivers must not
* implement these functions themselves but must use the provided helpers.
*/
static void static void
drm_atomic_helper_plane_changed(struct drm_atomic_state *state, drm_atomic_helper_plane_changed(struct drm_atomic_state *state,
struct drm_plane_state *plane_state, struct drm_plane_state *plane_state,
...@@ -1707,6 +1728,21 @@ int drm_atomic_helper_page_flip(struct drm_crtc *crtc, ...@@ -1707,6 +1728,21 @@ int drm_atomic_helper_page_flip(struct drm_crtc *crtc,
} }
EXPORT_SYMBOL(drm_atomic_helper_page_flip); EXPORT_SYMBOL(drm_atomic_helper_page_flip);
/**
* DOC: atomic state reset and initialization
*
* Both the drm core and the atomic helpers assume that there is always the full
* and correct atomic software state for all connectors, CRTCs and planes
* available. Which is a bit a problem on driver load and also after system
* suspend. One way to solve this is to have a hardware state read-out
* infrastructure which reconstructs the full software state (e.g. the i915
* driver).
*
* The simpler solution is to just reset the software state to everything off,
* which is easiest to do by calling drm_mode_config_reset(). To facilitate this
* the atomic helpers provide default reset implementations for all hooks.
*/
/** /**
* drm_atomic_helper_crtc_reset - default ->reset hook for CRTCs * drm_atomic_helper_crtc_reset - default ->reset hook for CRTCs
* @crtc: drm CRTC * @crtc: drm CRTC
......
...@@ -41,6 +41,26 @@ ...@@ -41,6 +41,26 @@
#include <drm/drm_plane_helper.h> #include <drm/drm_plane_helper.h>
#include <drm/drm_edid.h> #include <drm/drm_edid.h>
/**
* DOC: overview
*
* The CRTC modeset helper library provides a default set_config implementation
* in drm_crtc_helper_set_config(). Plus a few other convenience functions using
* the same callbacks which drivers can use to e.g. restore the modeset
* configuration on resume with drm_helper_resume_force_mode().
*
* The driver callbacks are mostly compatible with the atomic modeset helpers,
* except for the handling of the primary plane: Atomic helpers require that the
* primary plane is implemented as a real standalone plane and not directly tied
* to the CRTC state. For easier transition this library provides functions to
* implement the old semantics required by the CRTC helpers using the new plane
* and atomic helper callbacks.
*
* Drivers are strongly urged to convert to the atomic helpers (by way of first
* converting to the plane helpers). New drivers must not use these functions
* but need to implement the atomic interface instead, potentially using the
* atomic helpers for that.
*/
MODULE_AUTHOR("David Airlie, Jesse Barnes"); MODULE_AUTHOR("David Airlie, Jesse Barnes");
MODULE_DESCRIPTION("DRM KMS helper"); MODULE_DESCRIPTION("DRM KMS helper");
MODULE_LICENSE("GPL and additional rights"); MODULE_LICENSE("GPL and additional rights");
......
...@@ -31,6 +31,32 @@ ...@@ -31,6 +31,32 @@
#define SUBPIXEL_MASK 0xffff #define SUBPIXEL_MASK 0xffff
/**
* DOC: overview
*
* This helper library has two parts. The first part has support to implement
* primary plane support on top of the normal CRTC configuration interface.
* Since the legacy ->set_config interface ties the primary plane together with
* the CRTC state this does not allow userspace to disable the primary plane
* itself. To avoid too much duplicated code use
* drm_plane_helper_check_update() which can be used to enforce the same
* restrictions as primary planes had thus. The default primary plane only
* expose XRBG8888 and ARGB8888 as valid pixel formats for the attached
* framebuffer.
*
* Drivers are highly recommended to implement proper support for primary
* planes, and newly merged drivers must not rely upon these transitional
* helpers.
*
* The second part also implements transitional helpers which allow drivers to
* gradually switch to the atomic helper infrastructure for plane updates. Once
* that switch is complete drivers shouldn't use these any longer, instead using
* the proper legacy implementations for update and disable plane hooks provided
* by the atomic helpers.
*
* Again drivers are strongly urged to switch to the new interfaces.
*/
/* /*
* This is the minimal list of formats that seem to be safe for modeset use * This is the minimal list of formats that seem to be safe for modeset use
* with all current DRM drivers. Most hardware can actually support more * with all current DRM drivers. Most hardware can actually support more
......
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