From: Emil Velikov <emil.veli...@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
