[PATCH] drm/doc: Document uapi requirements in DRM

[Eric Anholt]

Daniel Vetter <daniel.vetter at ffwll.ch> writes:

> Everyone knows them, except all the new folks joining from the ARM
> side haven't lived through all the pain of the past years and are
> entirely surprised when I raise this. Definitely time to document
> this.


> ---
>  Documentation/gpu/drm-uapi.rst | 67 ++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 67 insertions(+)
>
> diff --git a/Documentation/gpu/drm-uapi.rst b/Documentation/gpu/drm-uapi.rst
> index 94876938aef3..a7e3aa27167d 100644
> --- a/Documentation/gpu/drm-uapi.rst
> +++ b/Documentation/gpu/drm-uapi.rst
> @@ -36,6 +36,73 @@ Primary Nodes, DRM Master and Authentication
>  Open-Source Userspace Requirements
>  ==================================
>  
> +The DRM subsystem has stricter requirements on what the userspace side for new
> +uAPI needs to look like. This section here explains what exactly those
> +requirements are, and why they exist.
> +
> +The short summary is that any addition of DRM uAPI requires corresponding
> +open-sourced userspace patches, and those patches must be reviewed and ready for
> +merging into a suitable and canonical upstream project.
> +
> +GFX devices (both display and render/GPU side) are really complex bits of hardware,
> +with userspace and kernel by necessity having to work together really closely.
> +The interfaces, for rendering and modesetting must be extremely wide and

I think there should be another comma after "modesetting".

> +flexible, and therefore it is almost always impossible to precisely define them
> +for every possible corner case. This in turns makes it really practically

"in turn"

> +These are fairly steep requirements, but have grown out from years of shared
> +pain and experience with uAPI added hastily, and almost always regretted about
> +as fast. GFX devices change really fast, requiring a paradigm shift and entire
> +new set of uAPI interfaces every few years at least. Together with the Linux
> +kernel's guarantee to keep existing userspace running for 10+ years this is
> +already rather painful for the DRM subsystem, with multiple different uAPIs for
> +the same thing co-existing. If we'd add a few more complete mistakes into the

"If we"

> +mix every year it would be entirely unmanagable.

With the little nitpicks (probably) fixed,

Reviewed-by: Eric Anholt <eric at anholt.net>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 800 bytes
Desc: not available
URL: <https://lists.freedesktop.org/archives/dri-devel/attachments/20160819/3d2d2a1a/attachment-0001.sig>