| Message ID | 1414934370-11924-17-git-send-email-daniel.vetter@ffwll.ch (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
On Sun, Nov 02, 2014 at 02:19:29PM +0100, Daniel Vetter wrote: > In all cases the text requires that new drivers are converted to the > atomic interfaces. > > v2: Add overview for state handling. > > Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch> > --- > Documentation/DocBook/drm.tmpl | 20 +++++++++++++++++++- > drivers/gpu/drm/drm_atomic_helper.c | 36 ++++++++++++++++++++++++++++++++++++ > drivers/gpu/drm/drm_crtc_helper.c | 20 ++++++++++++++++++++ > drivers/gpu/drm/drm_plane_helper.c | 26 +++++++++++++++++++++++++- > 4 files changed, 100 insertions(+), 2 deletions(-) > > diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl > index ea0ef43b19e1..5e3a11f5e941 100644 > --- a/Documentation/DocBook/drm.tmpl > +++ b/Documentation/DocBook/drm.tmpl > @@ -2324,8 +2324,25 @@ void intel_crt_init(struct drm_device *dev) > </itemizedlist> > </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> > <title>Modeset Helper Functions Reference</title> > !Edrivers/gpu/drm/drm_crtc_helper.c > +!Pdrivers/gpu/drm/drm_crtc_helper.c overview > </sect2> > <sect2> > <title>Output Probing Helper Functions Reference</title> > @@ -2379,7 +2396,8 @@ void intel_crt_init(struct drm_device *dev) > </sect2> > <sect2> > <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> > </sect1> > > diff --git a/drivers/gpu/drm/drm_atomic_helper.c b/drivers/gpu/drm/drm_atomic_helper.c > index bd38df3cbe55..d0ca681d6326 100644 > --- a/drivers/gpu/drm/drm_atomic_helper.c > +++ b/drivers/gpu/drm/drm_atomic_helper.c > @@ -32,6 +32,27 @@ > #include <drm/drm_atomic_helper.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 > drm_atomic_helper_plane_changed(struct drm_atomic_state *state, > struct drm_plane_state *plane_state, > @@ -1709,6 +1730,21 @@ backoff: > 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 > * @crtc: drm CRTC > * > diff --git a/drivers/gpu/drm/drm_crtc_helper.c b/drivers/gpu/drm/drm_crtc_helper.c > index 46728a8ac622..33195e9adaab 100644 > --- a/drivers/gpu/drm/drm_crtc_helper.c > +++ b/drivers/gpu/drm/drm_crtc_helper.c > @@ -41,6 +41,26 @@ > #include <drm/drm_plane_helper.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_DESCRIPTION("DRM KMS helper"); > MODULE_LICENSE("GPL and additional rights"); > diff --git a/drivers/gpu/drm/drm_plane_helper.c b/drivers/gpu/drm/drm_plane_helper.c > index 40ecb2c6e858..df69522b1f0e 100644 > --- a/drivers/gpu/drm/drm_plane_helper.c > +++ b/drivers/gpu/drm/drm_plane_helper.c > @@ -31,6 +31,31 @@ > > #define SUBPIXEL_MASK 0xffff > > +/** > + * DOC: overview > + * > + * This helper library has two ports. The first part has support to implement s/ports/parts/ > + * primary plane support on top of the normal CRTC configuration interface. Sinc s/Sinc/Since/ > + * the legacy ->set_config interface ties the primary plane together with the > + * CRTC state this does not userspace to disable the primary plane itself. To s/does not/does not allow/ > + * 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 > * with all current DRM drivers. Most hardware can actually support more > @@ -40,7 +65,6 @@ > */ > static const uint32_t safe_modeset_formats[] = { > DRM_FORMAT_XRGB8888, > - DRM_FORMAT_ARGB8888, Whoops! > }; > > /* > -- > 2.1.1 > > _______________________________________________ > dri-devel mailing list > dri-devel@lists.freedesktop.org > http://lists.freedesktop.org/mailman/listinfo/dri-devel
diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl index ea0ef43b19e1..5e3a11f5e941 100644 --- a/Documentation/DocBook/drm.tmpl +++ b/Documentation/DocBook/drm.tmpl @@ -2324,8 +2324,25 @@ void intel_crt_init(struct drm_device *dev) </itemizedlist> </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> <title>Modeset Helper Functions Reference</title> !Edrivers/gpu/drm/drm_crtc_helper.c +!Pdrivers/gpu/drm/drm_crtc_helper.c overview </sect2> <sect2> <title>Output Probing Helper Functions Reference</title> @@ -2379,7 +2396,8 @@ void intel_crt_init(struct drm_device *dev) </sect2> <sect2> <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> </sect1> diff --git a/drivers/gpu/drm/drm_atomic_helper.c b/drivers/gpu/drm/drm_atomic_helper.c index bd38df3cbe55..d0ca681d6326 100644 --- a/drivers/gpu/drm/drm_atomic_helper.c +++ b/drivers/gpu/drm/drm_atomic_helper.c @@ -32,6 +32,27 @@ #include <drm/drm_atomic_helper.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 drm_atomic_helper_plane_changed(struct drm_atomic_state *state, struct drm_plane_state *plane_state, @@ -1709,6 +1730,21 @@ backoff: 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 * @crtc: drm CRTC * diff --git a/drivers/gpu/drm/drm_crtc_helper.c b/drivers/gpu/drm/drm_crtc_helper.c index 46728a8ac622..33195e9adaab 100644 --- a/drivers/gpu/drm/drm_crtc_helper.c +++ b/drivers/gpu/drm/drm_crtc_helper.c @@ -41,6 +41,26 @@ #include <drm/drm_plane_helper.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_DESCRIPTION("DRM KMS helper"); MODULE_LICENSE("GPL and additional rights"); diff --git a/drivers/gpu/drm/drm_plane_helper.c b/drivers/gpu/drm/drm_plane_helper.c index 40ecb2c6e858..df69522b1f0e 100644 --- a/drivers/gpu/drm/drm_plane_helper.c +++ b/drivers/gpu/drm/drm_plane_helper.c @@ -31,6 +31,31 @@ #define SUBPIXEL_MASK 0xffff +/** + * DOC: overview + * + * This helper library has two ports. The first part has support to implement + * primary plane support on top of the normal CRTC configuration interface. Sinc + * the legacy ->set_config interface ties the primary plane together with the + * CRTC state this does not 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 * with all current DRM drivers. Most hardware can actually support more @@ -40,7 +65,6 @@ */ static const uint32_t safe_modeset_formats[] = { DRM_FORMAT_XRGB8888, - DRM_FORMAT_ARGB8888, }; /*
In all cases the text requires that new drivers are converted to the atomic interfaces. v2: Add overview for state handling. Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch> --- Documentation/DocBook/drm.tmpl | 20 +++++++++++++++++++- drivers/gpu/drm/drm_atomic_helper.c | 36 ++++++++++++++++++++++++++++++++++++ drivers/gpu/drm/drm_crtc_helper.c | 20 ++++++++++++++++++++ drivers/gpu/drm/drm_plane_helper.c | 26 +++++++++++++++++++++++++- 4 files changed, 100 insertions(+), 2 deletions(-)