| 1 |
What are these headers ? |
| 2 |
------------------------ |
| 3 |
This is the canonical source of drm headers that user space should use for |
| 4 |
communicating with the kernel DRM subsystem. |
| 5 |
|
| 6 |
They flow from the kernel, thus any changes must be merged there first. |
| 7 |
Do _not_ attempt to "fix" these by deviating from the kernel ones ! |
| 8 |
|
| 9 |
|
| 10 |
Non-linux platforms - changes/patches |
| 11 |
------------------------------------- |
| 12 |
If your platform has local changes, please send them upstream for inclusion. |
| 13 |
Even if your patches don't get accepted in their current form, devs will |
| 14 |
give you feedback on how to address things properly. |
| 15 |
|
| 16 |
git send-email --subject-prefix="PATCH libdrm" your patches to dri-devel |
| 17 |
mailing list. |
| 18 |
|
| 19 |
Before doing so, please consider the following: |
| 20 |
- Have the [libdrm vs kernel] headers on your platform deviated ? |
| 21 |
Consider unifying them first. |
| 22 |
|
| 23 |
- Have you introduced additional ABI that's not available in Linux ? |
| 24 |
Propose it for [Linux kernel] upstream inclusion. |
| 25 |
If that doesn't work out (hopefully it never does), move it to another header |
| 26 |
and/or keep the change(s) local ? |
| 27 |
|
| 28 |
- Are your changes DRI1/UMS specific ? |
| 29 |
There is virtually no interest/power in keeping those legacy interfaces. They |
| 30 |
are around due to the kernel "thou shalt not break existing user space" rule. |
| 31 |
|
| 32 |
Consider porting the driver to DRI2/KMS - all (almost?) sensible hardware is |
| 33 |
capable of supporting those. |
| 34 |
|
| 35 |
|
| 36 |
Which headers go where ? |
| 37 |
------------------------ |
| 38 |
A snipped from the, now removed, Makefile.am used to state: |
| 39 |
|
| 40 |
XXX airlied says, nothing besides *_drm.h and drm*.h should be necessary. |
| 41 |
however, r300 and via need their reg headers installed in order to build. |
| 42 |
better solutions are welcome. |
| 43 |
|
| 44 |
Obviously the r300 and via headers are no longer around ;-) |
| 45 |
|
| 46 |
Reason behind is that the drm headers can be used as a basic communications |
| 47 |
channel with the respective kernel modules. If more advanced functionality is |
| 48 |
required one can pull the specific libdrm_$driver which is free to pull |
| 49 |
additional files from the kernel. |
| 50 |
|
| 51 |
For example: nouveau has nouveau/nvif/*.h while vc4 has vc4/*.h |
| 52 |
|
| 53 |
If your driver is still in prototyping/staging state, consider moving the |
| 54 |
$driver_drm.h into $driver and _not_ installing it. An header providing opaque |
| 55 |
definitions and access [via $driver_drmif.h or similar] would be better fit. |
| 56 |
|
| 57 |
|
| 58 |
When and which headers to update |
| 59 |
-------------------------------- |
| 60 |
Ideally all files will be synced (updated) with the latest released kernel on |
| 61 |
each libdrm release. Sadly that's not yet possible since quite a few headers |
| 62 |
differ significantly - see Outdated or Broken Headers section below. |
| 63 |
|
| 64 |
That said, it's up-to the individual developers to sync with newer version |
| 65 |
(from drm-next) as they see fit. |
| 66 |
|
| 67 |
|
| 68 |
When and how to update these files |
| 69 |
---------------------------------- |
| 70 |
Note: One should not do _any_ changes to the files apart from the steps below. |
| 71 |
|
| 72 |
In order to update the files do the following: |
| 73 |
- Switch to a Linux kernel tree/branch which is not rebased. |
| 74 |
For example: drm-next (https://gitlab.freedesktop.org/drm/kernel/) |
| 75 |
- Install the headers via `make headers_install' to a separate location. |
| 76 |
- Copy the drm header[s] + git add + git commit. |
| 77 |
- Note: Your commit message must include: |
| 78 |
a) Brief summary on the delta. If there's any change that looks like an |
| 79 |
API/ABI break one _must_ explicitly state why it's safe to do so. |
| 80 |
b) "Generated using make headers_install." |
| 81 |
c) "Generated from $tree/branch commit $sha" |
| 82 |
|
| 83 |
|
| 84 |
Outdated or Broken Headers |
| 85 |
-------------------------- |
| 86 |
This section contains a list of headers and the respective "issues" they might |
| 87 |
have relative to their kernel equivalent. |
| 88 |
|
| 89 |
Most UMS headers: |
| 90 |
- Not using fixed size integers - compat ioctls are broken. |
| 91 |
Status: ? |
| 92 |
Promote to fixed size ints, which match the current (32bit) ones. |
| 93 |
|
| 94 |
nouveau_drm.h |
| 95 |
- Missing macros NOUVEAU_GETPARAM*, NOUVEAU_DRM_HEADER_PATCHLEVEL, structs, |
| 96 |
enums |
| 97 |
Status: Deliberate UABI choice; nouveau hides the exact kernel ABI behind libdrm |
| 98 |
|
| 99 |
r128_drm.h |
| 100 |
- Broken compat ioctls. |
| 101 |
|
| 102 |
radeon_drm.h |
| 103 |
- Missing RADEON_TILING_R600_NO_SCANOUT, CIK_TILE_MODE_*, broken UMS ioctls |
| 104 |
- Both kernel and libdrm: missing padding - |
| 105 |
drm_radeon_gem_{create,{g,s}et_tiling,set_domain} others ? |
| 106 |
Status: ? |
| 107 |
|
| 108 |
savage_drm.h |
| 109 |
- Renamed ioctls - DRM_IOCTL_SAVAGE_{,BCI}_EVENT_EMIT, compat ioctls are broken. |
| 110 |
Status: ? |
| 111 |
|
| 112 |
sis_drm.h |
| 113 |
- Borken ioctls + libdrm uses int vs kernel long |
| 114 |
Status: ? |
| 115 |
|
| 116 |
via_drm.h |
| 117 |
- Borken ioctls - libdrm int vs kernel long |
| 118 |
Status: ? |
| 119 |
|
| 120 |
|
| 121 |
omap_drm.h (living in $TOP/omap) |
| 122 |
- License mismatch, missing DRM_IOCTL_OMAP_GEM_NEW and related struct |
| 123 |
Status: ? |
| 124 |
|
| 125 |
exynos_drm.h (living in $TOP/exynos) |
| 126 |
- License mismatch, now using fixed size ints (but not everywhere). Lots of |
| 127 |
new stuff. |
| 128 |
Status: ? |