[PATCH 4/5] drm/atomic: Make the drm_atomic_state documentation less ambiguous

[Pekka Paalanen]

On Fri, 8 Dec 2023 16:20:37 +0100
Maxime Ripard <mripard at kernel.org> wrote:

> On Fri, Dec 08, 2023 at 03:59:46PM +0200, Pekka Paalanen wrote:
> > On Fri, 8 Dec 2023 13:25:22 +0100
> > Maxime Ripard <mripard at kernel.org> wrote:
> >   
> > > On Fri, Dec 08, 2023 at 10:08:28AM +0200, Pekka Paalanen wrote:  
> > > > On Thu, 7 Dec 2023 15:27:33 +0100
> > > > Maxime Ripard <mripard at kernel.org> wrote:
> > > >     
> > > > > On Tue, Dec 05, 2023 at 10:51:06AM +0200, Pekka Paalanen wrote:    
> > > > > > On Mon,  4 Dec 2023 13:17:06 +0100
> > > > > > Maxime Ripard <mripard at kernel.org> wrote:
> > > > > >       
> > > > > > > The current documentation of drm_atomic_state says that it's the "global
> > > > > > > state object". This is confusing since, while it does contain all the
> > > > > > > objects affected by an update and their respective states, if an object
> > > > > > > isn't affected by this update it won't be part of it.
> > > > > > > 
> > > > > > > Thus, it's not truly a "global state", unlike object state structures
> > > > > > > that do contain the entire state of a given object.
> > > > > > > 
> > > > > > > Signed-off-by: Maxime Ripard <mripard at kernel.org>
> > > > > > > ---
> > > > > > >  include/drm/drm_atomic.h | 10 +++++++++-
> > > > > > >  1 file changed, 9 insertions(+), 1 deletion(-)

...

> > Sima's phrasing is an addition, not a replacement, to this. There are
> > two things:
> > 
> > a) An atomic commit does not need to contain all the objects of a
> >    drm_device.
> > 
> > b) An atomic commit may affect more objects than it originally
> >    contained. (from userspace perspective)
> > 
> > Here b) is important for userspace to know, because it can be
> > surprising, but I understand that this patch is not userspace doc.  
> 
> Right, so my initial goal from this series was to make sure the
> ambiguous meaning of what a state was was (hopefully) lifted, and thus
> we could progress on your userspace doc patch. So I want to address
> point A here.
> 
> B is also important, but maybe we should discuss it into a separate
> patch?

Sure!

Just mind both cases to not accidentally imply something about b) when
talking about a).


Thanks,
pq
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 833 bytes
Desc: OpenPGP digital signature
URL: <https://lists.freedesktop.org/archives/dri-devel/attachments/20231211/921de834/attachment.sig>