aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorEmil Velikov2016-11-14 11:59:28 -0600
committerEmil Velikov2016-11-14 13:52:38 -0600
commitde13ea387737cdc99ec43813acb4d4f443075db2 (patch)
tree98680e26d08d8b87ec5cc4060b8bbebb2da62e8c /include
parent8cf431271a8ad33c35859da2fb0387e6bccecd44 (diff)
downloadexternal-libgbm-de13ea387737cdc99ec43813acb4d4f443075db2.tar.gz
external-libgbm-de13ea387737cdc99ec43813acb4d4f443075db2.tar.xz
external-libgbm-de13ea387737cdc99ec43813acb4d4f443075db2.zip
headers: Add README file
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. v2: - Drop drm-misc (Daniel Vetter) v3: - Elaborate on when and which headers to update - Add a list of headers and the respective "issues" - Add file to EXTRA_DIST Cc: Dave Airlie <airlied@redhat.com> Reviewed-by: Daniel Vetter <daniel.vetter@ffwll.ch> (v1) Signed-off-by: Emil Velikov <emil.l.velikov@gmail.com>
Diffstat (limited to 'include')
-rw-r--r--include/drm/README157
1 files changed, 157 insertions, 0 deletions
diff --git a/include/drm/README b/include/drm/README
new file mode 100644
index 00000000..c3292f31
--- /dev/null
+++ b/include/drm/README
@@ -0,0 +1,157 @@
1What are these headers ?
2------------------------
3This is the canonical source of drm headers that user space should use for
4communicating with the kernel DRM subsystem.
5
6They flow from the kernel, thus any changes must be merged there first.
7Do _not_ attempt to "fix" these by deviating from the kernel ones !
8
9
10Non-linux platforms - changes/patches
11-------------------------------------
12If your platform has local changes, please send them upstream for inclusion.
13Even if your patches don't get accepted in their current form, devs will
14give you feedback on how to address things properly.
15
16git send-email --subject-prefix="PATCH libdrm" your patches to dri-devel
17mailing list.
18
19Before doing so, please consider the following:
20 - Have the [libdrm vs kernel] headers on your platform deviated ?
21Consider unifying them first.
22
23 - Have you introduced additional ABI that's not available in Linux ?
24Propose it for [Linux kernel] upstream inclusion.
25If that doesn't work out (hopefully it never does), move it to another header
26and/or keep the change(s) local ?
27
28 - Are your changes DRI1/UMS specific ?
29There is virtually no interest/power in keeping those legacy interfaces. They
30are around due to the kernel "thou shalt not break existing user space" rule.
31
32Consider porting the driver to DRI2/KMS - all (almost?) sensible hardware is
33capable of supporting those.
34
35
36Which headers go where ?
37------------------------
38A 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
44Obviously the r300 and via headers are no longer around ;-)
45
46Reason behind is that the drm headers can be used as a basic communications
47channel with the respective kernel modules. If more advanced functionality is
48required one can pull the specific libdrm_$driver which is free to pull
49additional files from the kernel.
50
51For example: nouveau has nouveau/nvif/*.h while vc4 has vc4/*.h
52
53If 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
55definitions and access [via $driver_drmif.h or similar] would be better fit.
56
57
58When and which headers to update
59--------------------------------
60Ideally all files will be synced (updated) with the latest released kernel on
61each libdrm release. Sadly that's not yet possible since quite a few headers
62differ significantly - see Outdated or Broken Headers section below.
63
64That said, it's up-to the individual developers to sync with newer version
65(from drm-next) as they see fit.
66
67
68When and how to update these files
69----------------------------------
70In order to update the files do the following:
71 - Switch to a Linux kernel tree/branch which is not rebased.
72For example: airlied/drm-next
73 - Install the headers via `make headers_install' to a separate location.
74 - Copy the drm header[s] + git add + git commit.
75 - Note: Your commit message must include:
76 a) Brief summary on the delta. If there's any change that looks like an
77API/ABI break one _must_ explicitly state why it's safe to do so.
78 b) "Generated using make headers_install."
79 c) "Generated from $tree/branch commit $sha"
80
81
82Outdated or Broken Headers
83--------------------------
84This section contains a list of headers and the respective "issues" they might
85have relative to their kernel equivalent.
86
87Nearly all headers:
88 - Missing extern C notation.
89Status: Trivial.
90
91Most UMS headers:
92 - Not using fixed size interers - compat ioctls are broken.
93Status: ?
94Promote to fixed size ints, which match the current (32bit) ones.
95
96
97amdgpu_drm.h
98 - Using the stdint.h uint*_t over the respective __u* ones
99Status: Trivial.
100
101drm_mode.h
102 - Missing DPI encode/connector pair.
103Status: Trivial.
104
105i915_drm.h
106 - Missing PARAMS - HAS_POOLED_EU, MIN_EU_IN_POOL CONTEXT_PARAM_NO_ERROR_CAPTURE
107Status: Trivial.
108
109mga_drm.h
110 - Typo fix, use struct over typedef.
111Status: Trivial.
112
113nouveau_drm.h
114 - Missing macros NOUVEAU_GETPARAM*, NOUVEAU_DRM_HEADER_PATCHLEVEL, structs,
115enums, using stdint.h over the __u* types.
116Status: ?
117
118qxl_drm.h
119 - Using the stdint.h uint*_t over the respective __u* ones
120Status: Trivial.
121
122r128_drm.h
123 - Broken compat ioctls.
124
125radeon_drm.h
126 - Missing RADEON_TILING_R600_NO_SCANOUT, CIK_TILE_MODE_*, broken UMS ioctls,
127using stdint types.
128 - Both kernel and libdrm: missing padding -
129drm_radeon_gem_{create,{g,s}et_tiling,set_domain} others ?
130Status: ?
131
132savage_drm.h
133 - Renamed ioctls - DRM_IOCTL_SAVAGE_{,BCI}_EVENT_EMIT, compat ioctls are broken.
134Status: ?
135
136sis_drm.h
137 - Borken ioctls + libdrm uses int vs kernel long
138Status: ?
139
140via_drm.h
141 - Borken ioctls - libdrm int vs kernel long
142Status: ?
143
144
145omap_drm.h (living in $TOP/omap)
146 - License mismatch, missing DRM_IOCTL_OMAP_GEM_NEW and related struct
147Status: ?
148
149msm_drm.h (located in $TOP/freedreno/msm/)
150 - License mismatch, missing MSM_PIPE_*, MSM_SUBMIT_*. Renamed
151drm_msm_gem_submit::flags, missing drm_msm_gem_submit::fence_fd.
152Status: ?
153
154exynos_drm.h (living in $TOP/exynos)
155 - License mismatch, now using fixed size ints (but not everywhere). Lots of
156new stuff.
157Status: ?