[PATCH v4 2/5] drm/doc: document the type plane property

[Daniel Vetter]

On Fri, Jan 15, 2021 at 12:06 PM Simon Ser <contact at emersion.fr> wrote:
>
> On Tuesday, December 22nd, 2020 at 2:59 PM, Daniel Vetter <daniel at ffwll.ch> wrote:
>
> > > + * type:
> > > + *     Immutable property describing the type of the plane.
> > > + *
> > > + *     For user-space which has enabled the &DRM_CLIENT_CAP_UNIVERSAL_PLANES
> >
> > s/UNIVERSAL_PLANES/ATOMIC/ here?
> >
> > With just universal planes you don't have atomic test-only. But I guess it
> > also works as-is, I'm just not entirely clear what you want to state here.
>
> Right. This paragraph was written when I wasn't aware about ATOMIC implicitly
> enabling UNIVERSAL_PLANES. Fixed in v5.
>
> > > + *     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. Note that
> > > + *     &DRM_CLIENT_CAP_UNIVERSAL_PLANES is implicitly enabled by
> > > + *     &DRM_CLIENT_CAP_ATOMIC.
> > > + *
> > > + *     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.
> > > + *
> > > + *         Primary planes are implicitly used by the kernel in the legacy
> > > + *         IOCTLs &DRM_IOCTL_MODE_SETCRTC and &DRM_IOCTL_MODE_PAGE_FLIP.
> > > + *         Therefore user-space must not mix explicit usage of any primary
> > > + *         plane (e.g. through an atomic commit) with these legacy IOCTLs.
> >
> > Empty line here for reading comfort in plain text? Same below.
> >
> > Since you mention formats below, I also wonder whether we should state
> > here that xrgb8888 is generally supported, worst case through software
> > emulation. That's defacto the uapi we have to adhere to.
>
> I wonder. If a new driver decides not to support XRGB8888, that wouldn't be a
> kernel regression because it's about new hardware. Do we want to formally lock
> future drivers into XRGB8888 support? Or do we want to open the door for a
> driver to break this assumption, even if most user-space won't work on the new
> hardware?
>
> I guess all of this is mostly theoretical at this point.

It's been practical since a few years, since a lot of the simple
panels we've added don't support xrgb8888. That's why we have the
fairly good horror show of format conversions in drm_format_helper.c.
And we've done this because too much general distro userspace just
keels over real bad if xrgb8888 doesn't work.
-Daniel
-- 
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch