[PATCH 16/17] drm: Docbook integration and over sections for all the new helpers

[Sean Paul]

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 at 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 at lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/dri-devel