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