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
119format Helper Functions Reference
120=================================
121
122.. kernel-doc:: drivers/gpu/drm/drm_format_helper.c
123   :export:
124
125Framebuffer DMA Helper Functions Reference
126==========================================
127
128.. kernel-doc:: drivers/gpu/drm/drm_fb_dma_helper.c
129   :doc: framebuffer dma helper functions
130
131.. kernel-doc:: drivers/gpu/drm/drm_fb_dma_helper.c
132   :export:
133
134Framebuffer GEM Helper Reference
135================================
136
137.. kernel-doc:: drivers/gpu/drm/drm_gem_framebuffer_helper.c
138   :doc: overview
139
140.. kernel-doc:: drivers/gpu/drm/drm_gem_framebuffer_helper.c
141   :export:
142
143.. _drm_bridges:
144
145Bridges
146=======
147
148Overview
149--------
150
151.. kernel-doc:: drivers/gpu/drm/drm_bridge.c
152   :doc: overview
153
154Display Driver Integration
155--------------------------
156
157.. kernel-doc:: drivers/gpu/drm/drm_bridge.c
158   :doc: display driver integration
159
160Special Care with MIPI-DSI bridges
161----------------------------------
162
163.. kernel-doc:: drivers/gpu/drm/drm_bridge.c
164   :doc: special care dsi
165
166Bridge Operations
167-----------------
168
169.. kernel-doc:: drivers/gpu/drm/drm_bridge.c
170   :doc: bridge operations
171
172Bridge Connector Helper
173-----------------------
174
175.. kernel-doc:: drivers/gpu/drm/display/drm_bridge_connector.c
176   :doc: overview
177
178
179Bridge Helper Reference
180-------------------------
181
182.. kernel-doc:: include/drm/drm_bridge.h
183   :internal:
184
185.. kernel-doc:: drivers/gpu/drm/drm_bridge.c
186   :export:
187
188MIPI-DSI bridge operation
189-------------------------
190
191.. kernel-doc:: drivers/gpu/drm/drm_bridge.c
192   :doc: dsi bridge operations
193
194
195Bridge Connector Helper Reference
196---------------------------------
197
198.. kernel-doc:: drivers/gpu/drm/display/drm_bridge_connector.c
199   :export:
200
201Panel-Bridge Helper Reference
202-----------------------------
203
204.. kernel-doc:: drivers/gpu/drm/bridge/panel.c
205   :export:
206
207.. _drm_panel_helper:
208
209Panel Helper Reference
210======================
211
212.. kernel-doc:: drivers/gpu/drm/drm_panel.c
213   :doc: drm panel
214
215.. kernel-doc:: include/drm/drm_panel.h
216   :internal:
217
218.. kernel-doc:: drivers/gpu/drm/drm_panel.c
219   :export:
220
221.. kernel-doc:: drivers/gpu/drm/drm_panel_orientation_quirks.c
222   :export:
223
224.. kernel-doc:: drivers/gpu/drm/drm_panel_backlight_quirks.c
225   :export:
226
227Panel Self Refresh Helper Reference
228===================================
229
230.. kernel-doc:: drivers/gpu/drm/drm_self_refresh_helper.c
231   :doc: overview
232
233.. kernel-doc:: drivers/gpu/drm/drm_self_refresh_helper.c
234   :export:
235
236HDMI Atomic State Helpers
237=========================
238
239Overview
240--------
241
242.. kernel-doc:: drivers/gpu/drm/display/drm_hdmi_state_helper.c
243   :doc: hdmi helpers
244
245Functions Reference
246-------------------
247
248.. kernel-doc:: drivers/gpu/drm/display/drm_hdmi_state_helper.c
249   :export:
250
251HDCP Helper Functions Reference
252===============================
253
254.. kernel-doc:: drivers/gpu/drm/display/drm_hdcp_helper.c
255   :export:
256
257Display Port Helper Functions Reference
258=======================================
259
260.. kernel-doc:: drivers/gpu/drm/display/drm_dp_helper.c
261   :doc: dp helpers
262
263.. kernel-doc:: include/drm/display/drm_dp.h
264   :internal:
265
266.. kernel-doc:: include/drm/display/drm_dp_helper.h
267   :internal:
268
269.. kernel-doc:: drivers/gpu/drm/display/drm_dp_helper.c
270   :export:
271
272Display Port CEC Helper Functions Reference
273===========================================
274
275.. kernel-doc:: drivers/gpu/drm/display/drm_dp_cec.c
276   :doc: dp cec helpers
277
278.. kernel-doc:: drivers/gpu/drm/display/drm_dp_cec.c
279   :export:
280
281Display Port Dual Mode Adaptor Helper Functions Reference
282=========================================================
283
284.. kernel-doc:: drivers/gpu/drm/display/drm_dp_dual_mode_helper.c
285   :doc: dp dual mode helpers
286
287.. kernel-doc:: include/drm/display/drm_dp_dual_mode_helper.h
288   :internal:
289
290.. kernel-doc:: drivers/gpu/drm/display/drm_dp_dual_mode_helper.c
291   :export:
292
293Display Port MST Helpers
294========================
295
296Overview
297--------
298
299.. kernel-doc:: drivers/gpu/drm/display/drm_dp_mst_topology.c
300   :doc: dp mst helper
301
302.. kernel-doc:: drivers/gpu/drm/display/drm_dp_mst_topology.c
303   :doc: Branch device and port refcounting
304
305Functions Reference
306-------------------
307
308.. kernel-doc:: include/drm/display/drm_dp_mst_helper.h
309   :internal:
310
311.. kernel-doc:: drivers/gpu/drm/display/drm_dp_mst_topology.c
312   :export:
313
314Topology Lifetime Internals
315---------------------------
316
317These functions aren't exported to drivers, but are documented here to help make
318the MST topology helpers easier to understand
319
320.. kernel-doc:: drivers/gpu/drm/display/drm_dp_mst_topology.c
321   :functions: drm_dp_mst_topology_try_get_mstb drm_dp_mst_topology_get_mstb
322               drm_dp_mst_topology_put_mstb
323               drm_dp_mst_topology_try_get_port drm_dp_mst_topology_get_port
324               drm_dp_mst_topology_put_port
325               drm_dp_mst_get_mstb_malloc drm_dp_mst_put_mstb_malloc
326
327MIPI DBI Helper Functions Reference
328===================================
329
330.. kernel-doc:: drivers/gpu/drm/drm_mipi_dbi.c
331   :doc: overview
332
333.. kernel-doc:: include/drm/drm_mipi_dbi.h
334   :internal:
335
336.. kernel-doc:: drivers/gpu/drm/drm_mipi_dbi.c
337   :export:
338
339MIPI DSI Helper Functions Reference
340===================================
341
342.. kernel-doc:: drivers/gpu/drm/drm_mipi_dsi.c
343   :doc: dsi helpers
344
345.. kernel-doc:: include/drm/drm_mipi_dsi.h
346   :internal:
347
348.. kernel-doc:: drivers/gpu/drm/drm_mipi_dsi.c
349   :export:
350
351Display Stream Compression Helper Functions Reference
352=====================================================
353
354.. kernel-doc:: drivers/gpu/drm/display/drm_dsc_helper.c
355   :doc: dsc helpers
356
357.. kernel-doc:: include/drm/display/drm_dsc.h
358   :internal:
359
360.. kernel-doc:: drivers/gpu/drm/display/drm_dsc_helper.c
361   :export:
362
363Output Probing Helper Functions Reference
364=========================================
365
366.. kernel-doc:: drivers/gpu/drm/drm_probe_helper.c
367   :doc: output probing helper overview
368
369.. kernel-doc:: drivers/gpu/drm/drm_probe_helper.c
370   :export:
371
372EDID Helper Functions Reference
373===============================
374
375.. kernel-doc:: include/drm/drm_edid.h
376   :internal:
377
378.. kernel-doc:: drivers/gpu/drm/drm_edid.c
379   :export:
380
381.. kernel-doc:: include/drm/drm_eld.h
382   :internal:
383
384.. kernel-doc:: drivers/gpu/drm/drm_eld.c
385   :export:
386
387SCDC Helper Functions Reference
388===============================
389
390.. kernel-doc:: drivers/gpu/drm/display/drm_scdc_helper.c
391   :doc: scdc helpers
392
393.. kernel-doc:: include/drm/display/drm_scdc_helper.h
394   :internal:
395
396.. kernel-doc:: drivers/gpu/drm/display/drm_scdc_helper.c
397   :export:
398
399HDMI Infoframes Helper Reference
400================================
401
402Strictly speaking this is not a DRM helper library but generally usable
403by any driver interfacing with HDMI outputs like v4l or alsa drivers.
404But it nicely fits into the overall topic of mode setting helper
405libraries and hence is also included here.
406
407.. kernel-doc:: include/linux/hdmi.h
408   :internal:
409
410.. kernel-doc:: drivers/video/hdmi.c
411   :export:
412
413Rectangle Utilities Reference
414=============================
415
416.. kernel-doc:: include/drm/drm_rect.h
417   :doc: rect utils
418
419.. kernel-doc:: include/drm/drm_rect.h
420   :internal:
421
422.. kernel-doc:: drivers/gpu/drm/drm_rect.c
423   :export:
424
425Flip-work Helper Reference
426==========================
427
428.. kernel-doc:: include/drm/drm_flip_work.h
429   :doc: flip utils
430
431.. kernel-doc:: include/drm/drm_flip_work.h
432   :internal:
433
434.. kernel-doc:: drivers/gpu/drm/drm_flip_work.c
435   :export:
436
437Auxiliary Modeset Helpers
438=========================
439
440.. kernel-doc:: drivers/gpu/drm/drm_modeset_helper.c
441   :doc: aux kms helpers
442
443.. kernel-doc:: drivers/gpu/drm/drm_modeset_helper.c
444   :export:
445
446OF/DT Helpers
447=============
448
449.. kernel-doc:: drivers/gpu/drm/drm_of.c
450   :doc: overview
451
452.. kernel-doc:: drivers/gpu/drm/drm_of.c
453   :export:
454
455Legacy Plane Helper Reference
456=============================
457
458.. kernel-doc:: drivers/gpu/drm/drm_plane_helper.c
459   :doc: overview
460
461.. kernel-doc:: drivers/gpu/drm/drm_plane_helper.c
462   :export:
463
464Legacy CRTC/Modeset Helper Functions Reference
465==============================================
466
467.. kernel-doc:: drivers/gpu/drm/drm_crtc_helper.c
468   :doc: overview
469
470.. kernel-doc:: drivers/gpu/drm/drm_crtc_helper.c
471   :export:
472
473Privacy-screen class
474====================
475
476.. kernel-doc:: drivers/gpu/drm/drm_privacy_screen.c
477   :doc: overview
478
479.. kernel-doc:: include/drm/drm_privacy_screen_driver.h
480   :internal:
481
482.. kernel-doc:: include/drm/drm_privacy_screen_machine.h
483   :internal:
484
485.. kernel-doc:: drivers/gpu/drm/drm_privacy_screen.c
486   :export:
487