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

[Christian König]

Am 19.08.2016 um 23:43 schrieb 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.

Oh, yes please.

>> ---
>>   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>

I read through it and can't find anything more to add. So with Eric's 
comments fixed the patch is Reviewed-by: Christian König 
<christian.koenig at amd.com>.

Additional to that I think with our hybrid stack this is rather 
important for AMD. So I'm going to forward it to a few people internally 
as well.

Regards,
Christian.