diff options
Diffstat (limited to 'include')
-rw-r--r-- | include/drm/README | 157 |
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 @@ | |||
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 | In order to update the files do the following: | ||
71 | - Switch to a Linux kernel tree/branch which is not rebased. | ||
72 | For 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 | ||
77 | API/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 | |||
82 | Outdated or Broken Headers | ||
83 | -------------------------- | ||
84 | This section contains a list of headers and the respective "issues" they might | ||
85 | have relative to their kernel equivalent. | ||
86 | |||
87 | Nearly all headers: | ||
88 | - Missing extern C notation. | ||
89 | Status: Trivial. | ||
90 | |||
91 | Most UMS headers: | ||
92 | - Not using fixed size interers - compat ioctls are broken. | ||
93 | Status: ? | ||
94 | Promote to fixed size ints, which match the current (32bit) ones. | ||
95 | |||
96 | |||
97 | amdgpu_drm.h | ||
98 | - Using the stdint.h uint*_t over the respective __u* ones | ||
99 | Status: Trivial. | ||
100 | |||
101 | drm_mode.h | ||
102 | - Missing DPI encode/connector pair. | ||
103 | Status: Trivial. | ||
104 | |||
105 | i915_drm.h | ||
106 | - Missing PARAMS - HAS_POOLED_EU, MIN_EU_IN_POOL CONTEXT_PARAM_NO_ERROR_CAPTURE | ||
107 | Status: Trivial. | ||
108 | |||
109 | mga_drm.h | ||
110 | - Typo fix, use struct over typedef. | ||
111 | Status: Trivial. | ||
112 | |||
113 | nouveau_drm.h | ||
114 | - Missing macros NOUVEAU_GETPARAM*, NOUVEAU_DRM_HEADER_PATCHLEVEL, structs, | ||
115 | enums, using stdint.h over the __u* types. | ||
116 | Status: ? | ||
117 | |||
118 | qxl_drm.h | ||
119 | - Using the stdint.h uint*_t over the respective __u* ones | ||
120 | Status: Trivial. | ||
121 | |||
122 | r128_drm.h | ||
123 | - Broken compat ioctls. | ||
124 | |||
125 | radeon_drm.h | ||
126 | - Missing RADEON_TILING_R600_NO_SCANOUT, CIK_TILE_MODE_*, broken UMS ioctls, | ||
127 | using stdint types. | ||
128 | - Both kernel and libdrm: missing padding - | ||
129 | drm_radeon_gem_{create,{g,s}et_tiling,set_domain} others ? | ||
130 | Status: ? | ||
131 | |||
132 | savage_drm.h | ||
133 | - Renamed ioctls - DRM_IOCTL_SAVAGE_{,BCI}_EVENT_EMIT, compat ioctls are broken. | ||
134 | Status: ? | ||
135 | |||
136 | sis_drm.h | ||
137 | - Borken ioctls + libdrm uses int vs kernel long | ||
138 | Status: ? | ||
139 | |||
140 | via_drm.h | ||
141 | - Borken ioctls - libdrm int vs kernel long | ||
142 | Status: ? | ||
143 | |||
144 | |||
145 | omap_drm.h (living in $TOP/omap) | ||
146 | - License mismatch, missing DRM_IOCTL_OMAP_GEM_NEW and related struct | ||
147 | Status: ? | ||
148 | |||
149 | msm_drm.h (located in $TOP/freedreno/msm/) | ||
150 | - License mismatch, missing MSM_PIPE_*, MSM_SUBMIT_*. Renamed | ||
151 | drm_msm_gem_submit::flags, missing drm_msm_gem_submit::fence_fd. | ||
152 | Status: ? | ||
153 | |||
154 | exynos_drm.h (living in $TOP/exynos) | ||
155 | - License mismatch, now using fixed size ints (but not everywhere). Lots of | ||
156 | new stuff. | ||
157 | Status: ? | ||