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 | * | |
134 | * RETURNS: | |
135 | * | |
136 | * True if an acceptable configuration is possible, false if the modeset | |
137 | * operation should be rejected. | |
138 | */ | |
092d01da DV |
139 | bool (*mode_fixup)(struct drm_crtc *crtc, |
140 | const struct drm_display_mode *mode, | |
141 | struct drm_display_mode *adjusted_mode); | |
36b66080 DV |
142 | |
143 | /** | |
144 | * @mode_set: | |
145 | * | |
146 | * This callback is used by the legacy CRTC helpers to set a new mode, | |
147 | * position and framebuffer. Since it ties the primary plane to every | |
148 | * mode change it is incompatible with universal plane support. And | |
149 | * since it can't update other planes it's incompatible with atomic | |
150 | * modeset support. | |
151 | * | |
152 | * This callback is only used by CRTC helpers and deprecated. | |
153 | * | |
154 | * RETURNS: | |
155 | * | |
156 | * 0 on success or a negative error code on failure. | |
157 | */ | |
092d01da DV |
158 | int (*mode_set)(struct drm_crtc *crtc, struct drm_display_mode *mode, |
159 | struct drm_display_mode *adjusted_mode, int x, int y, | |
160 | struct drm_framebuffer *old_fb); | |
36b66080 DV |
161 | |
162 | /** | |
163 | * @mode_set_nofb: | |
164 | * | |
165 | * This callback is used to update the display mode of a CRTC without | |
166 | * changing anything of the primary plane configuration. This fits the | |
167 | * requirement of atomic and hence is used by the atomic helpers. It is | |
168 | * also used by the transitional plane helpers to implement a | |
169 | * @mode_set hook in drm_helper_crtc_mode_set(). | |
170 | * | |
171 | * Note that the display pipe is completely off when this function is | |
172 | * called. Atomic drivers which need hardware to be running before they | |
173 | * program the new display mode (e.g. because they implement runtime PM) | |
174 | * should not use this hook. This is because the helper library calls | |
175 | * this hook only once per mode change and not every time the display | |
176 | * pipeline is suspended using either DPMS or the new "ACTIVE" property. | |
177 | * Which means register values set in this callback might get reset when | |
178 | * the CRTC is suspended, but not restored. Such drivers should instead | |
179 | * move all their CRTC setup into the @enable callback. | |
180 | * | |
181 | * This callback is optional. | |
182 | */ | |
092d01da DV |
183 | void (*mode_set_nofb)(struct drm_crtc *crtc); |
184 | ||
36b66080 DV |
185 | /** |
186 | * @mode_set_base: | |
187 | * | |
188 | * This callback is used by the legacy CRTC helpers to set a new | |
189 | * framebuffer and scanout position. It is optional and used as an | |
190 | * optimized fast-path instead of a full mode set operation with all the | |
191 | * resulting flickering. Since it can't update other planes it's | |
192 | * incompatible with atomic modeset support. | |
193 | * | |
194 | * This callback is only used by the CRTC helpers and deprecated. | |
195 | * | |
196 | * RETURNS: | |
197 | * | |
198 | * 0 on success or a negative error code on failure. | |
199 | */ | |
092d01da DV |
200 | int (*mode_set_base)(struct drm_crtc *crtc, int x, int y, |
201 | struct drm_framebuffer *old_fb); | |
36b66080 DV |
202 | |
203 | /** | |
204 | * @mode_set_base_atomic: | |
205 | * | |
206 | * This callback is used by the fbdev helpers to set a new framebuffer | |
207 | * and scanout without sleeping, i.e. from an atomic calling context. It | |
208 | * is only used to implement kgdb support. | |
209 | * | |
210 | * This callback is optional and only needed for kgdb support in the fbdev | |
211 | * helpers. | |
212 | * | |
213 | * RETURNS: | |
214 | * | |
215 | * 0 on success or a negative error code on failure. | |
216 | */ | |
092d01da DV |
217 | int (*mode_set_base_atomic)(struct drm_crtc *crtc, |
218 | struct drm_framebuffer *fb, int x, int y, | |
219 | enum mode_set_atomic); | |
220 | ||
36b66080 DV |
221 | /** |
222 | * @load_lut: | |
223 | * | |
224 | * Load a LUT prepared with the @gamma_set functions from | |
225 | * &drm_fb_helper_funcs. | |
226 | * | |
227 | * This callback is optional and is only used by the fbdev emulation | |
228 | * helpers. | |
229 | * | |
230 | * FIXME: | |
231 | * | |
232 | * This callback is functionally redundant with the core gamma table | |
233 | * support and simply exists because the fbdev hasn't yet been | |
234 | * refactored to use the core gamma table interfaces. | |
235 | */ | |
092d01da DV |
236 | void (*load_lut)(struct drm_crtc *crtc); |
237 | ||
36b66080 DV |
238 | /** |
239 | * @disable: | |
240 | * | |
241 | * This callback should be used to disable the CRTC. With the atomic | |
242 | * drivers it is called after all encoders connected to this CRTC have | |
243 | * been shut off already using their own ->disable hook. If that | |
244 | * sequence is too simple drivers can just add their own hooks and call | |
245 | * it from this CRTC callback here by looping over all encoders | |
246 | * connected to it using for_each_encoder_on_crtc(). | |
247 | * | |
248 | * This hook is used both by legacy CRTC helpers and atomic helpers. | |
249 | * Atomic drivers don't need to implement it if there's no need to | |
250 | * disable anything at the CRTC level. To ensure that runtime PM | |
251 | * handling (using either DPMS or the new "ACTIVE" property) works | |
252 | * @disable must be the inverse of @enable for atomic drivers. | |
253 | * | |
254 | * NOTE: | |
255 | * | |
256 | * With legacy CRTC helpers there's a big semantic difference between | |
257 | * @disable and other hooks (like @prepare or @dpms) used to shut down a | |
258 | * CRTC: @disable is only called when also logically disabling the | |
259 | * display pipeline and needs to release any resources acquired in | |
260 | * @mode_set (like shared PLLs, or again release pinned framebuffers). | |
261 | * | |
262 | * Therefore @disable must be the inverse of @mode_set plus @commit for | |
263 | * drivers still using legacy CRTC helpers, which is different from the | |
264 | * rules under atomic. | |
265 | */ | |
092d01da | 266 | void (*disable)(struct drm_crtc *crtc); |
36b66080 DV |
267 | |
268 | /** | |
269 | * @enable: | |
270 | * | |
271 | * This callback should be used to enable the CRTC. With the atomic | |
272 | * drivers it is called before all encoders connected to this CRTC are | |
273 | * enabled through the encoder's own ->enable hook. If that sequence is | |
274 | * too simple drivers can just add their own hooks and call it from this | |
275 | * CRTC callback here by looping over all encoders connected to it using | |
276 | * for_each_encoder_on_crtc(). | |
277 | * | |
278 | * This hook is used only by atomic helpers, for symmetry with @disable. | |
279 | * Atomic drivers don't need to implement it if there's no need to | |
280 | * enable anything at the CRTC level. To ensure that runtime PM handling | |
281 | * (using either DPMS or the new "ACTIVE" property) works | |
282 | * @enable must be the inverse of @disable for atomic drivers. | |
283 | */ | |
092d01da DV |
284 | void (*enable)(struct drm_crtc *crtc); |
285 | ||
11a0ba97 DV |
286 | /** |
287 | * @atomic_check: | |
288 | * | |
289 | * Drivers should check plane-update related CRTC constraints in this | |
290 | * hook. They can also check mode related limitations but need to be | |
291 | * aware of the calling order, since this hook is used by | |
292 | * drm_atomic_helper_check_planes() whereas the preparations needed to | |
293 | * check output routing and the display mode is done in | |
294 | * drm_atomic_helper_check_modeset(). Therefore drivers that want to | |
295 | * check output routing and display mode constraints in this callback | |
296 | * must ensure that drm_atomic_helper_check_modeset() has been called | |
297 | * beforehand. This is calling order used by the default helper | |
298 | * implementation in drm_atomic_helper_check(). | |
299 | * | |
300 | * When using drm_atomic_helper_check_planes() CRTCs' ->atomic_check() | |
301 | * hooks are called after the ones for planes, which allows drivers to | |
302 | * assign shared resources requested by planes in the CRTC callback | |
303 | * here. For more complicated dependencies the driver can call the provided | |
304 | * check helpers multiple times until the computed state has a final | |
305 | * configuration and everything has been checked. | |
306 | * | |
307 | * This function is also allowed to inspect any other object's state and | |
308 | * can add more state objects to the atomic commit if needed. Care must | |
309 | * be taken though to ensure that state check&compute functions for | |
310 | * these added states are all called, and derived state in other objects | |
311 | * all updated. Again the recommendation is to just call check helpers | |
312 | * until a maximal configuration is reached. | |
313 | * | |
314 | * This callback is used by the atomic modeset helpers and by the | |
315 | * transitional plane helpers, but it is optional. | |
316 | * | |
317 | * NOTE: | |
318 | * | |
319 | * This function is called in the check phase of an atomic update. The | |
320 | * driver is not allowed to change anything outside of the free-standing | |
321 | * state objects passed-in or assembled in the overall &drm_atomic_state | |
322 | * update tracking structure. | |
323 | * | |
324 | * RETURNS: | |
325 | * | |
326 | * 0 on success, -EINVAL if the state or the transition can't be | |
327 | * supported, -ENOMEM on memory allocation failure and -EDEADLK if an | |
328 | * attempt to obtain another state object ran into a &drm_modeset_lock | |
329 | * deadlock. | |
330 | */ | |
092d01da DV |
331 | int (*atomic_check)(struct drm_crtc *crtc, |
332 | struct drm_crtc_state *state); | |
11a0ba97 DV |
333 | |
334 | /** | |
335 | * @atomic_begin: | |
336 | * | |
337 | * Drivers should prepare for an atomic update of multiple planes on | |
338 | * a CRTC in this hook. Depending upon hardware this might be vblank | |
339 | * evasion, blocking updates by setting bits or doing preparatory work | |
340 | * for e.g. manual update display. | |
341 | * | |
342 | * This hook is called before any plane commit functions are called. | |
343 | * | |
344 | * Note that the power state of the display pipe when this function is | |
345 | * called depends upon the exact helpers and calling sequence the driver | |
346 | * has picked. See drm_atomic_commit_planes() for a discussion of the | |
347 | * tradeoffs and variants of plane commit helpers. | |
348 | * | |
349 | * This callback is used by the atomic modeset helpers and by the | |
350 | * transitional plane helpers, but it is optional. | |
351 | */ | |
092d01da DV |
352 | void (*atomic_begin)(struct drm_crtc *crtc, |
353 | struct drm_crtc_state *old_crtc_state); | |
11a0ba97 DV |
354 | /** |
355 | * @atomic_flush: | |
356 | * | |
357 | * Drivers should finalize an atomic update of multiple planes on | |
358 | * a CRTC in this hook. Depending upon hardware this might include | |
359 | * checking that vblank evasion was successful, unblocking updates by | |
360 | * setting bits or setting the GO bit to flush out all updates. | |
361 | * | |
362 | * Simple hardware or hardware with special requirements can commit and | |
363 | * flush out all updates for all planes from this hook and forgo all the | |
364 | * other commit hooks for plane updates. | |
365 | * | |
366 | * This hook is called after any plane commit functions are called. | |
367 | * | |
368 | * Note that the power state of the display pipe when this function is | |
369 | * called depends upon the exact helpers and calling sequence the driver | |
370 | * has picked. See drm_atomic_commit_planes() for a discussion of the | |
371 | * tradeoffs and variants of plane commit helpers. | |
372 | * | |
373 | * This callback is used by the atomic modeset helpers and by the | |
374 | * transitional plane helpers, but it is optional. | |
375 | */ | |
092d01da DV |
376 | void (*atomic_flush)(struct drm_crtc *crtc, |
377 | struct drm_crtc_state *old_crtc_state); | |
378 | }; | |
379 | ||
380 | /** | |
381 | * drm_crtc_helper_add - sets the helper vtable for a crtc | |
382 | * @crtc: DRM CRTC | |
383 | * @funcs: helper vtable to set for @crtc | |
384 | */ | |
385 | static inline void drm_crtc_helper_add(struct drm_crtc *crtc, | |
386 | const struct drm_crtc_helper_funcs *funcs) | |
387 | { | |
388 | crtc->helper_private = funcs; | |
389 | } | |
390 | ||
391 | /** | |
392 | * struct drm_encoder_helper_funcs - helper operations for encoders | |
092d01da | 393 | * |
36b66080 DV |
394 | * These hooks are used by the legacy CRTC helpers, the transitional plane |
395 | * helpers and the new atomic modesetting helpers. | |
092d01da DV |
396 | */ |
397 | struct drm_encoder_helper_funcs { | |
36b66080 DV |
398 | /** |
399 | * @dpms: | |
400 | * | |
401 | * Callback to control power levels on the encoder. If the mode passed in | |
402 | * is unsupported, the provider must use the next lowest power level. | |
403 | * This is used by the legacy encoder helpers to implement DPMS | |
404 | * functionality in drm_helper_connector_dpms(). | |
405 | * | |
406 | * This callback is also used to disable an encoder by calling it with | |
407 | * DRM_MODE_DPMS_OFF if the @disable hook isn't used. | |
408 | * | |
409 | * This callback is used by the legacy CRTC helpers. Atomic helpers | |
410 | * also support using this hook for enabling and disabling an encoder to | |
411 | * facilitate transitions to atomic, but it is deprecated. Instead | |
412 | * @enable and @disable should be used. | |
413 | */ | |
092d01da | 414 | void (*dpms)(struct drm_encoder *encoder, int mode); |
092d01da | 415 | |
36b66080 DV |
416 | /** |
417 | * @mode_fixup: | |
418 | * | |
419 | * This callback is used to validate and adjust a mode. The parameter | |
420 | * mode is the display mode that should be fed to the next element in | |
421 | * the display chain, either the final &drm_connector or a &drm_bridge. | |
422 | * The parameter adjusted_mode is the input mode the encoder requires. It | |
423 | * can be modified by this callback and does not need to match mode. | |
424 | * | |
425 | * This function is used by both legacy CRTC helpers and atomic helpers. | |
426 | * With atomic helpers it is optional. | |
427 | * | |
428 | * NOTE: | |
429 | * | |
430 | * This function is called in the check phase of atomic modesets, which | |
431 | * can be aborted for any reason (including on userspace's request to | |
432 | * just check whether a configuration would be possible). Atomic drivers | |
433 | * MUST NOT touch any persistent state (hardware or software) or data | |
434 | * structures except the passed in adjusted_mode parameter. | |
435 | * | |
436 | * This is in contrast to the legacy CRTC helpers where this was | |
437 | * allowed. | |
438 | * | |
439 | * Atomic drivers which need to inspect and adjust more state should | |
440 | * instead use the @atomic_check callback. | |
441 | * | |
442 | * RETURNS: | |
443 | * | |
444 | * True if an acceptable configuration is possible, false if the modeset | |
445 | * operation should be rejected. | |
446 | */ | |
092d01da DV |
447 | bool (*mode_fixup)(struct drm_encoder *encoder, |
448 | const struct drm_display_mode *mode, | |
449 | struct drm_display_mode *adjusted_mode); | |
36b66080 DV |
450 | |
451 | /** | |
452 | * @prepare: | |
453 | * | |
454 | * This callback should prepare the encoder for a subsequent modeset, | |
455 | * which in practice means the driver should disable the encoder if it | |
456 | * is running. Most drivers ended up implementing this by calling their | |
457 | * @dpms hook with DRM_MODE_DPMS_OFF. | |
458 | * | |
459 | * This callback is used by the legacy CRTC helpers. Atomic helpers | |
460 | * also support using this hook for disabling an encoder to facilitate | |
461 | * transitions to atomic, but it is deprecated. Instead @disable should | |
462 | * be used. | |
463 | */ | |
092d01da | 464 | void (*prepare)(struct drm_encoder *encoder); |
36b66080 DV |
465 | |
466 | /** | |
467 | * @commit: | |
468 | * | |
469 | * This callback should commit the new mode on the encoder after a modeset, | |
470 | * which in practice means the driver should enable the encoder. Most | |
471 | * drivers ended up implementing this by calling their @dpms hook with | |
472 | * DRM_MODE_DPMS_ON. | |
473 | * | |
474 | * This callback is used by the legacy CRTC helpers. Atomic helpers | |
475 | * also support using this hook for enabling an encoder to facilitate | |
476 | * transitions to atomic, but it is deprecated. Instead @enable should | |
477 | * be used. | |
478 | */ | |
092d01da | 479 | void (*commit)(struct drm_encoder *encoder); |
36b66080 DV |
480 | |
481 | /** | |
482 | * @mode_set: | |
483 | * | |
484 | * This callback is used to update the display mode of an encoder. | |
485 | * | |
486 | * Note that the display pipe is completely off when this function is | |
487 | * called. Drivers which need hardware to be running before they program | |
488 | * the new display mode (because they implement runtime PM) should not | |
489 | * use this hook, because the helper library calls it only once and not | |
490 | * every time the display pipeline is suspend using either DPMS or the | |
491 | * new "ACTIVE" property. Such drivers should instead move all their | |
492 | * encoder setup into the ->enable() callback. | |
493 | * | |
494 | * This callback is used both by the legacy CRTC helpers and the atomic | |
495 | * modeset helpers. It is optional in the atomic helpers. | |
496 | */ | |
092d01da DV |
497 | void (*mode_set)(struct drm_encoder *encoder, |
498 | struct drm_display_mode *mode, | |
499 | struct drm_display_mode *adjusted_mode); | |
36b66080 DV |
500 | |
501 | /** | |
502 | * @get_crtc: | |
503 | * | |
504 | * This callback is used by the legacy CRTC helpers to work around | |
505 | * deficiencies in its own book-keeping. | |
506 | * | |
507 | * Do not use, use atomic helpers instead, which get the book keeping | |
508 | * right. | |
509 | * | |
510 | * FIXME: | |
511 | * | |
512 | * Currently only nouveau is using this, and as soon as nouveau is | |
513 | * atomic we can ditch this hook. | |
514 | */ | |
092d01da | 515 | struct drm_crtc *(*get_crtc)(struct drm_encoder *encoder); |
36b66080 DV |
516 | |
517 | /** | |
518 | * @detect: | |
519 | * | |
520 | * This callback can be used by drivers who want to do detection on the | |
521 | * encoder object instead of in connector functions. | |
522 | * | |
523 | * It is not used by any helper and therefore has purely driver-specific | |
524 | * semantics. New drivers shouldn't use this and instead just implement | |
525 | * their own private callbacks. | |
526 | * | |
527 | * FIXME: | |
528 | * | |
529 | * This should just be converted into a pile of driver vfuncs. | |
530 | * Currently radeon, amdgpu and nouveau are using it. | |
531 | */ | |
092d01da DV |
532 | enum drm_connector_status (*detect)(struct drm_encoder *encoder, |
533 | struct drm_connector *connector); | |
36b66080 DV |
534 | |
535 | /** | |
536 | * @disable: | |
537 | * | |
538 | * This callback should be used to disable the encoder. With the atomic | |
539 | * drivers it is called before this encoder's CRTC has been shut off | |
540 | * using the CRTC's own ->disable hook. If that sequence is too simple | |
541 | * drivers can just add their own driver private encoder hooks and call | |
542 | * them from CRTC's callback by looping over all encoders connected to | |
543 | * it using for_each_encoder_on_crtc(). | |
544 | * | |
545 | * This hook is used both by legacy CRTC helpers and atomic helpers. | |
546 | * Atomic drivers don't need to implement it if there's no need to | |
547 | * disable anything at the encoder level. To ensure that runtime PM | |
548 | * handling (using either DPMS or the new "ACTIVE" property) works | |
549 | * @disable must be the inverse of @enable for atomic drivers. | |
550 | * | |
551 | * NOTE: | |
552 | * | |
553 | * With legacy CRTC helpers there's a big semantic difference between | |
554 | * @disable and other hooks (like @prepare or @dpms) used to shut down a | |
555 | * encoder: @disable is only called when also logically disabling the | |
556 | * display pipeline and needs to release any resources acquired in | |
557 | * @mode_set (like shared PLLs, or again release pinned framebuffers). | |
558 | * | |
559 | * Therefore @disable must be the inverse of @mode_set plus @commit for | |
560 | * drivers still using legacy CRTC helpers, which is different from the | |
561 | * rules under atomic. | |
562 | */ | |
092d01da DV |
563 | void (*disable)(struct drm_encoder *encoder); |
564 | ||
36b66080 DV |
565 | /** |
566 | * @enable: | |
567 | * | |
568 | * This callback should be used to enable the encoder. With the atomic | |
569 | * drivers it is called after this encoder's CRTC has been enabled using | |
570 | * the CRTC's own ->enable hook. If that sequence is too simple drivers | |
571 | * can just add their own driver private encoder hooks and call them | |
572 | * from CRTC's callback by looping over all encoders connected to it | |
573 | * using for_each_encoder_on_crtc(). | |
574 | * | |
575 | * This hook is used only by atomic helpers, for symmetry with @disable. | |
576 | * Atomic drivers don't need to implement it if there's no need to | |
577 | * enable anything at the encoder level. To ensure that runtime PM handling | |
578 | * (using either DPMS or the new "ACTIVE" property) works | |
579 | * @enable must be the inverse of @disable for atomic drivers. | |
580 | */ | |
092d01da DV |
581 | void (*enable)(struct drm_encoder *encoder); |
582 | ||
36b66080 DV |
583 | /** |
584 | * @atomic_check: | |
585 | * | |
586 | * This callback is used to validate encoder state for atomic drivers. | |
587 | * Since the encoder is the object connecting the CRTC and connector it | |
588 | * gets passed both states, to be able to validate interactions and | |
589 | * update the CRTC to match what the encoder needs for the requested | |
590 | * connector. | |
591 | * | |
592 | * This function is used by the atomic helpers, but it is optional. | |
593 | * | |
594 | * NOTE: | |
595 | * | |
596 | * This function is called in the check phase of an atomic update. The | |
597 | * driver is not allowed to change anything outside of the free-standing | |
598 | * state objects passed-in or assembled in the overall &drm_atomic_state | |
599 | * update tracking structure. | |
600 | * | |
601 | * RETURNS: | |
602 | * | |
603 | * 0 on success, -EINVAL if the state or the transition can't be | |
604 | * supported, -ENOMEM on memory allocation failure and -EDEADLK if an | |
605 | * attempt to obtain another state object ran into a &drm_modeset_lock | |
606 | * deadlock. | |
607 | */ | |
092d01da DV |
608 | int (*atomic_check)(struct drm_encoder *encoder, |
609 | struct drm_crtc_state *crtc_state, | |
610 | struct drm_connector_state *conn_state); | |
611 | }; | |
612 | ||
613 | /** | |
36b66080 | 614 | * drm_encoder_helper_add - sets the helper vtable for an encoder |
092d01da DV |
615 | * @encoder: DRM encoder |
616 | * @funcs: helper vtable to set for @encoder | |
617 | */ | |
618 | static inline void drm_encoder_helper_add(struct drm_encoder *encoder, | |
619 | const struct drm_encoder_helper_funcs *funcs) | |
620 | { | |
621 | encoder->helper_private = funcs; | |
622 | } | |
623 | ||
624 | /** | |
625 | * struct drm_connector_helper_funcs - helper operations for connectors | |
092d01da | 626 | * |
4ee6034c DV |
627 | * These functions are used by the atomic and legacy modeset helpers and by the |
628 | * probe helpers. | |
092d01da DV |
629 | */ |
630 | struct drm_connector_helper_funcs { | |
4ee6034c DV |
631 | /** |
632 | * @get_modes: | |
633 | * | |
634 | * This function should fill in all modes currently valid for the sink | |
635 | * into the connector->probed_modes list. It should also update the | |
636 | * EDID property by calling drm_mode_connector_update_edid_property(). | |
637 | * | |
638 | * The usual way to implement this is to cache the EDID retrieved in the | |
639 | * probe callback somewhere in the driver-private connector structure. | |
640 | * In this function drivers then parse the modes in the EDID and add | |
641 | * them by calling drm_add_edid_modes(). But connectors that driver a | |
642 | * fixed panel can also manually add specific modes using | |
643 | * drm_mode_probed_add(). Finally drivers that support audio probably | |
644 | * want to update the ELD data, too, using drm_edid_to_eld(). | |
645 | * | |
646 | * This function is only called after the ->detect() hook has indicated | |
647 | * that a sink is connected and when the EDID isn't overridden through | |
648 | * sysfs or the kernel commandline. | |
649 | * | |
650 | * This callback is used by the probe helpers in e.g. | |
651 | * drm_helper_probe_single_connector_modes(). | |
652 | * | |
653 | * RETURNS: | |
654 | * | |
655 | * The number of modes added by calling drm_mode_probed_add(). | |
656 | */ | |
092d01da | 657 | int (*get_modes)(struct drm_connector *connector); |
4ee6034c DV |
658 | |
659 | /** | |
660 | * @mode_valid: | |
661 | * | |
662 | * Callback to validate a mode for a connector, irrespective of the | |
663 | * specific display configuration. | |
664 | * | |
665 | * This callback is used by the probe helpers to filter the mode list | |
666 | * (which is usually derived from the EDID data block from the sink). | |
667 | * See e.g. drm_helper_probe_single_connector_modes(). | |
668 | * | |
669 | * NOTE: | |
670 | * | |
671 | * This only filters the mode list supplied to userspace in the | |
672 | * GETCONNECOTR IOCTL. Userspace is free to create modes of its own and | |
673 | * ask the kernel to use them. It this case the atomic helpers or legacy | |
674 | * CRTC helpers will not call this function. Drivers therefore must | |
675 | * still fully validate any mode passed in in a modeset request. | |
676 | * | |
677 | * RETURNS: | |
678 | * | |
679 | * Either MODE_OK or one of the failure reasons in enum | |
680 | * &drm_mode_status. | |
681 | */ | |
092d01da DV |
682 | enum drm_mode_status (*mode_valid)(struct drm_connector *connector, |
683 | struct drm_display_mode *mode); | |
4ee6034c DV |
684 | /** |
685 | * @best_encoder: | |
686 | * | |
687 | * This function should select the best encoder for the given connector. | |
688 | * | |
689 | * This function is used by both the atomic helpers (in the | |
690 | * drm_atomic_helper_check_modeset() function) and in the legacy CRTC | |
691 | * helpers. | |
692 | * | |
693 | * NOTE: | |
694 | * | |
695 | * In atomic drivers this function is called in the check phase of an | |
696 | * atomic update. The driver is not allowed to change or inspect | |
697 | * anything outside of arguments passed-in. Atomic drivers which need to | |
698 | * inspect dynamic configuration state should instead use | |
699 | * @atomic_best_encoder. | |
700 | * | |
701 | * RETURNS: | |
702 | * | |
703 | * Encoder that should be used for the given connector and connector | |
704 | * state, or NULL if no suitable encoder exists. Note that the helpers | |
705 | * will ensure that encoders aren't used twice, drivers should not check | |
706 | * for this. | |
707 | */ | |
092d01da | 708 | struct drm_encoder *(*best_encoder)(struct drm_connector *connector); |
4ee6034c DV |
709 | |
710 | /** | |
711 | * @atomic_best_encoder: | |
712 | * | |
713 | * This is the atomic version of @best_encoder for atomic drivers which | |
714 | * need to select the best encoder depending upon the desired | |
715 | * configuration and can't select it statically. | |
716 | * | |
717 | * This function is used by drm_atomic_helper_check_modeset() and either | |
718 | * this or @best_encoder is required. | |
719 | * | |
720 | * NOTE: | |
721 | * | |
722 | * This function is called in the check phase of an atomic update. The | |
723 | * driver is not allowed to change anything outside of the free-standing | |
724 | * state objects passed-in or assembled in the overall &drm_atomic_state | |
725 | * update tracking structure. | |
726 | * | |
727 | * RETURNS: | |
728 | * | |
729 | * Encoder that should be used for the given connector and connector | |
730 | * state, or NULL if no suitable encoder exists. Note that the helpers | |
731 | * will ensure that encoders aren't used twice, drivers should not check | |
732 | * for this. | |
733 | */ | |
092d01da DV |
734 | struct drm_encoder *(*atomic_best_encoder)(struct drm_connector *connector, |
735 | struct drm_connector_state *connector_state); | |
736 | }; | |
737 | ||
738 | /** | |
739 | * drm_connector_helper_add - sets the helper vtable for a connector | |
740 | * @connector: DRM connector | |
741 | * @funcs: helper vtable to set for @connector | |
742 | */ | |
743 | static inline void drm_connector_helper_add(struct drm_connector *connector, | |
744 | const struct drm_connector_helper_funcs *funcs) | |
745 | { | |
746 | connector->helper_private = funcs; | |
747 | } | |
748 | ||
749 | /** | |
11a0ba97 | 750 | * struct drm_plane_helper_funcs - helper operations for planes |
092d01da | 751 | * |
11a0ba97 DV |
752 | * These functions are used by the atomic helpers and by the transitional plane |
753 | * helpers. | |
092d01da DV |
754 | */ |
755 | struct drm_plane_helper_funcs { | |
11a0ba97 DV |
756 | /** |
757 | * @prepare_fb: | |
758 | * | |
759 | * This hook is to prepare a framebuffer for scanout by e.g. pinning | |
760 | * it's backing storage or relocating it into a contiguous block of | |
761 | * VRAM. Other possible preparatory work includes flushing caches. | |
762 | * | |
763 | * This function must not block for outstanding rendering, since it is | |
764 | * called in the context of the atomic IOCTL even for async commits to | |
765 | * be able to return any errors to userspace. Instead the recommended | |
766 | * way is to fill out the fence member of the passed-in | |
767 | * &drm_plane_state. If the driver doesn't support native fences then | |
768 | * equivalent functionality should be implemented through private | |
769 | * members in the plane structure. | |
770 | * | |
771 | * The helpers will call @cleanup_fb with matching arguments for every | |
772 | * successful call to this hook. | |
773 | * | |
774 | * This callback is used by the atomic modeset helpers and by the | |
775 | * transitional plane helpers, but it is optional. | |
776 | * | |
777 | * RETURNS: | |
778 | * | |
779 | * 0 on success or one of the following negative error codes allowed by | |
780 | * the atomic_commit hook in &drm_mode_config_funcs. When using helpers | |
781 | * this callback is the only one which can fail an atomic commit, | |
782 | * everything else must complete successfully. | |
783 | */ | |
092d01da DV |
784 | int (*prepare_fb)(struct drm_plane *plane, |
785 | const struct drm_plane_state *new_state); | |
11a0ba97 DV |
786 | /** |
787 | * @cleanup_fb: | |
788 | * | |
789 | * This hook is called to clean up any resources allocated for the given | |
790 | * framebuffer and plane configuration in @prepare_fb. | |
791 | * | |
792 | * This callback is used by the atomic modeset helpers and by the | |
793 | * transitional plane helpers, but it is optional. | |
794 | */ | |
092d01da DV |
795 | void (*cleanup_fb)(struct drm_plane *plane, |
796 | const struct drm_plane_state *old_state); | |
797 | ||
11a0ba97 DV |
798 | /** |
799 | * @atomic_check: | |
800 | * | |
801 | * Drivers should check plane specific constraints in this hook. | |
802 | * | |
803 | * When using drm_atomic_helper_check_planes() plane's ->atomic_check() | |
804 | * hooks are called before the ones for CRTCs, which allows drivers to | |
805 | * request shared resources that the CRTC controls here. For more | |
806 | * complicated dependencies the driver can call the provided check helpers | |
807 | * multiple times until the computed state has a final configuration and | |
808 | * everything has been checked. | |
809 | * | |
810 | * This function is also allowed to inspect any other object's state and | |
811 | * can add more state objects to the atomic commit if needed. Care must | |
812 | * be taken though to ensure that state check&compute functions for | |
813 | * these added states are all called, and derived state in other objects | |
814 | * all updated. Again the recommendation is to just call check helpers | |
815 | * until a maximal configuration is reached. | |
816 | * | |
817 | * This callback is used by the atomic modeset helpers and by the | |
818 | * transitional plane helpers, but it is optional. | |
819 | * | |
820 | * NOTE: | |
821 | * | |
822 | * This function is called in the check phase of an atomic update. The | |
823 | * driver is not allowed to change anything outside of the free-standing | |
824 | * state objects passed-in or assembled in the overall &drm_atomic_state | |
825 | * update tracking structure. | |
826 | * | |
827 | * RETURNS: | |
828 | * | |
829 | * 0 on success, -EINVAL if the state or the transition can't be | |
830 | * supported, -ENOMEM on memory allocation failure and -EDEADLK if an | |
831 | * attempt to obtain another state object ran into a &drm_modeset_lock | |
832 | * deadlock. | |
833 | */ | |
092d01da DV |
834 | int (*atomic_check)(struct drm_plane *plane, |
835 | struct drm_plane_state *state); | |
11a0ba97 DV |
836 | |
837 | /** | |
838 | * @atomic_update: | |
839 | * | |
840 | * Drivers should use this function to update the plane state. This | |
841 | * hook is called in-between the ->atomic_begin() and | |
842 | * ->atomic_flush() of &drm_crtc_helper_funcs. | |
843 | * | |
844 | * Note that the power state of the display pipe when this function is | |
845 | * called depends upon the exact helpers and calling sequence the driver | |
846 | * has picked. See drm_atomic_commit_planes() for a discussion of the | |
847 | * tradeoffs and variants of plane commit helpers. | |
848 | * | |
849 | * This callback is used by the atomic modeset helpers and by the | |
850 | * transitional plane helpers, but it is optional. | |
851 | */ | |
092d01da DV |
852 | void (*atomic_update)(struct drm_plane *plane, |
853 | struct drm_plane_state *old_state); | |
11a0ba97 DV |
854 | /** |
855 | * @atomic_disable: | |
856 | * | |
857 | * Drivers should use this function to unconditionally disable a plane. | |
858 | * This hook is called in-between the ->atomic_begin() and | |
859 | * ->atomic_flush() of &drm_crtc_helper_funcs. It is an alternative to | |
860 | * @atomic_update, which will be called for disabling planes, too, if | |
861 | * the @atomic_disable hook isn't implemented. | |
862 | * | |
863 | * This hook is also useful to disable planes in preparation of a modeset, | |
864 | * by calling drm_atomic_helper_disable_planes_on_crtc() from the | |
865 | * ->disable() hook in &drm_crtc_helper_funcs. | |
866 | * | |
867 | * Note that the power state of the display pipe when this function is | |
868 | * called depends upon the exact helpers and calling sequence the driver | |
869 | * has picked. See drm_atomic_commit_planes() for a discussion of the | |
870 | * tradeoffs and variants of plane commit helpers. | |
871 | * | |
872 | * This callback is used by the atomic modeset helpers and by the | |
873 | * transitional plane helpers, but it is optional. | |
874 | */ | |
092d01da DV |
875 | void (*atomic_disable)(struct drm_plane *plane, |
876 | struct drm_plane_state *old_state); | |
877 | }; | |
878 | ||
879 | /** | |
880 | * drm_plane_helper_add - sets the helper vtable for a plane | |
881 | * @plane: DRM plane | |
882 | * @funcs: helper vtable to set for @plane | |
883 | */ | |
884 | static inline void drm_plane_helper_add(struct drm_plane *plane, | |
885 | const struct drm_plane_helper_funcs *funcs) | |
886 | { | |
887 | plane->helper_private = funcs; | |
888 | } | |
889 | ||
890 | #endif |