[PATCH libdrm] headers: Add README file

[Alex Deucher]

On Fri, Nov 11, 2016 at 8:44 AM, Emil Velikov <emil.l.velikov at gmail.com> wrote:
> 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_*

I think the extra stuff in radeon_drm.h in libdrm can go.  I think
Marek addressed this previously.  It was just stuck in there for
convenience IIRC.

Alex