On Mon, Dec 04, 2023 at 01:17:07PM +0100, Maxime Ripard wrote: > The name of the structure drm_atomic_state is confusing. Let's add an > entry to our todo list to rename it. > > Signed-off-by: Maxime Ripard <mripard@xxxxxxxxxx> > --- > Documentation/gpu/todo.rst | 18 ++++++++++++++++++ > 1 file changed, 18 insertions(+) > > diff --git a/Documentation/gpu/todo.rst b/Documentation/gpu/todo.rst > index b62c7fa0c2bc..fe95aea89d67 100644 > --- a/Documentation/gpu/todo.rst > +++ b/Documentation/gpu/todo.rst > @@ -120,6 +120,24 @@ Contact: Daniel Vetter, respective driver maintainers > > Level: Advanced > > +Rename drm_atomic_state > +----------------------- > + > +The KMS framework uses two slightly different definitions for the ``state`` > +concept. For a given object (plane, CRTC, encoder, etc., so > +``drm_$OBJECT_state``), the state is the entire state of that object. However, > +at the device level, ``drm_atomic_state`` refers to a state update for a > +limited number of objects. That's a very generous description of my screw-up of calling a commit a state and making a big mess out of a lot of concepts :-) > + > +The state isn't the entire device state anymore, but only the full state of s/anymore// since it was always meant to be an incremental/partial update/commit structure. > +some objects in that device. This is confusing to newcomers, and > +``drm_atomic_state`` should be renamed to something clearer like > +``drm_atomic_update``. My choice would be drm_atomic_commit, because that's what we're calling these everywhere else in the code. See drm_crtc_commit for the per-crtc tracking thing of a drm_atomic_commit. If you want update, there's quite a lot of other things we also need to rename to the _update suffix. Also this should have some pointers to the functions that need adjusting, like drm_atomic_state_alloc|get/put/init/.... since without also renaming those this is just going to create even more confusion. With my comments addressed: Reviewed-by: Daniel Vetter <daniel.vetter@xxxxxxxx> > + > +Contact: Maxime Ripard <mripard@xxxxxxxxxx> > + > +Level: Advanced > + > Fallout from atomic KMS > ----------------------- > > -- > 2.43.0 > -- Daniel Vetter Software Engineer, Intel Corporation http://blog.ffwll.ch
