Commit | Line | Data |
---|---|---|
092d01da DV |
1 | /* |
2 | * Copyright © 2006 Keith Packard | |
3 | * Copyright © 2007-2008 Dave Airlie | |
4 | * Copyright © 2007-2008 Intel Corporation | |
5 | * Jesse Barnes <jesse.barnes@intel.com> | |
6 | * Copyright © 2011-2013 Intel Corporation | |
7 | * Copyright © 2015 Intel Corporation | |
8 | * Daniel Vetter <daniel.vetter@ffwll.ch> | |
9 | * | |
10 | * Permission is hereby granted, free of charge, to any person obtaining a | |
11 | * copy of this software and associated documentation files (the "Software"), | |
12 | * to deal in the Software without restriction, including without limitation | |
13 | * the rights to use, copy, modify, merge, publish, distribute, sublicense, | |
14 | * and/or sell copies of the Software, and to permit persons to whom the | |
15 | * Software is furnished to do so, subject to the following conditions: | |
16 | * | |
17 | * The above copyright notice and this permission notice shall be included in | |
18 | * all copies or substantial portions of the Software. | |
19 | * | |
20 | * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR | |
21 | * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, | |
22 | * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL | |
23 | * THE COPYRIGHT HOLDER(S) OR AUTHOR(S) BE LIABLE FOR ANY CLAIM, DAMAGES OR | |
24 | * OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, | |
25 | * ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR | |
26 | * OTHER DEALINGS IN THE SOFTWARE. | |
27 | */ | |
28 | ||
29 | #ifndef __DRM_MODESET_HELPER_VTABLES_H__ | |
30 | #define __DRM_MODESET_HELPER_VTABLES_H__ | |
31 | ||
32 | #include <drm/drm_crtc.h> | |
33 | ||
34 | /** | |
35 | * DOC: overview | |
36 | * | |
37 | * The DRM mode setting helper functions are common code for drivers to use if | |
38 | * they wish. Drivers are not forced to use this code in their | |
39 | * implementations but it would be useful if the code they do use at least | |
40 | * provides a consistent interface and operation to userspace. Therefore it is | |
41 | * highly recommended to use the provided helpers as much as possible. | |
42 | * | |
43 | * Because there is only one pointer per modeset object to hold a vfunc table | |
44 | * for helper libraries they are by necessity shared among the different | |
45 | * helpers. | |
46 | * | |
47 | * To make this clear all the helper vtables are pulled together in this location here. | |
48 | */ | |
49 | ||
50 | enum mode_set_atomic; | |
51 | ||
52 | /** | |
53 | * struct drm_crtc_helper_funcs - helper operations for CRTCs | |
092d01da | 54 | * |
36b66080 DV |
55 | * These hooks are used by the legacy CRTC helpers, the transitional plane |
56 | * helpers and the new atomic modesetting helpers. | |
092d01da DV |
57 | */ |
58 | struct drm_crtc_helper_funcs { | |
36b66080 DV |
59 | /** |
60 | * @dpms: | |
61 | * | |
62 | * Callback to control power levels on the CRTC. If the mode passed in | |
63 | * is unsupported, the provider must use the next lowest power level. | |
64 | * This is used by the legacy CRTC helpers to implement DPMS | |
65 | * functionality in drm_helper_connector_dpms(). | |
66 | * | |
67 | * This callback is also used to disable a CRTC by calling it with | |
68 | * DRM_MODE_DPMS_OFF if the @disable hook isn't used. | |
69 | * | |
70 | * This callback is used by the legacy CRTC helpers. Atomic helpers | |
71 | * also support using this hook for enabling and disabling a CRTC to | |
72 | * facilitate transitions to atomic, but it is deprecated. Instead | |
73 | * @enable and @disable should be used. | |
092d01da DV |
74 | */ |
75 | void (*dpms)(struct drm_crtc *crtc, int mode); | |
36b66080 DV |
76 | |
77 | /** | |
78 | * @prepare: | |
79 | * | |
80 | * This callback should prepare the CRTC for a subsequent modeset, which | |
81 | * in practice means the driver should disable the CRTC if it is | |
82 | * running. Most drivers ended up implementing this by calling their | |
83 | * @dpms hook with DRM_MODE_DPMS_OFF. | |
84 | * | |
85 | * This callback is used by the legacy CRTC helpers. Atomic helpers | |
86 | * also support using this hook for disabling a CRTC to facilitate | |
87 | * transitions to atomic, but it is deprecated. Instead @disable should | |
88 | * be used. | |
89 | */ | |
092d01da | 90 | void (*prepare)(struct drm_crtc *crtc); |
36b66080 DV |
91 | |
92 | /** | |
93 | * @commit: | |
94 | * | |
95 | * This callback should commit the new mode on the CRTC after a modeset, | |
96 | * which in practice means the driver should enable the CRTC. Most | |
97 | * drivers ended up implementing this by calling their @dpms hook with | |
98 | * DRM_MODE_DPMS_ON. | |
99 | * | |
100 | * This callback is used by the legacy CRTC helpers. Atomic helpers | |
101 | * also support using this hook for enabling a CRTC to facilitate | |
102 | * transitions to atomic, but it is deprecated. Instead @enable should | |
103 | * be used. | |
104 | */ | |
092d01da DV |
105 | void (*commit)(struct drm_crtc *crtc); |
106 | ||
36b66080 DV |
107 | /** |
108 | * @mode_fixup: | |
109 | * | |
110 | * This callback is used to validate a mode. The parameter mode is the | |
111 | * display mode that userspace requested, adjusted_mode is the mode the | |
112 | * encoders need to be fed with. Note that this is the inverse semantics | |
113 | * of the meaning for the &drm_encoder and &drm_bridge | |
114 | * ->mode_fixup() functions. If the CRTC cannot support the requested | |
115 | * conversion from mode to adjusted_mode it should reject the modeset. | |
116 | * | |
117 | * This function is used by both legacy CRTC helpers and atomic helpers. | |
118 | * With atomic helpers it is optional. | |
119 | * | |
120 | * NOTE: | |
121 | * | |
122 | * This function is called in the check phase of atomic modesets, which | |
123 | * can be aborted for any reason (including on userspace's request to | |
124 | * just check whether a configuration would be possible). Atomic drivers | |
125 | * MUST NOT touch any persistent state (hardware or software) or data | |
126 | * structures except the passed in adjusted_mode parameter. | |
127 | * | |
128 | * This is in contrast to the legacy CRTC helpers where this was | |
129 | * allowed. | |
130 | * | |
131 | * Atomic drivers which need to inspect and adjust more state should | |
132 | * instead use the @atomic_check callback. | |
133 | * | |
df7d678b DV |
134 | * Also beware that neither core nor helpers filter modes before |
135 | * passing them to the driver: While the list of modes that is | |
136 | * advertised to userspace is filtered using the connector's | |
137 | * ->mode_valid() callback, neither the core nor the helpers do any | |
138 | * filtering on modes passed in from userspace when setting a mode. It | |
139 | * is therefore possible for userspace to pass in a mode that was | |
140 | * previously filtered out using ->mode_valid() or add a custom mode | |
141 | * that wasn't probed from EDID or similar to begin with. Even though | |
142 | * this is an advanced feature and rarely used nowadays, some users rely | |
143 | * on being able to specify modes manually so drivers must be prepared | |
144 | * to deal with it. Specifically this means that all drivers need not | |
145 | * only validate modes in ->mode_valid() but also in ->mode_fixup() to | |
146 | * make sure invalid modes passed in from userspace are rejected. | |
147 | * | |
36b66080 DV |
148 | * RETURNS: |
149 | * | |
150 | * True if an acceptable configuration is possible, false if the modeset | |
151 | * operation should be rejected. | |
152 | */ | |
092d01da DV |
153 | bool (*mode_fixup)(struct drm_crtc *crtc, |
154 | const struct drm_display_mode *mode, | |
155 | struct drm_display_mode *adjusted_mode); | |
36b66080 DV |
156 | |
157 | /** | |
158 | * @mode_set: | |
159 | * | |
160 | * This callback is used by the legacy CRTC helpers to set a new mode, | |
161 | * position and framebuffer. Since it ties the primary plane to every | |
162 | * mode change it is incompatible with universal plane support. And | |
163 | * since it can't update other planes it's incompatible with atomic | |
164 | * modeset support. | |
165 | * | |
166 | * This callback is only used by CRTC helpers and deprecated. | |
167 | * | |
168 | * RETURNS: | |
169 | * | |
170 | * 0 on success or a negative error code on failure. | |
171 | */ | |
092d01da DV |
172 | int (*mode_set)(struct drm_crtc *crtc, struct drm_display_mode *mode, |
173 | struct drm_display_mode *adjusted_mode, int x, int y, | |
174 | struct drm_framebuffer *old_fb); | |
36b66080 DV |
175 | |
176 | /** | |
177 | * @mode_set_nofb: | |
178 | * | |
179 | * This callback is used to update the display mode of a CRTC without | |
180 | * changing anything of the primary plane configuration. This fits the | |
181 | * requirement of atomic and hence is used by the atomic helpers. It is | |
182 | * also used by the transitional plane helpers to implement a | |
183 | * @mode_set hook in drm_helper_crtc_mode_set(). | |
184 | * | |
185 | * Note that the display pipe is completely off when this function is | |
186 | * called. Atomic drivers which need hardware to be running before they | |
187 | * program the new display mode (e.g. because they implement runtime PM) | |
188 | * should not use this hook. This is because the helper library calls | |
189 | * this hook only once per mode change and not every time the display | |
190 | * pipeline is suspended using either DPMS or the new "ACTIVE" property. | |
191 | * Which means register values set in this callback might get reset when | |
192 | * the CRTC is suspended, but not restored. Such drivers should instead | |
193 | * move all their CRTC setup into the @enable callback. | |
194 | * | |
195 | * This callback is optional. | |
196 | */ | |
092d01da DV |
197 | void (*mode_set_nofb)(struct drm_crtc *crtc); |
198 | ||
36b66080 DV |
199 | /** |
200 | * @mode_set_base: | |
201 | * | |
202 | * This callback is used by the legacy CRTC helpers to set a new | |
203 | * framebuffer and scanout position. It is optional and used as an | |
204 | * optimized fast-path instead of a full mode set operation with all the | |
df7d678b DV |
205 | * resulting flickering. If it is not present |
206 | * drm_crtc_helper_set_config() will fall back to a full modeset, using | |
207 | * the ->mode_set() callback. Since it can't update other planes it's | |
36b66080 DV |
208 | * incompatible with atomic modeset support. |
209 | * | |
210 | * This callback is only used by the CRTC helpers and deprecated. | |
211 | * | |
212 | * RETURNS: | |
213 | * | |
214 | * 0 on success or a negative error code on failure. | |
215 | */ | |
092d01da DV |
216 | int (*mode_set_base)(struct drm_crtc *crtc, int x, int y, |
217 | struct drm_framebuffer *old_fb); | |
36b66080 DV |
218 | |
219 | /** | |
220 | * @mode_set_base_atomic: | |
221 | * | |
222 | * This callback is used by the fbdev helpers to set a new framebuffer | |
223 | * and scanout without sleeping, i.e. from an atomic calling context. It | |
224 | * is only used to implement kgdb support. | |
225 | * | |
226 | * This callback is optional and only needed for kgdb support in the fbdev | |
227 | * helpers. | |
228 | * | |
229 | * RETURNS: | |
230 | * | |
231 | * 0 on success or a negative error code on failure. | |
232 | */ | |
092d01da DV |
233 | int (*mode_set_base_atomic)(struct drm_crtc *crtc, |
234 | struct drm_framebuffer *fb, int x, int y, | |
235 | enum mode_set_atomic); | |
236 | ||
36b66080 DV |
237 | /** |
238 | * @load_lut: | |
239 | * | |
240 | * Load a LUT prepared with the @gamma_set functions from | |
241 | * &drm_fb_helper_funcs. | |
242 | * | |
243 | * This callback is optional and is only used by the fbdev emulation | |
244 | * helpers. | |
245 | * | |
246 | * FIXME: | |
247 | * | |
248 | * This callback is functionally redundant with the core gamma table | |
249 | * support and simply exists because the fbdev hasn't yet been | |
250 | * refactored to use the core gamma table interfaces. | |
251 | */ | |
092d01da DV |
252 | void (*load_lut)(struct drm_crtc *crtc); |
253 | ||
36b66080 DV |
254 | /** |
255 | * @disable: | |
256 | * | |
257 | * This callback should be used to disable the CRTC. With the atomic | |
258 | * drivers it is called after all encoders connected to this CRTC have | |
259 | * been shut off already using their own ->disable hook. If that | |
260 | * sequence is too simple drivers can just add their own hooks and call | |
261 | * it from this CRTC callback here by looping over all encoders | |
262 | * connected to it using for_each_encoder_on_crtc(). | |
263 | * | |
264 | * This hook is used both by legacy CRTC helpers and atomic helpers. | |
265 | * Atomic drivers don't need to implement it if there's no need to | |
266 | * disable anything at the CRTC level. To ensure that runtime PM | |
267 | * handling (using either DPMS or the new "ACTIVE" property) works | |
268 | * @disable must be the inverse of @enable for atomic drivers. | |
269 | * | |
270 | * NOTE: | |
271 | * | |
272 | * With legacy CRTC helpers there's a big semantic difference between | |
273 | * @disable and other hooks (like @prepare or @dpms) used to shut down a | |
274 | * CRTC: @disable is only called when also logically disabling the | |
275 | * display pipeline and needs to release any resources acquired in | |
276 | * @mode_set (like shared PLLs, or again release pinned framebuffers). | |
277 | * | |
278 | * Therefore @disable must be the inverse of @mode_set plus @commit for | |
279 | * drivers still using legacy CRTC helpers, which is different from the | |
280 | * rules under atomic. | |
281 | */ | |
092d01da | 282 | void (*disable)(struct drm_crtc *crtc); |
36b66080 DV |
283 | |
284 | /** | |
285 | * @enable: | |
286 | * | |
287 | * This callback should be used to enable the CRTC. With the atomic | |
288 | * drivers it is called before all encoders connected to this CRTC are | |
289 | * enabled through the encoder's own ->enable hook. If that sequence is | |
290 | * too simple drivers can just add their own hooks and call it from this | |
291 | * CRTC callback here by looping over all encoders connected to it using | |
292 | * for_each_encoder_on_crtc(). | |
293 | * | |
294 | * This hook is used only by atomic helpers, for symmetry with @disable. | |
295 | * Atomic drivers don't need to implement it if there's no need to | |
296 | * enable anything at the CRTC level. To ensure that runtime PM handling | |
297 | * (using either DPMS or the new "ACTIVE" property) works | |
298 | * @enable must be the inverse of @disable for atomic drivers. | |
299 | */ | |
092d01da DV |
300 | void (*enable)(struct drm_crtc *crtc); |
301 | ||
11a0ba97 DV |
302 | /** |
303 | * @atomic_check: | |
304 | * | |
305 | * Drivers should check plane-update related CRTC constraints in this | |
306 | * hook. They can also check mode related limitations but need to be | |
307 | * aware of the calling order, since this hook is used by | |
308 | * drm_atomic_helper_check_planes() whereas the preparations needed to | |
309 | * check output routing and the display mode is done in | |
310 | * drm_atomic_helper_check_modeset(). Therefore drivers that want to | |
311 | * check output routing and display mode constraints in this callback | |
312 | * must ensure that drm_atomic_helper_check_modeset() has been called | |
313 | * beforehand. This is calling order used by the default helper | |
314 | * implementation in drm_atomic_helper_check(). | |
315 | * | |
316 | * When using drm_atomic_helper_check_planes() CRTCs' ->atomic_check() | |
317 | * hooks are called after the ones for planes, which allows drivers to | |
318 | * assign shared resources requested by planes in the CRTC callback | |
319 | * here. For more complicated dependencies the driver can call the provided | |
320 | * check helpers multiple times until the computed state has a final | |
321 | * configuration and everything has been checked. | |
322 | * | |
323 | * This function is also allowed to inspect any other object's state and | |
324 | * can add more state objects to the atomic commit if needed. Care must | |
325 | * be taken though to ensure that state check&compute functions for | |
326 | * these added states are all called, and derived state in other objects | |
327 | * all updated. Again the recommendation is to just call check helpers | |
328 | * until a maximal configuration is reached. | |
329 | * | |
330 | * This callback is used by the atomic modeset helpers and by the | |
331 | * transitional plane helpers, but it is optional. | |
332 | * | |
333 | * NOTE: | |
334 | * | |
335 | * This function is called in the check phase of an atomic update. The | |
336 | * driver is not allowed to change anything outside of the free-standing | |
337 | * state objects passed-in or assembled in the overall &drm_atomic_state | |
338 | * update tracking structure. | |
339 | * | |
340 | * RETURNS: | |
341 | * | |
342 | * 0 on success, -EINVAL if the state or the transition can't be | |
343 | * supported, -ENOMEM on memory allocation failure and -EDEADLK if an | |
344 | * attempt to obtain another state object ran into a &drm_modeset_lock | |
345 | * deadlock. | |
346 | */ | |
092d01da DV |
347 | int (*atomic_check)(struct drm_crtc *crtc, |
348 | struct drm_crtc_state *state); | |
11a0ba97 DV |
349 | |
350 | /** | |
351 | * @atomic_begin: | |
352 | * | |
353 | * Drivers should prepare for an atomic update of multiple planes on | |
354 | * a CRTC in this hook. Depending upon hardware this might be vblank | |
355 | * evasion, blocking updates by setting bits or doing preparatory work | |
356 | * for e.g. manual update display. | |
357 | * | |
358 | * This hook is called before any plane commit functions are called. | |
359 | * | |
360 | * Note that the power state of the display pipe when this function is | |
361 | * called depends upon the exact helpers and calling sequence the driver | |
362 | * has picked. See drm_atomic_commit_planes() for a discussion of the | |
363 | * tradeoffs and variants of plane commit helpers. | |
364 | * | |
365 | * This callback is used by the atomic modeset helpers and by the | |
366 | * transitional plane helpers, but it is optional. | |
367 | */ | |
092d01da DV |
368 | void (*atomic_begin)(struct drm_crtc *crtc, |
369 | struct drm_crtc_state *old_crtc_state); | |
11a0ba97 DV |
370 | /** |
371 | * @atomic_flush: | |
372 | * | |
373 | * Drivers should finalize an atomic update of multiple planes on | |
374 | * a CRTC in this hook. Depending upon hardware this might include | |
375 | * checking that vblank evasion was successful, unblocking updates by | |
376 | * setting bits or setting the GO bit to flush out all updates. | |
377 | * | |
378 | * Simple hardware or hardware with special requirements can commit and | |
379 | * flush out all updates for all planes from this hook and forgo all the | |
380 | * other commit hooks for plane updates. | |
381 | * | |
382 | * This hook is called after any plane commit functions are called. | |
383 | * | |
384 | * Note that the power state of the display pipe when this function is | |
385 | * called depends upon the exact helpers and calling sequence the driver | |
386 | * has picked. See drm_atomic_commit_planes() for a discussion of the | |
387 | * tradeoffs and variants of plane commit helpers. | |
388 | * | |
389 | * This callback is used by the atomic modeset helpers and by the | |
390 | * transitional plane helpers, but it is optional. | |
391 | */ | |
092d01da DV |
392 | void (*atomic_flush)(struct drm_crtc *crtc, |
393 | struct drm_crtc_state *old_crtc_state); | |
394 | }; | |
395 | ||
396 | /** | |
397 | * drm_crtc_helper_add - sets the helper vtable for a crtc | |
398 | * @crtc: DRM CRTC | |
399 | * @funcs: helper vtable to set for @crtc | |
400 | */ | |
401 | static inline void drm_crtc_helper_add(struct drm_crtc *crtc, | |
402 | const struct drm_crtc_helper_funcs *funcs) | |
403 | { | |
404 | crtc->helper_private = funcs; | |
405 | } | |
406 | ||
407 | /** | |
408 | * struct drm_encoder_helper_funcs - helper operations for encoders | |
092d01da | 409 | * |
36b66080 DV |
410 | * These hooks are used by the legacy CRTC helpers, the transitional plane |
411 | * helpers and the new atomic modesetting helpers. | |
092d01da DV |
412 | */ |
413 | struct drm_encoder_helper_funcs { | |
36b66080 DV |
414 | /** |
415 | * @dpms: | |
416 | * | |
417 | * Callback to control power levels on the encoder. If the mode passed in | |
418 | * is unsupported, the provider must use the next lowest power level. | |
419 | * This is used by the legacy encoder helpers to implement DPMS | |
420 | * functionality in drm_helper_connector_dpms(). | |
421 | * | |
422 | * This callback is also used to disable an encoder by calling it with | |
423 | * DRM_MODE_DPMS_OFF if the @disable hook isn't used. | |
424 | * | |
425 | * This callback is used by the legacy CRTC helpers. Atomic helpers | |
426 | * also support using this hook for enabling and disabling an encoder to | |
427 | * facilitate transitions to atomic, but it is deprecated. Instead | |
428 | * @enable and @disable should be used. | |
429 | */ | |
092d01da | 430 | void (*dpms)(struct drm_encoder *encoder, int mode); |
092d01da | 431 | |
36b66080 DV |
432 | /** |
433 | * @mode_fixup: | |
434 | * | |
435 | * This callback is used to validate and adjust a mode. The parameter | |
436 | * mode is the display mode that should be fed to the next element in | |
437 | * the display chain, either the final &drm_connector or a &drm_bridge. | |
438 | * The parameter adjusted_mode is the input mode the encoder requires. It | |
439 | * can be modified by this callback and does not need to match mode. | |
440 | * | |
441 | * This function is used by both legacy CRTC helpers and atomic helpers. | |
442 | * With atomic helpers it is optional. | |
443 | * | |
444 | * NOTE: | |
445 | * | |
446 | * This function is called in the check phase of atomic modesets, which | |
447 | * can be aborted for any reason (including on userspace's request to | |
448 | * just check whether a configuration would be possible). Atomic drivers | |
449 | * MUST NOT touch any persistent state (hardware or software) or data | |
450 | * structures except the passed in adjusted_mode parameter. | |
451 | * | |
452 | * This is in contrast to the legacy CRTC helpers where this was | |
453 | * allowed. | |
454 | * | |
455 | * Atomic drivers which need to inspect and adjust more state should | |
456 | * instead use the @atomic_check callback. | |
457 | * | |
df7d678b DV |
458 | * Also beware that neither core nor helpers filter modes before |
459 | * passing them to the driver: While the list of modes that is | |
460 | * advertised to userspace is filtered using the connector's | |
461 | * ->mode_valid() callback, neither the core nor the helpers do any | |
462 | * filtering on modes passed in from userspace when setting a mode. It | |
463 | * is therefore possible for userspace to pass in a mode that was | |
464 | * previously filtered out using ->mode_valid() or add a custom mode | |
465 | * that wasn't probed from EDID or similar to begin with. Even though | |
466 | * this is an advanced feature and rarely used nowadays, some users rely | |
467 | * on being able to specify modes manually so drivers must be prepared | |
468 | * to deal with it. Specifically this means that all drivers need not | |
469 | * only validate modes in ->mode_valid() but also in ->mode_fixup() to | |
470 | * make sure invalid modes passed in from userspace are rejected. | |
471 | * | |
36b66080 DV |
472 | * RETURNS: |
473 | * | |
474 | * True if an acceptable configuration is possible, false if the modeset | |
475 | * operation should be rejected. | |
476 | */ | |
092d01da DV |
477 | bool (*mode_fixup)(struct drm_encoder *encoder, |
478 | const struct drm_display_mode *mode, | |
479 | struct drm_display_mode *adjusted_mode); | |
36b66080 DV |
480 | |
481 | /** | |
482 | * @prepare: | |
483 | * | |
484 | * This callback should prepare the encoder for a subsequent modeset, | |
485 | * which in practice means the driver should disable the encoder if it | |
486 | * is running. Most drivers ended up implementing this by calling their | |
487 | * @dpms hook with DRM_MODE_DPMS_OFF. | |
488 | * | |
489 | * This callback is used by the legacy CRTC helpers. Atomic helpers | |
490 | * also support using this hook for disabling an encoder to facilitate | |
491 | * transitions to atomic, but it is deprecated. Instead @disable should | |
492 | * be used. | |
493 | */ | |
092d01da | 494 | void (*prepare)(struct drm_encoder *encoder); |
36b66080 DV |
495 | |
496 | /** | |
497 | * @commit: | |
498 | * | |
499 | * This callback should commit the new mode on the encoder after a modeset, | |
500 | * which in practice means the driver should enable the encoder. Most | |
501 | * drivers ended up implementing this by calling their @dpms hook with | |
502 | * DRM_MODE_DPMS_ON. | |
503 | * | |
504 | * This callback is used by the legacy CRTC helpers. Atomic helpers | |
505 | * also support using this hook for enabling an encoder to facilitate | |
506 | * transitions to atomic, but it is deprecated. Instead @enable should | |
507 | * be used. | |
508 | */ | |
092d01da | 509 | void (*commit)(struct drm_encoder *encoder); |
36b66080 DV |
510 | |
511 | /** | |
512 | * @mode_set: | |
513 | * | |
514 | * This callback is used to update the display mode of an encoder. | |
515 | * | |
516 | * Note that the display pipe is completely off when this function is | |
517 | * called. Drivers which need hardware to be running before they program | |
518 | * the new display mode (because they implement runtime PM) should not | |
519 | * use this hook, because the helper library calls it only once and not | |
520 | * every time the display pipeline is suspend using either DPMS or the | |
521 | * new "ACTIVE" property. Such drivers should instead move all their | |
522 | * encoder setup into the ->enable() callback. | |
523 | * | |
524 | * This callback is used both by the legacy CRTC helpers and the atomic | |
525 | * modeset helpers. It is optional in the atomic helpers. | |
526 | */ | |
092d01da DV |
527 | void (*mode_set)(struct drm_encoder *encoder, |
528 | struct drm_display_mode *mode, | |
529 | struct drm_display_mode *adjusted_mode); | |
36b66080 DV |
530 | |
531 | /** | |
532 | * @get_crtc: | |
533 | * | |
534 | * This callback is used by the legacy CRTC helpers to work around | |
535 | * deficiencies in its own book-keeping. | |
536 | * | |
537 | * Do not use, use atomic helpers instead, which get the book keeping | |
538 | * right. | |
539 | * | |
540 | * FIXME: | |
541 | * | |
542 | * Currently only nouveau is using this, and as soon as nouveau is | |
543 | * atomic we can ditch this hook. | |
544 | */ | |
092d01da | 545 | struct drm_crtc *(*get_crtc)(struct drm_encoder *encoder); |
36b66080 DV |
546 | |
547 | /** | |
548 | * @detect: | |
549 | * | |
550 | * This callback can be used by drivers who want to do detection on the | |
551 | * encoder object instead of in connector functions. | |
552 | * | |
553 | * It is not used by any helper and therefore has purely driver-specific | |
554 | * semantics. New drivers shouldn't use this and instead just implement | |
555 | * their own private callbacks. | |
556 | * | |
557 | * FIXME: | |
558 | * | |
559 | * This should just be converted into a pile of driver vfuncs. | |
560 | * Currently radeon, amdgpu and nouveau are using it. | |
561 | */ | |
092d01da DV |
562 | enum drm_connector_status (*detect)(struct drm_encoder *encoder, |
563 | struct drm_connector *connector); | |
36b66080 DV |
564 | |
565 | /** | |
566 | * @disable: | |
567 | * | |
568 | * This callback should be used to disable the encoder. With the atomic | |
569 | * drivers it is called before this encoder's CRTC has been shut off | |
570 | * using the CRTC's own ->disable hook. If that sequence is too simple | |
571 | * drivers can just add their own driver private encoder hooks and call | |
572 | * them from CRTC's callback by looping over all encoders connected to | |
573 | * it using for_each_encoder_on_crtc(). | |
574 | * | |
575 | * This hook is used both by legacy CRTC helpers and atomic helpers. | |
576 | * Atomic drivers don't need to implement it if there's no need to | |
577 | * disable anything at the encoder level. To ensure that runtime PM | |
578 | * handling (using either DPMS or the new "ACTIVE" property) works | |
579 | * @disable must be the inverse of @enable for atomic drivers. | |
580 | * | |
581 | * NOTE: | |
582 | * | |
583 | * With legacy CRTC helpers there's a big semantic difference between | |
584 | * @disable and other hooks (like @prepare or @dpms) used to shut down a | |
585 | * encoder: @disable is only called when also logically disabling the | |
586 | * display pipeline and needs to release any resources acquired in | |
587 | * @mode_set (like shared PLLs, or again release pinned framebuffers). | |
588 | * | |
589 | * Therefore @disable must be the inverse of @mode_set plus @commit for | |
590 | * drivers still using legacy CRTC helpers, which is different from the | |
591 | * rules under atomic. | |
592 | */ | |
092d01da DV |
593 | void (*disable)(struct drm_encoder *encoder); |
594 | ||
36b66080 DV |
595 | /** |
596 | * @enable: | |
597 | * | |
598 | * This callback should be used to enable the encoder. With the atomic | |
599 | * drivers it is called after this encoder's CRTC has been enabled using | |
600 | * the CRTC's own ->enable hook. If that sequence is too simple drivers | |
601 | * can just add their own driver private encoder hooks and call them | |
602 | * from CRTC's callback by looping over all encoders connected to it | |
603 | * using for_each_encoder_on_crtc(). | |
604 | * | |
605 | * This hook is used only by atomic helpers, for symmetry with @disable. | |
606 | * Atomic drivers don't need to implement it if there's no need to | |
607 | * enable anything at the encoder level. To ensure that runtime PM handling | |
608 | * (using either DPMS or the new "ACTIVE" property) works | |
609 | * @enable must be the inverse of @disable for atomic drivers. | |
610 | */ | |
092d01da DV |
611 | void (*enable)(struct drm_encoder *encoder); |
612 | ||
36b66080 DV |
613 | /** |
614 | * @atomic_check: | |
615 | * | |
616 | * This callback is used to validate encoder state for atomic drivers. | |
617 | * Since the encoder is the object connecting the CRTC and connector it | |
618 | * gets passed both states, to be able to validate interactions and | |
619 | * update the CRTC to match what the encoder needs for the requested | |
620 | * connector. | |
621 | * | |
622 | * This function is used by the atomic helpers, but it is optional. | |
623 | * | |
624 | * NOTE: | |
625 | * | |
626 | * This function is called in the check phase of an atomic update. The | |
627 | * driver is not allowed to change anything outside of the free-standing | |
628 | * state objects passed-in or assembled in the overall &drm_atomic_state | |
629 | * update tracking structure. | |
630 | * | |
631 | * RETURNS: | |
632 | * | |
633 | * 0 on success, -EINVAL if the state or the transition can't be | |
634 | * supported, -ENOMEM on memory allocation failure and -EDEADLK if an | |
635 | * attempt to obtain another state object ran into a &drm_modeset_lock | |
636 | * deadlock. | |
637 | */ | |
092d01da DV |
638 | int (*atomic_check)(struct drm_encoder *encoder, |
639 | struct drm_crtc_state *crtc_state, | |
640 | struct drm_connector_state *conn_state); | |
641 | }; | |
642 | ||
643 | /** | |
36b66080 | 644 | * drm_encoder_helper_add - sets the helper vtable for an encoder |
092d01da DV |
645 | * @encoder: DRM encoder |
646 | * @funcs: helper vtable to set for @encoder | |
647 | */ | |
648 | static inline void drm_encoder_helper_add(struct drm_encoder *encoder, | |
649 | const struct drm_encoder_helper_funcs *funcs) | |
650 | { | |
651 | encoder->helper_private = funcs; | |
652 | } | |
653 | ||
654 | /** | |
655 | * struct drm_connector_helper_funcs - helper operations for connectors | |
092d01da | 656 | * |
4ee6034c DV |
657 | * These functions are used by the atomic and legacy modeset helpers and by the |
658 | * probe helpers. | |
092d01da DV |
659 | */ |
660 | struct drm_connector_helper_funcs { | |
4ee6034c DV |
661 | /** |
662 | * @get_modes: | |
663 | * | |
664 | * This function should fill in all modes currently valid for the sink | |
665 | * into the connector->probed_modes list. It should also update the | |
666 | * EDID property by calling drm_mode_connector_update_edid_property(). | |
667 | * | |
668 | * The usual way to implement this is to cache the EDID retrieved in the | |
669 | * probe callback somewhere in the driver-private connector structure. | |
670 | * In this function drivers then parse the modes in the EDID and add | |
671 | * them by calling drm_add_edid_modes(). But connectors that driver a | |
672 | * fixed panel can also manually add specific modes using | |
df7d678b DV |
673 | * drm_mode_probed_add(). Drivers which manually add modes should also |
674 | * make sure that the @display_info, @width_mm and @height_mm fields of the | |
675 | * struct #drm_connector are filled in. | |
676 | * | |
677 | * Virtual drivers that just want some standard VESA mode with a given | |
678 | * resolution can call drm_add_modes_noedid(), and mark the preferred | |
679 | * one using drm_set_preferred_mode(). | |
680 | * | |
681 | * Finally drivers that support audio probably want to update the ELD | |
682 | * data, too, using drm_edid_to_eld(). | |
4ee6034c DV |
683 | * |
684 | * This function is only called after the ->detect() hook has indicated | |
685 | * that a sink is connected and when the EDID isn't overridden through | |
686 | * sysfs or the kernel commandline. | |
687 | * | |
688 | * This callback is used by the probe helpers in e.g. | |
689 | * drm_helper_probe_single_connector_modes(). | |
690 | * | |
691 | * RETURNS: | |
692 | * | |
693 | * The number of modes added by calling drm_mode_probed_add(). | |
694 | */ | |
092d01da | 695 | int (*get_modes)(struct drm_connector *connector); |
4ee6034c DV |
696 | |
697 | /** | |
698 | * @mode_valid: | |
699 | * | |
700 | * Callback to validate a mode for a connector, irrespective of the | |
701 | * specific display configuration. | |
702 | * | |
703 | * This callback is used by the probe helpers to filter the mode list | |
704 | * (which is usually derived from the EDID data block from the sink). | |
705 | * See e.g. drm_helper_probe_single_connector_modes(). | |
706 | * | |
707 | * NOTE: | |
708 | * | |
709 | * This only filters the mode list supplied to userspace in the | |
710 | * GETCONNECOTR IOCTL. Userspace is free to create modes of its own and | |
711 | * ask the kernel to use them. It this case the atomic helpers or legacy | |
712 | * CRTC helpers will not call this function. Drivers therefore must | |
713 | * still fully validate any mode passed in in a modeset request. | |
714 | * | |
715 | * RETURNS: | |
716 | * | |
717 | * Either MODE_OK or one of the failure reasons in enum | |
718 | * &drm_mode_status. | |
719 | */ | |
092d01da DV |
720 | enum drm_mode_status (*mode_valid)(struct drm_connector *connector, |
721 | struct drm_display_mode *mode); | |
4ee6034c DV |
722 | /** |
723 | * @best_encoder: | |
724 | * | |
725 | * This function should select the best encoder for the given connector. | |
726 | * | |
727 | * This function is used by both the atomic helpers (in the | |
728 | * drm_atomic_helper_check_modeset() function) and in the legacy CRTC | |
729 | * helpers. | |
730 | * | |
731 | * NOTE: | |
732 | * | |
733 | * In atomic drivers this function is called in the check phase of an | |
734 | * atomic update. The driver is not allowed to change or inspect | |
735 | * anything outside of arguments passed-in. Atomic drivers which need to | |
736 | * inspect dynamic configuration state should instead use | |
737 | * @atomic_best_encoder. | |
738 | * | |
739 | * RETURNS: | |
740 | * | |
741 | * Encoder that should be used for the given connector and connector | |
742 | * state, or NULL if no suitable encoder exists. Note that the helpers | |
743 | * will ensure that encoders aren't used twice, drivers should not check | |
744 | * for this. | |
745 | */ | |
092d01da | 746 | struct drm_encoder *(*best_encoder)(struct drm_connector *connector); |
4ee6034c DV |
747 | |
748 | /** | |
749 | * @atomic_best_encoder: | |
750 | * | |
751 | * This is the atomic version of @best_encoder for atomic drivers which | |
752 | * need to select the best encoder depending upon the desired | |
753 | * configuration and can't select it statically. | |
754 | * | |
755 | * This function is used by drm_atomic_helper_check_modeset() and either | |
756 | * this or @best_encoder is required. | |
757 | * | |
758 | * NOTE: | |
759 | * | |
760 | * This function is called in the check phase of an atomic update. The | |
761 | * driver is not allowed to change anything outside of the free-standing | |
762 | * state objects passed-in or assembled in the overall &drm_atomic_state | |
763 | * update tracking structure. | |
764 | * | |
765 | * RETURNS: | |
766 | * | |
767 | * Encoder that should be used for the given connector and connector | |
768 | * state, or NULL if no suitable encoder exists. Note that the helpers | |
769 | * will ensure that encoders aren't used twice, drivers should not check | |
770 | * for this. | |
771 | */ | |
092d01da DV |
772 | struct drm_encoder *(*atomic_best_encoder)(struct drm_connector *connector, |
773 | struct drm_connector_state *connector_state); | |
774 | }; | |
775 | ||
776 | /** | |
777 | * drm_connector_helper_add - sets the helper vtable for a connector | |
778 | * @connector: DRM connector | |
779 | * @funcs: helper vtable to set for @connector | |
780 | */ | |
781 | static inline void drm_connector_helper_add(struct drm_connector *connector, | |
782 | const struct drm_connector_helper_funcs *funcs) | |
783 | { | |
784 | connector->helper_private = funcs; | |
785 | } | |
786 | ||
787 | /** | |
11a0ba97 | 788 | * struct drm_plane_helper_funcs - helper operations for planes |
092d01da | 789 | * |
11a0ba97 DV |
790 | * These functions are used by the atomic helpers and by the transitional plane |
791 | * helpers. | |
092d01da DV |
792 | */ |
793 | struct drm_plane_helper_funcs { | |
11a0ba97 DV |
794 | /** |
795 | * @prepare_fb: | |
796 | * | |
797 | * This hook is to prepare a framebuffer for scanout by e.g. pinning | |
798 | * it's backing storage or relocating it into a contiguous block of | |
799 | * VRAM. Other possible preparatory work includes flushing caches. | |
800 | * | |
801 | * This function must not block for outstanding rendering, since it is | |
802 | * called in the context of the atomic IOCTL even for async commits to | |
803 | * be able to return any errors to userspace. Instead the recommended | |
804 | * way is to fill out the fence member of the passed-in | |
805 | * &drm_plane_state. If the driver doesn't support native fences then | |
806 | * equivalent functionality should be implemented through private | |
807 | * members in the plane structure. | |
808 | * | |
809 | * The helpers will call @cleanup_fb with matching arguments for every | |
810 | * successful call to this hook. | |
811 | * | |
812 | * This callback is used by the atomic modeset helpers and by the | |
813 | * transitional plane helpers, but it is optional. | |
814 | * | |
815 | * RETURNS: | |
816 | * | |
817 | * 0 on success or one of the following negative error codes allowed by | |
818 | * the atomic_commit hook in &drm_mode_config_funcs. When using helpers | |
819 | * this callback is the only one which can fail an atomic commit, | |
820 | * everything else must complete successfully. | |
821 | */ | |
092d01da DV |
822 | int (*prepare_fb)(struct drm_plane *plane, |
823 | const struct drm_plane_state *new_state); | |
11a0ba97 DV |
824 | /** |
825 | * @cleanup_fb: | |
826 | * | |
827 | * This hook is called to clean up any resources allocated for the given | |
828 | * framebuffer and plane configuration in @prepare_fb. | |
829 | * | |
830 | * This callback is used by the atomic modeset helpers and by the | |
831 | * transitional plane helpers, but it is optional. | |
832 | */ | |
092d01da DV |
833 | void (*cleanup_fb)(struct drm_plane *plane, |
834 | const struct drm_plane_state *old_state); | |
835 | ||
11a0ba97 DV |
836 | /** |
837 | * @atomic_check: | |
838 | * | |
839 | * Drivers should check plane specific constraints in this hook. | |
840 | * | |
841 | * When using drm_atomic_helper_check_planes() plane's ->atomic_check() | |
842 | * hooks are called before the ones for CRTCs, which allows drivers to | |
843 | * request shared resources that the CRTC controls here. For more | |
844 | * complicated dependencies the driver can call the provided check helpers | |
845 | * multiple times until the computed state has a final configuration and | |
846 | * everything has been checked. | |
847 | * | |
848 | * This function is also allowed to inspect any other object's state and | |
849 | * can add more state objects to the atomic commit if needed. Care must | |
850 | * be taken though to ensure that state check&compute functions for | |
851 | * these added states are all called, and derived state in other objects | |
852 | * all updated. Again the recommendation is to just call check helpers | |
853 | * until a maximal configuration is reached. | |
854 | * | |
855 | * This callback is used by the atomic modeset helpers and by the | |
856 | * transitional plane helpers, but it is optional. | |
857 | * | |
858 | * NOTE: | |
859 | * | |
860 | * This function is called in the check phase of an atomic update. The | |
861 | * driver is not allowed to change anything outside of the free-standing | |
862 | * state objects passed-in or assembled in the overall &drm_atomic_state | |
863 | * update tracking structure. | |
864 | * | |
865 | * RETURNS: | |
866 | * | |
867 | * 0 on success, -EINVAL if the state or the transition can't be | |
868 | * supported, -ENOMEM on memory allocation failure and -EDEADLK if an | |
869 | * attempt to obtain another state object ran into a &drm_modeset_lock | |
870 | * deadlock. | |
871 | */ | |
092d01da DV |
872 | int (*atomic_check)(struct drm_plane *plane, |
873 | struct drm_plane_state *state); | |
11a0ba97 DV |
874 | |
875 | /** | |
876 | * @atomic_update: | |
877 | * | |
878 | * Drivers should use this function to update the plane state. This | |
879 | * hook is called in-between the ->atomic_begin() and | |
880 | * ->atomic_flush() of &drm_crtc_helper_funcs. | |
881 | * | |
882 | * Note that the power state of the display pipe when this function is | |
883 | * called depends upon the exact helpers and calling sequence the driver | |
884 | * has picked. See drm_atomic_commit_planes() for a discussion of the | |
885 | * tradeoffs and variants of plane commit helpers. | |
886 | * | |
887 | * This callback is used by the atomic modeset helpers and by the | |
888 | * transitional plane helpers, but it is optional. | |
889 | */ | |
092d01da DV |
890 | void (*atomic_update)(struct drm_plane *plane, |
891 | struct drm_plane_state *old_state); | |
11a0ba97 DV |
892 | /** |
893 | * @atomic_disable: | |
894 | * | |
895 | * Drivers should use this function to unconditionally disable a plane. | |
896 | * This hook is called in-between the ->atomic_begin() and | |
897 | * ->atomic_flush() of &drm_crtc_helper_funcs. It is an alternative to | |
898 | * @atomic_update, which will be called for disabling planes, too, if | |
899 | * the @atomic_disable hook isn't implemented. | |
900 | * | |
901 | * This hook is also useful to disable planes in preparation of a modeset, | |
902 | * by calling drm_atomic_helper_disable_planes_on_crtc() from the | |
903 | * ->disable() hook in &drm_crtc_helper_funcs. | |
904 | * | |
905 | * Note that the power state of the display pipe when this function is | |
906 | * called depends upon the exact helpers and calling sequence the driver | |
907 | * has picked. See drm_atomic_commit_planes() for a discussion of the | |
908 | * tradeoffs and variants of plane commit helpers. | |
909 | * | |
910 | * This callback is used by the atomic modeset helpers and by the | |
911 | * transitional plane helpers, but it is optional. | |
912 | */ | |
092d01da DV |
913 | void (*atomic_disable)(struct drm_plane *plane, |
914 | struct drm_plane_state *old_state); | |
915 | }; | |
916 | ||
917 | /** | |
918 | * drm_plane_helper_add - sets the helper vtable for a plane | |
919 | * @plane: DRM plane | |
920 | * @funcs: helper vtable to set for @plane | |
921 | */ | |
922 | static inline void drm_plane_helper_add(struct drm_plane *plane, | |
923 | const struct drm_plane_helper_funcs *funcs) | |
924 | { | |
925 | plane->helper_private = funcs; | |
926 | } | |
927 | ||
928 | #endif |