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

[Laurent Pinchart <laurent.pinchart@ideasonboard.com>]

On Tue, Sep 02, 2025 at 03:08:12PM +0200, Thomas Zimmermann wrote:
> Am 02.09.25 um 10:32 schrieb Maxime Ripard:
> > How drm_atomic_state structures and the various entity structures are

"entity" isn't commonly used in this sense in DRM/KMS. "object" is the
best term I can think so, even if some DRM objects (in the
drm_mode_object sense) are out of scope in this context. Same below
where you use "entity".

> > 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:

This indicates you'll talk about the lifetime of drm_atomic_state
itself, while the text below also covers the lifetime of the state of
the individual objects. This is a bit confusing. One of the important
aspects that I think you should document is that drm_atomic_state is a
transient object that holds a state update (I once proposed renaming it
to drm_atomic_commit, and to my surprise the idea wasn't rejected right
away, but it would cause lots of churn) in the form of pointers to
individual objects' states, and only exists for the duration of an
atomic commit operation, while object states have a different lifetime.

> > + *
> > + * - at reset time, the entity reset implementation will allocate a
> > + *   new, default, state and will store it in the entity state pointer.

Strictly speaking, this isn't related to the drm_atomic_state lifetime.

> 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.

I agree, the documentation here is clear for someone who knows exactly
how things work, but quite confusing for a newcomer.

> > + *
> > + *   + 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

"Committing a commit" sounds weird. As you define the atomic state above
as "an update to video pipeline state", I would write

  After the state is populated, it is checked. If the check is successful, the
  state update is then committed.

> > + *     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);
> >   

-- 
Regards,

Laurent Pinchart