[PATCH 5/5] drm/doc: Move legacy kms helpers to the very end

[Alex Deucher]

On Thu, Dec 14, 2017 at 3:30 PM, Daniel Vetter <daniel.vetter at ffwll.ch> wrote:
> We don't want people to accidentally stumble over there.
>
> Also rename the plane helpers to legacy plane helpers. After Ville's
> patch to make the clipping helper atomic and move it to
> drm_atomic_helper.c there's nothing left in there that should be
> useful for modern drivers.
>
> v2: Laurent had a few questions around how state is added to
> drm_atomic_state, tried to clarify that. And spotted another sentence
> where the docs suggested subclassing.
>
> Signed-off-by: Daniel Vetter <daniel.vetter at intel.com>
> ---
>  Documentation/gpu/drm-kms-helpers.rst | 36 +++++++++++++++++------------------
>  Documentation/gpu/drm-kms.rst         |  8 ++++----
>  include/drm/drm_atomic.h              |  4 ++++
>  3 files changed, 26 insertions(+), 22 deletions(-)
>
> diff --git a/Documentation/gpu/drm-kms-helpers.rst b/Documentation/gpu/drm-kms-helpers.rst
> index 3ea622876b67..e37557b30f62 100644
> --- a/Documentation/gpu/drm-kms-helpers.rst
> +++ b/Documentation/gpu/drm-kms-helpers.rst
> @@ -74,15 +74,6 @@ Helper Functions Reference
>  .. kernel-doc:: drivers/gpu/drm/drm_atomic_helper.c
>     :export:
>
> -Legacy CRTC/Modeset Helper Functions Reference
> -==============================================
> -
> -.. kernel-doc:: drivers/gpu/drm/drm_crtc_helper.c
> -   :doc: overview
> -
> -.. kernel-doc:: drivers/gpu/drm/drm_crtc_helper.c
> -   :export:
> -
>  Simple KMS Helper Reference
>  ===========================
>
> @@ -282,15 +273,6 @@ Flip-work Helper Reference
>  .. kernel-doc:: drivers/gpu/drm/drm_flip_work.c
>     :export:
>
> -Plane Helper Reference
> -======================
> -
> -.. kernel-doc:: drivers/gpu/drm/drm_plane_helper.c
> -   :doc: overview
> -
> -.. kernel-doc:: drivers/gpu/drm/drm_plane_helper.c
> -   :export:
> -
>  Auxiliary Modeset Helpers
>  =========================
>
> @@ -308,3 +290,21 @@ Framebuffer GEM Helper Reference
>
>  .. kernel-doc:: drivers/gpu/drm/drm_gem_framebuffer_helper.c
>     :export:
> +
> +Legacy Plane Helper Reference
> +=============================
> +
> +.. kernel-doc:: drivers/gpu/drm/drm_plane_helper.c
> +   :doc: overview
> +
> +.. kernel-doc:: drivers/gpu/drm/drm_plane_helper.c
> +   :export:
> +
> +Legacy CRTC/Modeset Helper Functions Reference
> +==============================================
> +
> +.. kernel-doc:: drivers/gpu/drm/drm_crtc_helper.c
> +   :doc: overview
> +
> +.. kernel-doc:: drivers/gpu/drm/drm_crtc_helper.c
> +   :export:
> diff --git a/Documentation/gpu/drm-kms.rst b/Documentation/gpu/drm-kms.rst
> index 420025bd6a9b..cbba93483aec 100644
> --- a/Documentation/gpu/drm-kms.rst
> +++ b/Documentation/gpu/drm-kms.rst
> @@ -263,10 +263,10 @@ Taken all together there's two consequences for the atomic design:
>
>  - An atomic update is assembled and validated as an entirely free-standing pile
>    of structures within the :c:type:`drm_atomic_state <drm_atomic_state>`
> -  container. Again drivers can subclass that container for their own state
> -  structure tracking needs. Only when a state is committed is it applied to the
> -  driver and modeset objects. This way rolling back an update boils down to
> -  releasing memory and unreferencing objects like framebuffers.
> +  container. Driver private state structures are also tracked in the same
> +  structure, see the next chapter.  Only when a state is committed is it applied

I think it would be clearer as:
structure (see the next chapter).
or
structure; see the next chapter.

Either way:
Reviewed-by: Alex Deucher <alexander.deucher at amd.com>

> +  to the driver and modeset objects. This way rolling back an update boils down
> +  to releasing memory and unreferencing objects like framebuffers.
>
>  Read on in this chapter, and also in :ref:`drm_atomic_helper` for more detailed
>  coverage of specific topics.
> diff --git a/include/drm/drm_atomic.h b/include/drm/drm_atomic.h
> index 8e4829a25c1b..e7f25e342cc8 100644
> --- a/include/drm/drm_atomic.h
> +++ b/include/drm/drm_atomic.h
> @@ -246,6 +246,10 @@ struct __drm_private_objs_state {
>   * @num_private_objs: size of the @private_objs array
>   * @private_objs: pointer to array of private object pointers
>   * @acquire_ctx: acquire context for this atomic modeset state update
> + *
> + * States are added to an atomic update by calling drm_atomic_get_crtc_state(),
> + * drm_atomic_get_plane_state(), drm_atomic_get_connector_state(), or for
> + * private state structures, drm_atomic_get_private_obj_state().
>   */
>  struct drm_atomic_state {
>         struct kref ref;
> --
> 2.15.1
>
> _______________________________________________
> dri-devel mailing list
> dri-devel at lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/dri-devel