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: + +- 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 -- 2.40.1
