[PATCH] Documentation/gpu: Requirements for driver-specific KMS uAPIs

[Harry Wentland]

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 at amd.com>
Cc: Simon Ser <contact at emersion.fr>
Cc: Joshua Ashton <joshua at froggi.es>
Cc: Michel Dänzer <mdaenzer at redhat.com>
Cc: Sebastian Wick <sebastian.wick at redhat.com>
Cc: Jonas Ådahl <jadahl at redhat.com>
Cc: Alex Goins <agoins at nvidia.com>
Cc: Pekka Paalanen <pekka.paalanen at collabora.com>
Cc: Melissa Wen <mwen at igalia.com>
Cc: Aleix Pol <aleixpol at kde.org>
Cc: Xaver Hugl <xaver.hugl at gmail.com>
Cc: Victoria Brekenfeld <victoria at system76.com>
Cc: Daniel Vetter <daniel at ffwll.ch>
Cc: Dave Airlie <airlied at gmail.com>
Cc: Ville Syrjälä <ville.syrjala at linux.intel.com>
Cc: Uma Shankar <uma.shankar at intel.com>
To: dri-devel at lists.freedesktop.org
---
 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