Re: [PATCH 01/29] drm/atomic: Document atomic state lifetime

[Thomas Zimmermann <tzimmermann@suse.de>]

Hi

Am 02.09.25 um 10:32 schrieb Maxime Ripard:
> How drm_atomic_state structures and the various entity structures are
> allocated and freed isn't really trivial, so let's document it.

Thanks for doing this.

>
> Signed-off-by: Maxime Ripard <mripard@kernel.org>
> ---
>   Documentation/gpu/drm-kms.rst |  6 ++++++
>   drivers/gpu/drm/drm_atomic.c  | 45 +++++++++++++++++++++++++++++++++++++++++++
>   2 files changed, 51 insertions(+)
>
> diff --git a/Documentation/gpu/drm-kms.rst b/Documentation/gpu/drm-kms.rst
> index abfe220764e1edc758a6bc6fb5ff9c8e1c7749ff..dc0f61a3d29e752889077d855a4bea381f2e2c18 100644
> --- a/Documentation/gpu/drm-kms.rst
> +++ b/Documentation/gpu/drm-kms.rst
> @@ -280,10 +280,16 @@ structure, ordering of committing state changes to hardware is sequenced using
>   :c:type:`struct drm_crtc_commit <drm_crtc_commit>`.
>   
>   Read on in this chapter, and also in :ref:`drm_atomic_helper` for more detailed
>   coverage of specific topics.
>   
> +Atomic State Lifetime
> +---------------------
> +
> +.. kernel-doc:: drivers/gpu/drm/drm_atomic.c
> +   :doc: state lifetime
> +
>   Handling Driver Private State
>   -----------------------------
>   
>   .. kernel-doc:: drivers/gpu/drm/drm_atomic.c
>      :doc: handling driver private state
> diff --git a/drivers/gpu/drm/drm_atomic.c b/drivers/gpu/drm/drm_atomic.c
> index cd15cf52f0c9144711da5879da57884674aea9e4..b356d26faad4acaa25c1fe6f9bd5043b6364ce87 100644
> --- a/drivers/gpu/drm/drm_atomic.c
> +++ b/drivers/gpu/drm/drm_atomic.c
> @@ -44,10 +44,55 @@
>   #include <drm/drm_writeback.h>
>   
>   #include "drm_crtc_internal.h"
>   #include "drm_internal.h"
>   
> +/**
> + * DOC: state lifetime
> + *
> + * &struct drm_atomic_state represents an update to video pipeline state.
> + *
> + * Its lifetime is:
> + *
> + * - at reset time, the entity reset implementation will allocate a
> + *   new, default, state and will store it in the entity state pointer.

Can you somehow mention drm_mode_config_reset() here? 'Reset time' might 
be too abstract.

> + *
> + * - whenever a new update is needed:
> + *
> + *   + we allocate a new &struct drm_atomic_state using drm_atomic_state_alloc().
> + *
> + *   + we copy the state of each affected entity into our &struct
> + *     drm_atomic_state using drm_atomic_get_plane_state(),
> + *     drm_atomic_get_crtc_state(), drm_atomic_get_connector_state(), or
> + *     drm_atomic_get_private_obj_state(). That state can then be
> + *     modified.
> + *
> + *     At that point, &struct drm_atomic_state stores three state
> + *     pointers for that particular entity: the old, new, and existing
> + *     (called "state") states. The old state is the state currently
> + *     active in the hardware, ie either the one initialized by reset()

'ie' should be replaced by 'which is'. AFAIK ie is used like this: 
(i.e., ...).

> + *     or a newer one if a commit has been made. The new state is the
> + *     state we just allocated and we might eventually commit to the
> + *     hardware. The existing state points to the state we'll eventually
> + *     have to free, the new state for now.

That final sentence is confusing. What are we doing with the existing 
state? Will the old state ever become the existing state? You also never 
explain this below.

Maybe only focus on the old and new state for now and explain the 
meaning of the existing state in a separate bullet point.

Best regards
Thomas

> + *
> + *   + Once we run a commit, it is first checked and if the check is
> + *     successful, it is committed. Part of the commit is a call to
> + *     drm_atomic_helper_swap_state() which will turn the new state into
> + *     the active state. Doing so involves updating the entity state
> + *     pointer (&drm_crtc.state or similar) to point to the new state,
> + *     and the existing state will now point to the old state, that used
> + *     to be active but isn't anymore.
> + *
> + *   + When the commit is done, and when all references to our &struct
> + *     drm_atomic_state are put, drm_atomic_state_clear() runs and will
> + *     free all the old states.
> + *
> + *   + Now, we don't have any active &struct drm_atomic_state anymore,
> + *     and only the entity active states remain allocated.
> + */
> +
>   void __drm_crtc_commit_free(struct kref *kref)
>   {
>   	struct drm_crtc_commit *commit =
>   		container_of(kref, struct drm_crtc_commit, ref);
>   
>

-- 
--
Thomas Zimmermann
Graphics Driver Developer
SUSE Software Solutions Germany GmbH
Frankenstrasse 146, 90461 Nuernberg, Germany
GF: Ivo Totev, Andrew Myers, Andrew McDonald, Boudien Moerman
HRB 36809 (AG Nuernberg)