[PATCH libdrm] headers: Add README file

[Marek Olšák]

On Fri, Nov 11, 2016 at 5:21 PM, Alex Deucher <alexdeucher at gmail.com> wrote:
> 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.

RADEON_TILING_R600_NO_SCANOUT must stay.

The rest can be moved to radeon/radeon_surface.c.

Compile-test Mesa and DDXs to verify that they are not broken by
changes in radeon_drm.h.

Marek