On Thu, 4 May 2023 17:25:57 -0400 Harry Wentland <harry.wentland@xxxxxxx> wrote: > We have steered away for a long time now from driver-specific KMS APIs > for good reasons but never codified our stance. With the proposal of > new, driver-specific color management uAPIs [1] it is important to > outline the requirements for the rare times when driver-specific KMS > uAPIs are desired in order to move complex topics along. > > [1] https://patchwork.freedesktop.org/series/116862/ > > Signed-off-by: Harry Wentland <harry.wentland@xxxxxxx> > Cc: Simon Ser <contact@xxxxxxxxxxx> > Cc: Joshua Ashton <joshua@xxxxxxxxx> > Cc: Michel Dänzer <mdaenzer@xxxxxxxxxx> > Cc: Sebastian Wick <sebastian.wick@xxxxxxxxxx> > Cc: Jonas Ådahl <jadahl@xxxxxxxxxx> > Cc: Alex Goins <agoins@xxxxxxxxxx> > Cc: Pekka Paalanen <pekka.paalanen@xxxxxxxxxxxxx> > Cc: Melissa Wen <mwen@xxxxxxxxxx> > Cc: Aleix Pol <aleixpol@xxxxxxx> > Cc: Xaver Hugl <xaver.hugl@xxxxxxxxx> > Cc: Victoria Brekenfeld <victoria@xxxxxxxxxxxx> > Cc: Daniel Vetter <daniel@xxxxxxxx> > Cc: Dave Airlie <airlied@xxxxxxxxx> > Cc: Ville Syrjälä <ville.syrjala@xxxxxxxxxxxxxxx> > Cc: Uma Shankar <uma.shankar@xxxxxxxxx> > To: dri-devel@xxxxxxxxxxxxxxxxxxxxx > --- > Documentation/gpu/drm-uapi.rst | 32 ++++++++++++++++++++++++++++++++ > 1 file changed, 32 insertions(+) > > diff --git a/Documentation/gpu/drm-uapi.rst b/Documentation/gpu/drm-uapi.rst > index ce47b4292481..eaefc3ed980c 100644 > --- a/Documentation/gpu/drm-uapi.rst > +++ b/Documentation/gpu/drm-uapi.rst > @@ -118,6 +118,38 @@ is already rather painful for the DRM subsystem, with multiple different uAPIs > for the same thing co-existing. If we add a few more complete mistakes into the > mix every year it would be entirely unmanageable. > > +.. _driver_specific: > + > +Driver-Specific DRM/KMS uAPI > +============================ > + > +Driver-specific interfaces are strongly discouraged for DRM/KMS interfaces. > +Kernel-modesetting (KMS) functionality does in principle apply to all drivers. > +Driver-specific uAPIs tends to lead to unique implementations in userspace and > +are often hard to maintain, especially when different drivers implement similar > +but subtly different uAPIs. > + > +At times arriving at a consensus uAPI can be a difficult and lengthy process and > +might benefit from experimentation. This experimentation might warrant > +introducing driver specific APIs in order to move the eosystem forward. If a > +driver decides to go down this path we ask for the following: Hi, should it be "require" instead of "ask"? > + > +- An agreement within the community that introducing driver-specific uAPIs is > + warranted in this case; > + > +- The new uAPI is behind a CONFIG option that is clearly marked EXPERIMENTAL and > + is disabled by default; > + > +- The new uAPI is enabled when a module parameter for the driver is set, and > + defaults to 'off' otherwise; > + > +- The new uAPI follows all open-source userspace requirements outlined above; > + > +- The focus is maintained on development of a vendor-neutral uAPI and progress > + toward such an uAPI needs to be apparent on public forums. If no such progress > + is visible within a reasonable timeframe (1-2 years) anybody is within their > + right to send, review, and merge patches that remove the driver-specific uAPI. > + > .. _drm_render_node: > > Render nodes Seems fine to me. I have another addition to suggest: When such UAPI is introduced, require that it comes with an expiration date. This date should be unmissable, not just documented. The kernel module parameter name to enable the UAPI could contain the expiry date, for example. After all, the most important thing to get through to users is that this *will* go away and not just theoretically. If that date needs to be moved forward, it should be possible to do so with a simple patch gathering enough acks. The main thing is to set the date from the start, so there can be no confusion about when its going to the chopping block. I do not suggest that the kernel would automatically runtime disable the UAPI after that date. Does any of the big idea fly with upper maintainers and Linus? Thanks, pq
