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

[Pekka Paalanen]

On Thu, 4 May 2023 17:25:57 -0400
Harry Wentland <harry.wentland at amd.com> 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 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:

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