1=============================
2Mode Setting Helper Functions
3=============================
4
5The DRM subsystem aims for a strong separation between core code and helper
6libraries. Core code takes care of general setup and teardown and decoding
7userspace requests to kernel internal objects. Everything else is handled by a
8large set of helper libraries, which can be combined freely to pick and choose
9for each driver what fits, and avoid shared code where special behaviour is
10needed.
11
12This distinction between core code and helpers is especially strong in the
13modesetting code, where there's a shared userspace ABI for all drivers. This is
14in contrast to the render side, where pretty much everything (with very few
15exceptions) can be considered optional helper code.
16
17There 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
36Modeset 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
47Atomic Modeset Helper Functions Reference
48=========================================
49
50Overview
51--------
52
53.. kernel-doc:: drivers/gpu/drm/drm_atomic_helper.c
54   :doc: overview
55
56Implementing Asynchronous Atomic Commit
57---------------------------------------
58
59.. kernel-doc:: drivers/gpu/drm/drm_atomic_helper.c
60   :doc: implementing nonblocking commit
61
62Helper 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
71Atomic 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
77Atomic State Helper Reference
78-----------------------------
79
80.. kernel-doc:: drivers/gpu/drm/drm_atomic_state_helper.c
81   :export:
82
83GEM Atomic Helper Reference
84---------------------------
85
86.. kernel-doc:: drivers/gpu/drm/drm_gem_atomic_helper.c
87   :doc: overview
88
89.. kernel-doc:: include/drm/drm_gem_atomic_helper.h
90   :internal:
91
92.. kernel-doc:: drivers/gpu/drm/drm_gem_atomic_helper.c
93   :export:
94
95Simple KMS Helper Reference
96===========================
97
98.. kernel-doc:: drivers/gpu/drm/drm_simple_kms_helper.c
99   :doc: overview
100
101.. kernel-doc:: include/drm/drm_simple_kms_helper.h
102   :internal:
103
104.. kernel-doc:: drivers/gpu/drm/drm_simple_kms_helper.c
105   :export:
106
107fbdev Helper Functions Reference
108================================
109
110.. kernel-doc:: drivers/gpu/drm/drm_fb_helper.c
111   :doc: fbdev helpers
112
113.. kernel-doc:: include/drm/drm_fb_helper.h
114   :internal:
115
116.. kernel-doc:: drivers/gpu/drm/drm_fb_helper.c
117   :export:
118
119.. kernel-doc:: drivers/gpu/drm/drm_fbdev_generic.c
120   :export:
121
122format Helper Functions Reference
123=================================
124
125.. kernel-doc:: drivers/gpu/drm/drm_format_helper.c
126   :export:
127
128Framebuffer DMA Helper Functions Reference
129==========================================
130
131.. kernel-doc:: drivers/gpu/drm/drm_fb_dma_helper.c
132   :doc: framebuffer dma helper functions
133
134.. kernel-doc:: drivers/gpu/drm/drm_fb_dma_helper.c
135   :export:
136
137Framebuffer GEM Helper Reference
138================================
139
140.. kernel-doc:: drivers/gpu/drm/drm_gem_framebuffer_helper.c
141   :doc: overview
142
143.. kernel-doc:: drivers/gpu/drm/drm_gem_framebuffer_helper.c
144   :export:
145
146.. _drm_bridges:
147
148Bridges
149=======
150
151Overview
152--------
153
154.. kernel-doc:: drivers/gpu/drm/drm_bridge.c
155   :doc: overview
156
157Display Driver Integration
158--------------------------
159
160.. kernel-doc:: drivers/gpu/drm/drm_bridge.c
161   :doc: display driver integration
162
163Special Care with MIPI-DSI bridges
164----------------------------------
165
166.. kernel-doc:: drivers/gpu/drm/drm_bridge.c
167   :doc: special care dsi
168
169Bridge Operations
170-----------------
171
172.. kernel-doc:: drivers/gpu/drm/drm_bridge.c
173   :doc: bridge operations
174
175Bridge Connector Helper
176-----------------------
177
178.. kernel-doc:: drivers/gpu/drm/drm_bridge_connector.c
179   :doc: overview
180
181
182Bridge Helper Reference
183-------------------------
184
185.. kernel-doc:: include/drm/drm_bridge.h
186   :internal:
187
188.. kernel-doc:: drivers/gpu/drm/drm_bridge.c
189   :export:
190
191Bridge Connector Helper Reference
192---------------------------------
193
194.. kernel-doc:: drivers/gpu/drm/drm_bridge_connector.c
195   :export:
196
197Panel-Bridge Helper Reference
198-----------------------------
199
200.. kernel-doc:: drivers/gpu/drm/bridge/panel.c
201   :export:
202
203.. _drm_panel_helper:
204
205Panel Helper Reference
206======================
207
208.. kernel-doc:: drivers/gpu/drm/drm_panel.c
209   :doc: drm panel
210
211.. kernel-doc:: include/drm/drm_panel.h
212   :internal:
213
214.. kernel-doc:: drivers/gpu/drm/drm_panel.c
215   :export:
216
217.. kernel-doc:: drivers/gpu/drm/drm_panel_orientation_quirks.c
218   :export:
219
220Panel Self Refresh Helper Reference
221===================================
222
223.. kernel-doc:: drivers/gpu/drm/drm_self_refresh_helper.c
224   :doc: overview
225
226.. kernel-doc:: drivers/gpu/drm/drm_self_refresh_helper.c
227   :export:
228
229HDCP Helper Functions Reference
230===============================
231
232.. kernel-doc:: drivers/gpu/drm/display/drm_hdcp_helper.c
233   :export:
234
235Display Port Helper Functions Reference
236=======================================
237
238.. kernel-doc:: drivers/gpu/drm/display/drm_dp_helper.c
239   :doc: dp helpers
240
241.. kernel-doc:: include/drm/display/drm_dp.h
242   :internal:
243
244.. kernel-doc:: include/drm/display/drm_dp_helper.h
245   :internal:
246
247.. kernel-doc:: drivers/gpu/drm/display/drm_dp_helper.c
248   :export:
249
250Display Port CEC Helper Functions Reference
251===========================================
252
253.. kernel-doc:: drivers/gpu/drm/display/drm_dp_cec.c
254   :doc: dp cec helpers
255
256.. kernel-doc:: drivers/gpu/drm/display/drm_dp_cec.c
257   :export:
258
259Display Port Dual Mode Adaptor Helper Functions Reference
260=========================================================
261
262.. kernel-doc:: drivers/gpu/drm/display/drm_dp_dual_mode_helper.c
263   :doc: dp dual mode helpers
264
265.. kernel-doc:: include/drm/display/drm_dp_dual_mode_helper.h
266   :internal:
267
268.. kernel-doc:: drivers/gpu/drm/display/drm_dp_dual_mode_helper.c
269   :export:
270
271Display Port MST Helpers
272========================
273
274Overview
275--------
276
277.. kernel-doc:: drivers/gpu/drm/display/drm_dp_mst_topology.c
278   :doc: dp mst helper
279
280.. kernel-doc:: drivers/gpu/drm/display/drm_dp_mst_topology.c
281   :doc: Branch device and port refcounting
282
283Functions Reference
284-------------------
285
286.. kernel-doc:: include/drm/display/drm_dp_mst_helper.h
287   :internal:
288
289.. kernel-doc:: drivers/gpu/drm/display/drm_dp_mst_topology.c
290   :export:
291
292Topology Lifetime Internals
293---------------------------
294
295These functions aren't exported to drivers, but are documented here to help make
296the MST topology helpers easier to understand
297
298.. kernel-doc:: drivers/gpu/drm/display/drm_dp_mst_topology.c
299   :functions: drm_dp_mst_topology_try_get_mstb drm_dp_mst_topology_get_mstb
300               drm_dp_mst_topology_put_mstb
301               drm_dp_mst_topology_try_get_port drm_dp_mst_topology_get_port
302               drm_dp_mst_topology_put_port
303               drm_dp_mst_get_mstb_malloc drm_dp_mst_put_mstb_malloc
304
305MIPI DBI Helper Functions Reference
306===================================
307
308.. kernel-doc:: drivers/gpu/drm/drm_mipi_dbi.c
309   :doc: overview
310
311.. kernel-doc:: include/drm/drm_mipi_dbi.h
312   :internal:
313
314.. kernel-doc:: drivers/gpu/drm/drm_mipi_dbi.c
315   :export:
316
317MIPI DSI Helper Functions Reference
318===================================
319
320.. kernel-doc:: drivers/gpu/drm/drm_mipi_dsi.c
321   :doc: dsi helpers
322
323.. kernel-doc:: include/drm/drm_mipi_dsi.h
324   :internal:
325
326.. kernel-doc:: drivers/gpu/drm/drm_mipi_dsi.c
327   :export:
328
329Display Stream Compression Helper Functions Reference
330=====================================================
331
332.. kernel-doc:: drivers/gpu/drm/display/drm_dsc_helper.c
333   :doc: dsc helpers
334
335.. kernel-doc:: include/drm/display/drm_dsc.h
336   :internal:
337
338.. kernel-doc:: drivers/gpu/drm/display/drm_dsc_helper.c
339   :export:
340
341Output Probing Helper Functions Reference
342=========================================
343
344.. kernel-doc:: drivers/gpu/drm/drm_probe_helper.c
345   :doc: output probing helper overview
346
347.. kernel-doc:: drivers/gpu/drm/drm_probe_helper.c
348   :export:
349
350EDID Helper Functions Reference
351===============================
352
353.. kernel-doc:: include/drm/drm_edid.h
354   :internal:
355
356.. kernel-doc:: drivers/gpu/drm/drm_edid.c
357   :export:
358
359SCDC Helper Functions Reference
360===============================
361
362.. kernel-doc:: drivers/gpu/drm/display/drm_scdc_helper.c
363   :doc: scdc helpers
364
365.. kernel-doc:: include/drm/display/drm_scdc_helper.h
366   :internal:
367
368.. kernel-doc:: drivers/gpu/drm/display/drm_scdc_helper.c
369   :export:
370
371HDMI Infoframes Helper Reference
372================================
373
374Strictly speaking this is not a DRM helper library but generally useable
375by any driver interfacing with HDMI outputs like v4l or alsa drivers.
376But it nicely fits into the overall topic of mode setting helper
377libraries and hence is also included here.
378
379.. kernel-doc:: include/linux/hdmi.h
380   :internal:
381
382.. kernel-doc:: drivers/video/hdmi.c
383   :export:
384
385Rectangle Utilities Reference
386=============================
387
388.. kernel-doc:: include/drm/drm_rect.h
389   :doc: rect utils
390
391.. kernel-doc:: include/drm/drm_rect.h
392   :internal:
393
394.. kernel-doc:: drivers/gpu/drm/drm_rect.c
395   :export:
396
397Flip-work Helper Reference
398==========================
399
400.. kernel-doc:: include/drm/drm_flip_work.h
401   :doc: flip utils
402
403.. kernel-doc:: include/drm/drm_flip_work.h
404   :internal:
405
406.. kernel-doc:: drivers/gpu/drm/drm_flip_work.c
407   :export:
408
409Auxiliary Modeset Helpers
410=========================
411
412.. kernel-doc:: drivers/gpu/drm/drm_modeset_helper.c
413   :doc: aux kms helpers
414
415.. kernel-doc:: drivers/gpu/drm/drm_modeset_helper.c
416   :export:
417
418OF/DT Helpers
419=============
420
421.. kernel-doc:: drivers/gpu/drm/drm_of.c
422   :doc: overview
423
424.. kernel-doc:: drivers/gpu/drm/drm_of.c
425   :export:
426
427Legacy Plane Helper Reference
428=============================
429
430.. kernel-doc:: drivers/gpu/drm/drm_plane_helper.c
431   :doc: overview
432
433.. kernel-doc:: drivers/gpu/drm/drm_plane_helper.c
434   :export:
435
436Legacy CRTC/Modeset Helper Functions Reference
437==============================================
438
439.. kernel-doc:: drivers/gpu/drm/drm_crtc_helper.c
440   :doc: overview
441
442.. kernel-doc:: drivers/gpu/drm/drm_crtc_helper.c
443   :export:
444
445Privacy-screen class
446====================
447
448.. kernel-doc:: drivers/gpu/drm/drm_privacy_screen.c
449   :doc: overview
450
451.. kernel-doc:: include/drm/drm_privacy_screen_driver.h
452   :internal:
453
454.. kernel-doc:: include/drm/drm_privacy_screen_machine.h
455   :internal:
456
457.. kernel-doc:: drivers/gpu/drm/drm_privacy_screen.c
458   :export:
459