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

[Maxime Ripard <mripard@kernel.org>]

[-- Attachment #1: Type: text/plain, Size: 1932 bytes --]

Hi Thomas,

On Tue, Sep 02, 2025 at 03:08:12PM +0200, Thomas Zimmermann wrote:
> > + *     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?

After the other cleanup series I have, existing state is only ever used
to point to the state we should free.

> Will the old state ever become the existing state? You also never explain
> this below.

Yes, after we run an atomic commit. If the commit is only allocated and
freed, or if the atomic is only checked, then we'll free new state. It's
what I tried to explain in the next paragraph, but maybe it's not clear
enough?

> 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'll try to do that then, thanks!

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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 273 bytes --]