[PATCH 8/8] drm/doc: document the type plane property

[Simon Ser]

On Thursday, December 17th, 2020 at 11:52 AM, Daniel Vetter <daniel at ffwll.ch> wrote:

> > > > + *     capability, the plane type is just a hint and is mostly superseded by
> > > > + *     atomic test-only commits. The type hint can still be used to come up
> > > > + *     more easily with a plane configuration accepted by the driver.
> > > > + *
> > > > + *     The value of this property can be one of the following:
> > > > + *
> > > > + *     "Primary":
> > > > + *         To light up a CRTC, attaching a primary plane is the most likely to
> > > > + *         work if it covers the whole CRTC and doesn't have scaling or
> > > > + *         cropping set up.
> > > > + *
> > > > + *         Drivers may support more features for the primary plane, user-space
> > > > + *         can find out with test-only atomic commits.
> > >
> > > We need to mention here that this is the implicit plane used by the
> > > PAGE_FLIP and SETCRTC ioctl (maybe spell them out in full since these are
> > > userspace docs).
> >
> > I intentionally didn't write that down here, because as previously discussed,
> > user-space has no way to guess the drm_crtc.{primary,cursor} pointers, so
> > user-space cannot guess which planes will be used for legacy IOCTLs. Adding any
> > hint that user-space _could_ do it will result in broken user-space.
>
> Hm then at least a warning that userspace must not mix legacy ioctls
> with using primary planes explicitly, since havoc will ensue? More
> relevant for cursor planes, since some compositors do use atomic +
> legacy cursor planes, but imo good to have the same blurb with the
> list of relevant ioctls for each.

Oh, right, good idea, this sounds important. Will add in v2.