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
83Simple KMS Helper Reference
84===========================
85
86.. kernel-doc:: drivers/gpu/drm/drm_simple_kms_helper.c
87   :doc: overview
88
89.. kernel-doc:: include/drm/drm_simple_kms_helper.h
90   :internal:
91
92.. kernel-doc:: drivers/gpu/drm/drm_simple_kms_helper.c
93   :export:
94
95fbdev Helper Functions Reference
96================================
97
98.. kernel-doc:: drivers/gpu/drm/drm_fb_helper.c
99   :doc: fbdev helpers
100
101.. kernel-doc:: include/drm/drm_fb_helper.h
102   :internal:
103
104.. kernel-doc:: drivers/gpu/drm/drm_fb_helper.c
105   :export:
106
107format Helper Functions Reference
108=================================
109
110.. kernel-doc:: drivers/gpu/drm/drm_format_helper.c
111   :export:
112
113Framebuffer CMA Helper Functions Reference
114==========================================
115
116.. kernel-doc:: drivers/gpu/drm/drm_fb_cma_helper.c
117   :doc: framebuffer cma helper functions
118
119.. kernel-doc:: drivers/gpu/drm/drm_fb_cma_helper.c
120   :export:
121
122Framebuffer GEM Helper Reference
123================================
124
125.. kernel-doc:: drivers/gpu/drm/drm_gem_framebuffer_helper.c
126   :doc: overview
127
128.. kernel-doc:: drivers/gpu/drm/drm_gem_framebuffer_helper.c
129   :export:
130
131.. _drm_bridges:
132
133Bridges
134=======
135
136Overview
137--------
138
139.. kernel-doc:: drivers/gpu/drm/drm_bridge.c
140   :doc: overview
141
142Default bridge callback sequence
143--------------------------------
144
145.. kernel-doc:: drivers/gpu/drm/drm_bridge.c
146   :doc: bridge callbacks
147
148
149Bridge Helper Reference
150-------------------------
151
152.. kernel-doc:: include/drm/drm_bridge.h
153   :internal:
154
155.. kernel-doc:: drivers/gpu/drm/drm_bridge.c
156   :export:
157
158Panel-Bridge Helper Reference
159-----------------------------
160
161.. kernel-doc:: drivers/gpu/drm/bridge/panel.c
162   :export:
163
164.. _drm_panel_helper:
165
166Panel Helper Reference
167======================
168
169.. kernel-doc:: drivers/gpu/drm/drm_panel.c
170   :doc: drm panel
171
172.. kernel-doc:: include/drm/drm_panel.h
173   :internal:
174
175.. kernel-doc:: drivers/gpu/drm/drm_panel.c
176   :export:
177
178.. kernel-doc:: drivers/gpu/drm/drm_panel_orientation_quirks.c
179   :export:
180
181Panel Self Refresh Helper Reference
182===================================
183
184.. kernel-doc:: drivers/gpu/drm/drm_self_refresh_helper.c
185   :doc: overview
186
187.. kernel-doc:: drivers/gpu/drm/drm_self_refresh_helper.c
188   :export:
189
190HDCP Helper Functions Reference
191===============================
192
193.. kernel-doc:: drivers/gpu/drm/drm_hdcp.c
194   :export:
195
196Display Port Helper Functions Reference
197=======================================
198
199.. kernel-doc:: drivers/gpu/drm/drm_dp_helper.c
200   :doc: dp helpers
201
202.. kernel-doc:: include/drm/drm_dp_helper.h
203   :internal:
204
205.. kernel-doc:: drivers/gpu/drm/drm_dp_helper.c
206   :export:
207
208Display Port CEC Helper Functions Reference
209===========================================
210
211.. kernel-doc:: drivers/gpu/drm/drm_dp_cec.c
212   :doc: dp cec helpers
213
214.. kernel-doc:: drivers/gpu/drm/drm_dp_cec.c
215   :export:
216
217Display Port Dual Mode Adaptor Helper Functions Reference
218=========================================================
219
220.. kernel-doc:: drivers/gpu/drm/drm_dp_dual_mode_helper.c
221   :doc: dp dual mode helpers
222
223.. kernel-doc:: include/drm/drm_dp_dual_mode_helper.h
224   :internal:
225
226.. kernel-doc:: drivers/gpu/drm/drm_dp_dual_mode_helper.c
227   :export:
228
229Display Port MST Helpers
230========================
231
232Overview
233--------
234
235.. kernel-doc:: drivers/gpu/drm/drm_dp_mst_topology.c
236   :doc: dp mst helper
237
238.. kernel-doc:: drivers/gpu/drm/drm_dp_mst_topology.c
239   :doc: Branch device and port refcounting
240
241Functions Reference
242-------------------
243
244.. kernel-doc:: include/drm/drm_dp_mst_helper.h
245   :internal:
246
247.. kernel-doc:: drivers/gpu/drm/drm_dp_mst_topology.c
248   :export:
249
250Topology Lifetime Internals
251---------------------------
252
253These functions aren't exported to drivers, but are documented here to help make
254the MST topology helpers easier to understand
255
256.. kernel-doc:: drivers/gpu/drm/drm_dp_mst_topology.c
257   :functions: drm_dp_mst_topology_try_get_mstb drm_dp_mst_topology_get_mstb
258               drm_dp_mst_topology_put_mstb
259               drm_dp_mst_topology_try_get_port drm_dp_mst_topology_get_port
260               drm_dp_mst_topology_put_port
261               drm_dp_mst_get_mstb_malloc drm_dp_mst_put_mstb_malloc
262
263MIPI DBI Helper Functions Reference
264===================================
265
266.. kernel-doc:: drivers/gpu/drm/drm_mipi_dbi.c
267   :doc: overview
268
269.. kernel-doc:: include/drm/drm_mipi_dbi.h
270   :internal:
271
272.. kernel-doc:: drivers/gpu/drm/drm_mipi_dbi.c
273   :export:
274
275MIPI DSI Helper Functions Reference
276===================================
277
278.. kernel-doc:: drivers/gpu/drm/drm_mipi_dsi.c
279   :doc: dsi helpers
280
281.. kernel-doc:: include/drm/drm_mipi_dsi.h
282   :internal:
283
284.. kernel-doc:: drivers/gpu/drm/drm_mipi_dsi.c
285   :export:
286
287Display Stream Compression Helper Functions Reference
288=====================================================
289
290.. kernel-doc:: drivers/gpu/drm/drm_dsc.c
291   :doc: dsc helpers
292
293.. kernel-doc:: include/drm/drm_dsc.h
294   :internal:
295
296.. kernel-doc:: drivers/gpu/drm/drm_dsc.c
297   :export:
298
299Output Probing Helper Functions Reference
300=========================================
301
302.. kernel-doc:: drivers/gpu/drm/drm_probe_helper.c
303   :doc: output probing helper overview
304
305.. kernel-doc:: drivers/gpu/drm/drm_probe_helper.c
306   :export:
307
308EDID Helper Functions Reference
309===============================
310
311.. kernel-doc:: include/drm/drm_edid.h
312   :internal:
313
314.. kernel-doc:: drivers/gpu/drm/drm_edid.c
315   :export:
316
317SCDC Helper Functions Reference
318===============================
319
320.. kernel-doc:: drivers/gpu/drm/drm_scdc_helper.c
321   :doc: scdc helpers
322
323.. kernel-doc:: include/drm/drm_scdc_helper.h
324   :internal:
325
326.. kernel-doc:: drivers/gpu/drm/drm_scdc_helper.c
327   :export:
328
329HDMI Infoframes Helper Reference
330================================
331
332Strictly speaking this is not a DRM helper library but generally useable
333by any driver interfacing with HDMI outputs like v4l or alsa drivers.
334But it nicely fits into the overall topic of mode setting helper
335libraries and hence is also included here.
336
337.. kernel-doc:: include/linux/hdmi.h
338   :internal:
339
340.. kernel-doc:: drivers/video/hdmi.c
341   :export:
342
343Rectangle Utilities Reference
344=============================
345
346.. kernel-doc:: include/drm/drm_rect.h
347   :doc: rect utils
348
349.. kernel-doc:: include/drm/drm_rect.h
350   :internal:
351
352.. kernel-doc:: drivers/gpu/drm/drm_rect.c
353   :export:
354
355Flip-work Helper Reference
356==========================
357
358.. kernel-doc:: include/drm/drm_flip_work.h
359   :doc: flip utils
360
361.. kernel-doc:: include/drm/drm_flip_work.h
362   :internal:
363
364.. kernel-doc:: drivers/gpu/drm/drm_flip_work.c
365   :export:
366
367Auxiliary Modeset Helpers
368=========================
369
370.. kernel-doc:: drivers/gpu/drm/drm_modeset_helper.c
371   :doc: aux kms helpers
372
373.. kernel-doc:: drivers/gpu/drm/drm_modeset_helper.c
374   :export:
375
376OF/DT Helpers
377=============
378
379.. kernel-doc:: drivers/gpu/drm/drm_of.c
380   :doc: overview
381
382.. kernel-doc:: drivers/gpu/drm/drm_of.c
383   :export:
384
385Legacy Plane Helper Reference
386=============================
387
388.. kernel-doc:: drivers/gpu/drm/drm_plane_helper.c
389   :doc: overview
390
391.. kernel-doc:: drivers/gpu/drm/drm_plane_helper.c
392   :export:
393
394Legacy CRTC/Modeset Helper Functions Reference
395==============================================
396
397.. kernel-doc:: drivers/gpu/drm/drm_crtc_helper.c
398   :doc: overview
399
400.. kernel-doc:: drivers/gpu/drm/drm_crtc_helper.c
401   :export:
402
403SHMEM GEM Helper Reference
404==========================
405
406.. kernel-doc:: drivers/gpu/drm/drm_gem_shmem_helper.c
407   :doc: overview
408
409.. kernel-doc:: include/drm/drm_gem_shmem_helper.h
410   :internal:
411
412.. kernel-doc:: drivers/gpu/drm/drm_gem_shmem_helper.c
413   :export:
414