Merge tag 'armsoc-dt' of git://git.kernel.org/pub/scm/linux/kernel/git/soc/soc
[sfrench/cifs-2.6.git] / Documentation / gpu / drm-kms-helpers.rst
1 =============================
2 Mode Setting Helper Functions
3 =============================
4
5 The DRM subsystem aims for a strong separation between core code and helper
6 libraries. Core code takes care of general setup and teardown and decoding
7 userspace requests to kernel internal objects. Everything else is handled by a
8 large set of helper libraries, which can be combined freely to pick and choose
9 for each driver what fits, and avoid shared code where special behaviour is
10 needed.
11
12 This distinction between core code and helpers is especially strong in the
13 modesetting code, where there's a shared userspace ABI for all drivers. This is
14 in contrast to the render side, where pretty much everything (with very few
15 exceptions) can be considered optional helper code.
16
17 There are a few areas these helpers can grouped into:
18
19 * Helpers to implement modesetting. The important ones here are the atomic
20   helpers. Old drivers still often use the legacy CRTC helpers. They both share
21   the same set of common helper vtables. For really simple drivers (anything
22   that would have been a great fit in the deprecated fbdev subsystem) there's
23   also the simple display pipe helpers.
24
25 * There's a big pile of helpers for handling outputs. First the generic bridge
26   helpers for handling encoder and transcoder IP blocks. Second the panel helpers
27   for handling panel-related information and logic. Plus then a big set of
28   helpers for the various sink standards (DisplayPort, HDMI, MIPI DSI). Finally
29   there's also generic helpers for handling output probing, and for dealing with
30   EDIDs.
31
32 * The last group of helpers concerns itself with the frontend side of a display
33   pipeline: Planes, handling rectangles for visibility checking and scissoring,
34   flip queues and assorted bits.
35
36 Modeset Helper Reference for Common Vtables
37 ===========================================
38
39 .. kernel-doc:: include/drm/drm_modeset_helper_vtables.h
40    :doc: overview
41
42 .. kernel-doc:: include/drm/drm_modeset_helper_vtables.h
43    :internal:
44
45 .. _drm_atomic_helper:
46
47 Atomic Modeset Helper Functions Reference
48 =========================================
49
50 Overview
51 --------
52
53 .. kernel-doc:: drivers/gpu/drm/drm_atomic_helper.c
54    :doc: overview
55
56 Implementing Asynchronous Atomic Commit
57 ---------------------------------------
58
59 .. kernel-doc:: drivers/gpu/drm/drm_atomic_helper.c
60    :doc: implementing nonblocking commit
61
62 Helper Functions Reference
63 --------------------------
64
65 .. kernel-doc:: include/drm/drm_atomic_helper.h
66    :internal:
67
68 .. kernel-doc:: drivers/gpu/drm/drm_atomic_helper.c
69    :export:
70
71 Atomic State Reset and Initialization
72 -------------------------------------
73
74 .. kernel-doc:: drivers/gpu/drm/drm_atomic_state_helper.c
75    :doc: atomic state reset and initialization
76
77 Atomic State Helper Reference
78 -----------------------------
79
80 .. kernel-doc:: include/drm/drm_atomic_state_helper.h
81    :internal:
82
83 .. kernel-doc:: drivers/gpu/drm/drm_atomic_state_helper.c
84    :export:
85
86 Simple KMS Helper Reference
87 ===========================
88
89 .. kernel-doc:: drivers/gpu/drm/drm_simple_kms_helper.c
90    :doc: overview
91
92 .. kernel-doc:: include/drm/drm_simple_kms_helper.h
93    :internal:
94
95 .. kernel-doc:: drivers/gpu/drm/drm_simple_kms_helper.c
96    :export:
97
98 fbdev Helper Functions Reference
99 ================================
100
101 .. kernel-doc:: drivers/gpu/drm/drm_fb_helper.c
102    :doc: fbdev helpers
103
104 .. kernel-doc:: include/drm/drm_fb_helper.h
105    :internal:
106
107 .. kernel-doc:: drivers/gpu/drm/drm_fb_helper.c
108    :export:
109
110 format Helper Functions Reference
111 =================================
112
113 .. kernel-doc:: drivers/gpu/drm/drm_format_helper.c
114    :export:
115
116 Framebuffer CMA Helper Functions Reference
117 ==========================================
118
119 .. kernel-doc:: drivers/gpu/drm/drm_fb_cma_helper.c
120    :doc: framebuffer cma helper functions
121
122 .. kernel-doc:: drivers/gpu/drm/drm_fb_cma_helper.c
123    :export:
124
125 Framebuffer GEM Helper Reference
126 ================================
127
128 .. kernel-doc:: drivers/gpu/drm/drm_gem_framebuffer_helper.c
129    :doc: overview
130
131 .. kernel-doc:: drivers/gpu/drm/drm_gem_framebuffer_helper.c
132    :export:
133
134 .. _drm_bridges:
135
136 Bridges
137 =======
138
139 Overview
140 --------
141
142 .. kernel-doc:: drivers/gpu/drm/drm_bridge.c
143    :doc: overview
144
145 Default bridge callback sequence
146 --------------------------------
147
148 .. kernel-doc:: drivers/gpu/drm/drm_bridge.c
149    :doc: bridge callbacks
150
151
152 Bridge Helper Reference
153 -------------------------
154
155 .. kernel-doc:: include/drm/drm_bridge.h
156    :internal:
157
158 .. kernel-doc:: drivers/gpu/drm/drm_bridge.c
159    :export:
160
161 Panel-Bridge Helper Reference
162 -----------------------------
163
164 .. kernel-doc:: drivers/gpu/drm/bridge/panel.c
165    :export:
166
167 .. _drm_panel_helper:
168
169 Panel Helper Reference
170 ======================
171
172 .. kernel-doc:: drivers/gpu/drm/drm_panel.c
173    :doc: drm panel
174
175 .. kernel-doc:: include/drm/drm_panel.h
176    :internal:
177
178 .. kernel-doc:: drivers/gpu/drm/drm_panel.c
179    :export:
180
181 .. kernel-doc:: drivers/gpu/drm/drm_panel_orientation_quirks.c
182    :export:
183
184 Display Port Helper Functions Reference
185 =======================================
186
187 .. kernel-doc:: drivers/gpu/drm/drm_dp_helper.c
188    :doc: dp helpers
189
190 .. kernel-doc:: include/drm/drm_dp_helper.h
191    :internal:
192
193 .. kernel-doc:: drivers/gpu/drm/drm_dp_helper.c
194    :export:
195
196 Display Port CEC Helper Functions Reference
197 ===========================================
198
199 .. kernel-doc:: drivers/gpu/drm/drm_dp_cec.c
200    :doc: dp cec helpers
201
202 .. kernel-doc:: drivers/gpu/drm/drm_dp_cec.c
203    :export:
204
205 Display Port Dual Mode Adaptor Helper Functions Reference
206 =========================================================
207
208 .. kernel-doc:: drivers/gpu/drm/drm_dp_dual_mode_helper.c
209    :doc: dp dual mode helpers
210
211 .. kernel-doc:: include/drm/drm_dp_dual_mode_helper.h
212    :internal:
213
214 .. kernel-doc:: drivers/gpu/drm/drm_dp_dual_mode_helper.c
215    :export:
216
217 Display Port MST Helpers
218 ========================
219
220 Overview
221 --------
222
223 .. kernel-doc:: drivers/gpu/drm/drm_dp_mst_topology.c
224    :doc: dp mst helper
225
226 .. kernel-doc:: drivers/gpu/drm/drm_dp_mst_topology.c
227    :doc: Branch device and port refcounting
228
229 Functions Reference
230 -------------------
231
232 .. kernel-doc:: include/drm/drm_dp_mst_helper.h
233    :internal:
234
235 .. kernel-doc:: drivers/gpu/drm/drm_dp_mst_topology.c
236    :export:
237
238 Topology Lifetime Internals
239 ---------------------------
240
241 These functions aren't exported to drivers, but are documented here to help make
242 the MST topology helpers easier to understand
243
244 .. kernel-doc:: drivers/gpu/drm/drm_dp_mst_topology.c
245    :functions: drm_dp_mst_topology_try_get_mstb drm_dp_mst_topology_get_mstb
246                drm_dp_mst_topology_put_mstb
247                drm_dp_mst_topology_try_get_port drm_dp_mst_topology_get_port
248                drm_dp_mst_topology_put_port
249                drm_dp_mst_get_mstb_malloc drm_dp_mst_put_mstb_malloc
250
251 MIPI DSI Helper Functions Reference
252 ===================================
253
254 .. kernel-doc:: drivers/gpu/drm/drm_mipi_dsi.c
255    :doc: dsi helpers
256
257 .. kernel-doc:: include/drm/drm_mipi_dsi.h
258    :internal:
259
260 .. kernel-doc:: drivers/gpu/drm/drm_mipi_dsi.c
261    :export:
262
263 Display Stream Compression Helper Functions Reference
264 =====================================================
265
266 .. kernel-doc:: drivers/gpu/drm/drm_dsc.c
267    :doc: dsc helpers
268
269 .. kernel-doc:: include/drm/drm_dsc.h
270    :internal:
271
272 .. kernel-doc:: drivers/gpu/drm/drm_dsc.c
273    :export:
274
275 Output Probing Helper Functions Reference
276 =========================================
277
278 .. kernel-doc:: drivers/gpu/drm/drm_probe_helper.c
279    :doc: output probing helper overview
280
281 .. kernel-doc:: drivers/gpu/drm/drm_probe_helper.c
282    :export:
283
284 EDID Helper Functions Reference
285 ===============================
286
287 .. kernel-doc:: include/drm/drm_edid.h
288    :internal:
289
290 .. kernel-doc:: drivers/gpu/drm/drm_edid.c
291    :export:
292
293 SCDC Helper Functions Reference
294 ===============================
295
296 .. kernel-doc:: drivers/gpu/drm/drm_scdc_helper.c
297    :doc: scdc helpers
298
299 .. kernel-doc:: include/drm/drm_scdc_helper.h
300    :internal:
301
302 .. kernel-doc:: drivers/gpu/drm/drm_scdc_helper.c
303    :export:
304
305 HDMI Infoframes Helper Reference
306 ================================
307
308 Strictly speaking this is not a DRM helper library but generally useable
309 by any driver interfacing with HDMI outputs like v4l or alsa drivers.
310 But it nicely fits into the overall topic of mode setting helper
311 libraries and hence is also included here.
312
313 .. kernel-doc:: include/linux/hdmi.h
314    :internal:
315
316 .. kernel-doc:: drivers/video/hdmi.c
317    :export:
318
319 Rectangle Utilities Reference
320 =============================
321
322 .. kernel-doc:: include/drm/drm_rect.h
323    :doc: rect utils
324
325 .. kernel-doc:: include/drm/drm_rect.h
326    :internal:
327
328 .. kernel-doc:: drivers/gpu/drm/drm_rect.c
329    :export:
330
331 Flip-work Helper Reference
332 ==========================
333
334 .. kernel-doc:: include/drm/drm_flip_work.h
335    :doc: flip utils
336
337 .. kernel-doc:: include/drm/drm_flip_work.h
338    :internal:
339
340 .. kernel-doc:: drivers/gpu/drm/drm_flip_work.c
341    :export:
342
343 Auxiliary Modeset Helpers
344 =========================
345
346 .. kernel-doc:: drivers/gpu/drm/drm_modeset_helper.c
347    :doc: aux kms helpers
348
349 .. kernel-doc:: drivers/gpu/drm/drm_modeset_helper.c
350    :export:
351
352 OF/DT Helpers
353 =============
354
355 .. kernel-doc:: drivers/gpu/drm/drm_of.c
356    :doc: overview
357
358 .. kernel-doc:: drivers/gpu/drm/drm_of.c
359    :export:
360
361 Legacy Plane Helper Reference
362 =============================
363
364 .. kernel-doc:: drivers/gpu/drm/drm_plane_helper.c
365    :doc: overview
366
367 .. kernel-doc:: drivers/gpu/drm/drm_plane_helper.c
368    :export:
369
370 Legacy CRTC/Modeset Helper Functions Reference
371 ==============================================
372
373 .. kernel-doc:: drivers/gpu/drm/drm_crtc_helper.c
374    :doc: overview
375
376 .. kernel-doc:: drivers/gpu/drm/drm_crtc_helper.c
377    :export:
378
379 SHMEM GEM Helper Reference
380 ==========================
381
382 .. kernel-doc:: drivers/gpu/drm/drm_gem_shmem_helper.c
383    :doc: overview
384
385 .. kernel-doc:: include/drm/drm_gem_shmem_helper.h
386    :internal:
387
388 .. kernel-doc:: drivers/gpu/drm/drm_gem_shmem_helper.c
389    :export: