[PATCH 16/17] drm: Docbook integration and over sections for all the new helpers
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 > --- > 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) > > > > + Atomic Modeset Helper Functions Reference > + > + Overview > +!Pdrivers/gpu/drm/drm_atomic_helper.c overview > + > + > + Implementing Asynchronous Atomic Commit > +!Pdrivers/gpu/drm/drm_atomic_helper.c implementing async commit > + > + > + Atomic State Reset and Initialization > +!Pdrivers/gpu/drm/drm_atomic_helper.c atomic state reset and initialization > + > +!Edrivers/gpu/drm/drm_atomic_helper.c > + > + >Modeset Helper Functions Reference > !Edrivers/gpu/drm/drm_crtc_helper.c > +!Pdrivers/gpu/drm/drm_crtc_helper.c overview > > >Output Probing Helper Functions Reference > @@ -2379,7 +2396,8 @@ void intel_crt_init(struct drm_device *dev) > > >Plane Helper Reference > -!Edrivers/gpu/drm/drm_plane_helper.c Plane Helpers > +!Edrivers/gpu/drm/drm_plane_helper.c > +!Pdrivers/gpu/drm/drm_plane_helper.c overview > > > > 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 > #include > > +/** > + * 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 > #include > > +/** > + * 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
[PATCH 16/17] 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. Signed-off-by: Daniel Vetter --- 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) + Atomic Modeset Helper Functions Reference + + Overview +!Pdrivers/gpu/drm/drm_atomic_helper.c overview + + + Implementing Asynchronous Atomic Commit +!Pdrivers/gpu/drm/drm_atomic_helper.c implementing async commit + + + Atomic State Reset and Initialization +!Pdrivers/gpu/drm/drm_atomic_helper.c atomic state reset and initialization + +!Edrivers/gpu/drm/drm_atomic_helper.c + + Modeset Helper Functions Reference !Edrivers/gpu/drm/drm_crtc_helper.c +!Pdrivers/gpu/drm/drm_crtc_helper.c overview Output Probing Helper Functions Reference @@ -2379,7 +2396,8 @@ void intel_crt_init(struct drm_device *dev) Plane Helper Reference -!Edrivers/gpu/drm/drm_plane_helper.c Plane Helpers +!Edrivers/gpu/drm/drm_plane_helper.c +!Pdrivers/gpu/drm/drm_plane_helper.c overview 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 #include +/** + * 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 #include +/** + * 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 + *
