[PATCH libdrm] headers: Add README file

[Emil Velikov]

On 10 November 2016 at 21:07, Alex Deucher <alexdeucher at gmail.com> wrote:
> On Thu, Nov 10, 2016 at 11:44 AM, Emil Velikov <emil.l.velikov at gmail.com> wrote:
>> From: Emil Velikov <emil.velikov at collabora.com>
>>
>> Since we're trying to standardise and make things more consistent in
>> the area, add a basic README which covers some of the more popular
>> topics.
>>
>> Cc: Dave Airlie <airlied at redhat.com>
>> Cc: Daniel Vetter <daniel.vetter at ffwll.ch>
>> Signed-off-by: Emil Velikov <emil.l.velikov at gmail.com>
>> ---
>> Dave, did I get it right on the "why only drm files should live here" ?
>>
>> Dave, Daniel, which trees/branches [in drm-misc] we can use as reference
>> point here ?
>> ---
>>  include/drm/README | 72 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
>>  1 file changed, 72 insertions(+)
>>  create mode 100644 include/drm/README
>>
>> diff --git a/include/drm/README b/include/drm/README
>> new file mode 100644
>> index 0000000..2f80c15
>> --- /dev/null
>> +++ b/include/drm/README
>> @@ -0,0 +1,72 @@
>> +What are these headers ?
>> +------------------------
>> +This is the canonical source of drm headers that user space should use for
>> +communicating with the kernel DRM subsystem.
>> +
>> +They flow from the kernel, thus any changes must be merged there first.
>> +Do _not_ attempt to "fix" these by deviating from the kernel ones !
>> +
>> +
>> +Non-linux platforms - changes/patches
>> +-------------------------------------
>> +If your platform has local changes, please send them upstream for inclusion.
>> +Even if your patches don't get accepted in their current form, devs will
>> +give you feedback on how to address things properly.
>> +
>> +git send-email --subject-prefix="PATCH libdrm" your patches to dri-devel
>> +mailing list.
>> +
>> +Before doing so, please consider the following:
>> + - Have the [libdrm vs kernel] headers on your platform deviated ?
>> +Consider unifying them first.
>> +
>> + - Have you introduced additional ABI that's not available in Linux ?
>> +Propose it for [Linux kernel] upstream inclusion.
>> +If that doesn't work out (hopefully it never does), move it to another header
>> +and/or keep the change(s) local ?
>> +
>> + - Are your changes DRI1/UMS specific ?
>> +There is virtually no interest/power in keeping those legacy interfaces. They
>> +are around due to the kernel "thou shalt not break existing user space" rule.
>> +
>> +Consider porting the driver to DRI2/KMS - all (almost?) sensible hardware is
>> +capable of supporting those.
>> +
>> +
>> +Which headers go where ?
>> +------------------------
>> +A snipped from the, now removed, Makefile.am used to state:
>> +
>> +  XXX airlied says, nothing besides *_drm.h and drm*.h should be necessary.
>> +  however, r300 and via need their reg headers installed in order to build.
>> +  better solutions are welcome.
>> +
>> +Obviously the r300 and via headers are no longer around ;-)
>> +
>> +Reason behind is that the drm headers can be used as a basic communications
>> +channel with the respective kernel modules. If more advanced functionality is
>> +required one can pull the specific libdrm_$driver which is free to pull
>> +additional files from the kernel.
>> +
>> +For example: nouveau has nouveau/nvif/*.h while vc4 has vc4/*.h
>> +
>> +If your driver is still in prototyping/staging state, consider moving the
>> +$driver_drm.h into $driver and _not_ installing it. An header providing opaque
>> +definitions and access [via $driver_drmif.h or similar] would be better fit.
>> +
>> +
>> +When and how to update these files
>> +----------------------------------
>> +Ideally on each libdrm release these will be kept in sync, with the latest
>> +released kernels. This way users won't need to provide local definitions.
>> +
>> +In order to update the files do the following:
>> + - Switch to a Linux kernel tree/branch which is not rebased.
>> +For example: airlied/drm-next, drm-misc/XXX
>
> If we just want to update it to the latest released kernel, why not
> just specify Linus' tree?  There's a chance there may be flux in -next
> that you wouldn't necessarily want in libdrm.
My understanding is that things are "fully carved in stone" only as
they reach Linus. Yet things in drm-next are good enough.

>  Also, I think
> generally, it would be the individual driver maintainers or people
> working on specific core features that do this.  Does it really make
> sense to update these en masse regularly?
>
Ideally we'll mass import (update only) from Linus and do individuals
(from -next) as devs. deem fit. We want the former since devs can
forget about the latter.
Former is "not there yet", so I'll add a mention on the whole topic.

Speaking of which - can anyone from the team skim through amdgpu_drm.h
and radeon_drm.h update them.
Former is trivial, while the latter needs a closer look:
 - missing (trailing) padding -
drm_radeon_gem_{create,{g,s}et_tiling,set_domain} others ?
 - "broken" API - missing RADEON_TILING_R600_NO_SCANOUT, CIK_TILE_MODE_*

Thanks
Emil