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 CMA Helper Functions Reference
126==========================================
127
128.. kernel-doc:: drivers/gpu/drm/drm_fb_cma_helper.c
129   :doc: framebuffer cma helper functions
130
131.. kernel-doc:: drivers/gpu/drm/drm_fb_cma_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/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
188Bridge Connector Helper Reference
189---------------------------------
190
191.. kernel-doc:: drivers/gpu/drm/drm_bridge_connector.c
192   :export:
193
194Panel-Bridge Helper Reference
195-----------------------------
196
197.. kernel-doc:: drivers/gpu/drm/bridge/panel.c
198   :export:
199
200.. _drm_panel_helper:
201
202Panel Helper Reference
203======================
204
205.. kernel-doc:: drivers/gpu/drm/drm_panel.c
206   :doc: drm panel
207
208.. kernel-doc:: include/drm/drm_panel.h
209   :internal:
210
211.. kernel-doc:: drivers/gpu/drm/drm_panel.c
212   :export:
213
214.. kernel-doc:: drivers/gpu/drm/drm_panel_orientation_quirks.c
215   :export:
216
217Panel Self Refresh Helper Reference
218===================================
219
220.. kernel-doc:: drivers/gpu/drm/drm_self_refresh_helper.c
221   :doc: overview
222
223.. kernel-doc:: drivers/gpu/drm/drm_self_refresh_helper.c
224   :export:
225
226HDCP Helper Functions Reference
227===============================
228
229.. kernel-doc:: drivers/gpu/drm/display/drm_hdcp_helper.c
230   :export:
231
232Display Port Helper Functions Reference
233=======================================
234
235.. kernel-doc:: drivers/gpu/drm/display/drm_dp_helper.c
236   :doc: dp helpers
237
238.. kernel-doc:: include/drm/display/drm_dp.h
239   :internal:
240
241.. kernel-doc:: include/drm/display/drm_dp_helper.h
242   :internal:
243
244.. kernel-doc:: drivers/gpu/drm/display/drm_dp_helper.c
245   :export:
246
247Display Port CEC Helper Functions Reference
248===========================================
249
250.. kernel-doc:: drivers/gpu/drm/display/drm_dp_cec.c
251   :doc: dp cec helpers
252
253.. kernel-doc:: drivers/gpu/drm/display/drm_dp_cec.c
254   :export:
255
256Display Port Dual Mode Adaptor Helper Functions Reference
257=========================================================
258
259.. kernel-doc:: drivers/gpu/drm/display/drm_dp_dual_mode_helper.c
260   :doc: dp dual mode helpers
261
262.. kernel-doc:: include/drm/display/drm_dp_dual_mode_helper.h
263   :internal:
264
265.. kernel-doc:: drivers/gpu/drm/display/drm_dp_dual_mode_helper.c
266   :export:
267
268Display Port MST Helpers
269========================
270
271Overview
272--------
273
274.. kernel-doc:: drivers/gpu/drm/display/drm_dp_mst_topology.c
275   :doc: dp mst helper
276
277.. kernel-doc:: drivers/gpu/drm/display/drm_dp_mst_topology.c
278   :doc: Branch device and port refcounting
279
280Functions Reference
281-------------------
282
283.. kernel-doc:: include/drm/display/drm_dp_mst_helper.h
284   :internal:
285
286.. kernel-doc:: drivers/gpu/drm/display/drm_dp_mst_topology.c
287   :export:
288
289Topology Lifetime Internals
290---------------------------
291
292These functions aren't exported to drivers, but are documented here to help make
293the MST topology helpers easier to understand
294
295.. kernel-doc:: drivers/gpu/drm/display/drm_dp_mst_topology.c
296   :functions: drm_dp_mst_topology_try_get_mstb drm_dp_mst_topology_get_mstb
297               drm_dp_mst_topology_put_mstb
298               drm_dp_mst_topology_try_get_port drm_dp_mst_topology_get_port
299               drm_dp_mst_topology_put_port
300               drm_dp_mst_get_mstb_malloc drm_dp_mst_put_mstb_malloc
301
302MIPI DBI Helper Functions Reference
303===================================
304
305.. kernel-doc:: drivers/gpu/drm/drm_mipi_dbi.c
306   :doc: overview
307
308.. kernel-doc:: include/drm/drm_mipi_dbi.h
309   :internal:
310
311.. kernel-doc:: drivers/gpu/drm/drm_mipi_dbi.c
312   :export:
313
314MIPI DSI Helper Functions Reference
315===================================
316
317.. kernel-doc:: drivers/gpu/drm/drm_mipi_dsi.c
318   :doc: dsi helpers
319
320.. kernel-doc:: include/drm/drm_mipi_dsi.h
321   :internal:
322
323.. kernel-doc:: drivers/gpu/drm/drm_mipi_dsi.c
324   :export:
325
326Display Stream Compression Helper Functions Reference
327=====================================================
328
329.. kernel-doc:: drivers/gpu/drm/display/drm_dsc_helper.c
330   :doc: dsc helpers
331
332.. kernel-doc:: include/drm/display/drm_dsc.h
333   :internal:
334
335.. kernel-doc:: drivers/gpu/drm/display/drm_dsc_helper.c
336   :export:
337
338Output Probing Helper Functions Reference
339=========================================
340
341.. kernel-doc:: drivers/gpu/drm/drm_probe_helper.c
342   :doc: output probing helper overview
343
344.. kernel-doc:: drivers/gpu/drm/drm_probe_helper.c
345   :export:
346
347EDID Helper Functions Reference
348===============================
349
350.. kernel-doc:: include/drm/drm_edid.h
351   :internal:
352
353.. kernel-doc:: drivers/gpu/drm/drm_edid.c
354   :export:
355
356SCDC Helper Functions Reference
357===============================
358
359.. kernel-doc:: drivers/gpu/drm/display/drm_scdc_helper.c
360   :doc: scdc helpers
361
362.. kernel-doc:: include/drm/display/drm_scdc_helper.h
363   :internal:
364
365.. kernel-doc:: drivers/gpu/drm/display/drm_scdc_helper.c
366   :export:
367
368HDMI Infoframes Helper Reference
369================================
370
371Strictly speaking this is not a DRM helper library but generally useable
372by any driver interfacing with HDMI outputs like v4l or alsa drivers.
373But it nicely fits into the overall topic of mode setting helper
374libraries and hence is also included here.
375
376.. kernel-doc:: include/linux/hdmi.h
377   :internal:
378
379.. kernel-doc:: drivers/video/hdmi.c
380   :export:
381
382Rectangle Utilities Reference
383=============================
384
385.. kernel-doc:: include/drm/drm_rect.h
386   :doc: rect utils
387
388.. kernel-doc:: include/drm/drm_rect.h
389   :internal:
390
391.. kernel-doc:: drivers/gpu/drm/drm_rect.c
392   :export:
393
394Flip-work Helper Reference
395==========================
396
397.. kernel-doc:: include/drm/drm_flip_work.h
398   :doc: flip utils
399
400.. kernel-doc:: include/drm/drm_flip_work.h
401   :internal:
402
403.. kernel-doc:: drivers/gpu/drm/drm_flip_work.c
404   :export:
405
406Auxiliary Modeset Helpers
407=========================
408
409.. kernel-doc:: drivers/gpu/drm/drm_modeset_helper.c
410   :doc: aux kms helpers
411
412.. kernel-doc:: drivers/gpu/drm/drm_modeset_helper.c
413   :export:
414
415OF/DT Helpers
416=============
417
418.. kernel-doc:: drivers/gpu/drm/drm_of.c
419   :doc: overview
420
421.. kernel-doc:: drivers/gpu/drm/drm_of.c
422   :export:
423
424Legacy Plane Helper Reference
425=============================
426
427.. kernel-doc:: drivers/gpu/drm/drm_plane_helper.c
428   :doc: overview
429
430.. kernel-doc:: drivers/gpu/drm/drm_plane_helper.c
431   :export:
432
433Legacy CRTC/Modeset Helper Functions Reference
434==============================================
435
436.. kernel-doc:: drivers/gpu/drm/drm_crtc_helper.c
437   :doc: overview
438
439.. kernel-doc:: drivers/gpu/drm/drm_crtc_helper.c
440   :export:
441
442Privacy-screen class
443====================
444
445.. kernel-doc:: drivers/gpu/drm/drm_privacy_screen.c
446   :doc: overview
447
448.. kernel-doc:: include/drm/drm_privacy_screen_driver.h
449   :internal:
450
451.. kernel-doc:: include/drm/drm_privacy_screen_machine.h
452   :internal:
453
454.. kernel-doc:: drivers/gpu/drm/drm_privacy_screen.c
455   :export:
456