[PATCH libdrm] headers: Add README file

[Emil Velikov]

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
+ - Install the headers via `make headers_install' to a separate location.
+ - Copy the drm header[s] + git add + git commit.
+ - Note: Your commit message must include:
+   a) Brief summary on the delta. If there's any change that looks like an
+API/ABI break one _must_ explicitly state why it's safe to do so.
+   b) "Generated using make headers_install."
+   c) "Generated from $tree/branch commit $sha"
-- 
2.9.3