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