1 /* $NetBSD: drm_modeset_helper_vtables.h,v 1.2 2021/12/18 23:45:46 riastradh Exp $ */
2
3 /*
4 * Copyright © 2006 Keith Packard
5 * Copyright © 2007-2008 Dave Airlie
6 * Copyright © 2007-2008 Intel Corporation
7 * Jesse Barnes <jesse.barnes@intel.com>
8 * Copyright © 2011-2013 Intel Corporation
9 * Copyright © 2015 Intel Corporation
10 * Daniel Vetter <daniel.vetter@ffwll.ch>
11 *
12 * Permission is hereby granted, free of charge, to any person obtaining a
13 * copy of this software and associated documentation files (the "Software"),
14 * to deal in the Software without restriction, including without limitation
15 * the rights to use, copy, modify, merge, publish, distribute, sublicense,
16 * and/or sell copies of the Software, and to permit persons to whom the
17 * Software is furnished to do so, subject to the following conditions:
18 *
19 * The above copyright notice and this permission notice shall be included in
20 * all copies or substantial portions of the Software.
21 *
22 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
23 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
24 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
25 * THE COPYRIGHT HOLDER(S) OR AUTHOR(S) BE LIABLE FOR ANY CLAIM, DAMAGES OR
26 * OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
27 * ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
28 * OTHER DEALINGS IN THE SOFTWARE.
29 */
30
31 #ifndef __DRM_MODESET_HELPER_VTABLES_H__
32 #define __DRM_MODESET_HELPER_VTABLES_H__
33
34 #include <drm/drm_crtc.h>
35 #include <drm/drm_encoder.h>
36
37 /**
38 * DOC: overview
39 *
40 * The DRM mode setting helper functions are common code for drivers to use if
41 * they wish. Drivers are not forced to use this code in their
42 * implementations but it would be useful if the code they do use at least
43 * provides a consistent interface and operation to userspace. Therefore it is
44 * highly recommended to use the provided helpers as much as possible.
45 *
46 * Because there is only one pointer per modeset object to hold a vfunc table
47 * for helper libraries they are by necessity shared among the different
48 * helpers.
49 *
50 * To make this clear all the helper vtables are pulled together in this location here.
51 */
52
53 enum mode_set_atomic;
54 struct drm_writeback_connector;
55 struct drm_writeback_job;
56
57 /**
58 * struct drm_crtc_helper_funcs - helper operations for CRTCs
59 *
60 * These hooks are used by the legacy CRTC helpers, the transitional plane
61 * helpers and the new atomic modesetting helpers.
62 */
63 struct drm_crtc_helper_funcs {
64 /**
65 * @dpms:
66 *
67 * Callback to control power levels on the CRTC. If the mode passed in
68 * is unsupported, the provider must use the next lowest power level.
69 * This is used by the legacy CRTC helpers to implement DPMS
70 * functionality in drm_helper_connector_dpms().
71 *
72 * This callback is also used to disable a CRTC by calling it with
73 * DRM_MODE_DPMS_OFF if the @disable hook isn't used.
74 *
75 * This callback is used by the legacy CRTC helpers. Atomic helpers
76 * also support using this hook for enabling and disabling a CRTC to
77 * facilitate transitions to atomic, but it is deprecated. Instead
78 * @atomic_enable and @atomic_disable should be used.
79 */
80 void (*dpms)(struct drm_crtc *crtc, int mode);
81
82 /**
83 * @prepare:
84 *
85 * This callback should prepare the CRTC for a subsequent modeset, which
86 * in practice means the driver should disable the CRTC if it is
87 * running. Most drivers ended up implementing this by calling their
88 * @dpms hook with DRM_MODE_DPMS_OFF.
89 *
90 * This callback is used by the legacy CRTC helpers. Atomic helpers
91 * also support using this hook for disabling a CRTC to facilitate
92 * transitions to atomic, but it is deprecated. Instead @atomic_disable
93 * should be used.
94 */
95 void (*prepare)(struct drm_crtc *crtc);
96
97 /**
98 * @commit:
99 *
100 * This callback should commit the new mode on the CRTC after a modeset,
101 * which in practice means the driver should enable the CRTC. Most
102 * drivers ended up implementing this by calling their @dpms hook with
103 * DRM_MODE_DPMS_ON.
104 *
105 * This callback is used by the legacy CRTC helpers. Atomic helpers
106 * also support using this hook for enabling a CRTC to facilitate
107 * transitions to atomic, but it is deprecated. Instead @atomic_enable
108 * should be used.
109 */
110 void (*commit)(struct drm_crtc *crtc);
111
112 /**
113 * @mode_valid:
114 *
115 * This callback is used to check if a specific mode is valid in this
116 * crtc. This should be implemented if the crtc has some sort of
117 * restriction in the modes it can display. For example, a given crtc
118 * may be responsible to set a clock value. If the clock can not
119 * produce all the values for the available modes then this callback
120 * can be used to restrict the number of modes to only the ones that
121 * can be displayed.
122 *
123 * This hook is used by the probe helpers to filter the mode list in
124 * drm_helper_probe_single_connector_modes(), and it is used by the
125 * atomic helpers to validate modes supplied by userspace in
126 * drm_atomic_helper_check_modeset().
127 *
128 * This function is optional.
129 *
130 * NOTE:
131 *
132 * Since this function is both called from the check phase of an atomic
133 * commit, and the mode validation in the probe paths it is not allowed
134 * to look at anything else but the passed-in mode, and validate it
135 * against configuration-invariant hardward constraints. Any further
136 * limits which depend upon the configuration can only be checked in
137 * @mode_fixup or @atomic_check.
138 *
139 * RETURNS:
140 *
141 * drm_mode_status Enum
142 */
143 enum drm_mode_status (*mode_valid)(struct drm_crtc *crtc,
144 const struct drm_display_mode *mode);
145
146 /**
147 * @mode_fixup:
148 *
149 * This callback is used to validate a mode. The parameter mode is the
150 * display mode that userspace requested, adjusted_mode is the mode the
151 * encoders need to be fed with. Note that this is the inverse semantics
152 * of the meaning for the &drm_encoder and &drm_bridge_funcs.mode_fixup
153 * vfunc. If the CRTC cannot support the requested conversion from mode
154 * to adjusted_mode it should reject the modeset. See also
155 * &drm_crtc_state.adjusted_mode for more details.
156 *
157 * This function is used by both legacy CRTC helpers and atomic helpers.
158 * With atomic helpers it is optional.
159 *
160 * NOTE:
161 *
162 * This function is called in the check phase of atomic modesets, which
163 * can be aborted for any reason (including on userspace's request to
164 * just check whether a configuration would be possible). Atomic drivers
165 * MUST NOT touch any persistent state (hardware or software) or data
166 * structures except the passed in adjusted_mode parameter.
167 *
168 * This is in contrast to the legacy CRTC helpers where this was
169 * allowed.
170 *
171 * Atomic drivers which need to inspect and adjust more state should
172 * instead use the @atomic_check callback, but note that they're not
173 * perfectly equivalent: @mode_valid is called from
174 * drm_atomic_helper_check_modeset(), but @atomic_check is called from
175 * drm_atomic_helper_check_planes(), because originally it was meant for
176 * plane update checks only.
177 *
178 * Also beware that userspace can request its own custom modes, neither
179 * core nor helpers filter modes to the list of probe modes reported by
180 * the GETCONNECTOR IOCTL and stored in &drm_connector.modes. To ensure
181 * that modes are filtered consistently put any CRTC constraints and
182 * limits checks into @mode_valid.
183 *
184 * RETURNS:
185 *
186 * True if an acceptable configuration is possible, false if the modeset
187 * operation should be rejected.
188 */
189 bool (*mode_fixup)(struct drm_crtc *crtc,
190 const struct drm_display_mode *mode,
191 struct drm_display_mode *adjusted_mode);
192
193 /**
194 * @mode_set:
195 *
196 * This callback is used by the legacy CRTC helpers to set a new mode,
197 * position and framebuffer. Since it ties the primary plane to every
198 * mode change it is incompatible with universal plane support. And
199 * since it can't update other planes it's incompatible with atomic
200 * modeset support.
201 *
202 * This callback is only used by CRTC helpers and deprecated.
203 *
204 * RETURNS:
205 *
206 * 0 on success or a negative error code on failure.
207 */
208 int (*mode_set)(struct drm_crtc *crtc, struct drm_display_mode *mode,
209 struct drm_display_mode *adjusted_mode, int x, int y,
210 struct drm_framebuffer *old_fb);
211
212 /**
213 * @mode_set_nofb:
214 *
215 * This callback is used to update the display mode of a CRTC without
216 * changing anything of the primary plane configuration. This fits the
217 * requirement of atomic and hence is used by the atomic helpers. It is
218 * also used by the transitional plane helpers to implement a
219 * @mode_set hook in drm_helper_crtc_mode_set().
220 *
221 * Note that the display pipe is completely off when this function is
222 * called. Atomic drivers which need hardware to be running before they
223 * program the new display mode (e.g. because they implement runtime PM)
224 * should not use this hook. This is because the helper library calls
225 * this hook only once per mode change and not every time the display
226 * pipeline is suspended using either DPMS or the new "ACTIVE" property.
227 * Which means register values set in this callback might get reset when
228 * the CRTC is suspended, but not restored. Such drivers should instead
229 * move all their CRTC setup into the @atomic_enable callback.
230 *
231 * This callback is optional.
232 */
233 void (*mode_set_nofb)(struct drm_crtc *crtc);
234
235 /**
236 * @mode_set_base:
237 *
238 * This callback is used by the legacy CRTC helpers to set a new
239 * framebuffer and scanout position. It is optional and used as an
240 * optimized fast-path instead of a full mode set operation with all the
241 * resulting flickering. If it is not present
242 * drm_crtc_helper_set_config() will fall back to a full modeset, using
243 * the @mode_set callback. Since it can't update other planes it's
244 * incompatible with atomic modeset support.
245 *
246 * This callback is only used by the CRTC helpers and deprecated.
247 *
248 * RETURNS:
249 *
250 * 0 on success or a negative error code on failure.
251 */
252 int (*mode_set_base)(struct drm_crtc *crtc, int x, int y,
253 struct drm_framebuffer *old_fb);
254
255 /**
256 * @mode_set_base_atomic:
257 *
258 * This callback is used by the fbdev helpers to set a new framebuffer
259 * and scanout without sleeping, i.e. from an atomic calling context. It
260 * is only used to implement kgdb support.
261 *
262 * This callback is optional and only needed for kgdb support in the fbdev
263 * helpers.
264 *
265 * RETURNS:
266 *
267 * 0 on success or a negative error code on failure.
268 */
269 int (*mode_set_base_atomic)(struct drm_crtc *crtc,
270 struct drm_framebuffer *fb, int x, int y,
271 enum mode_set_atomic);
272
273 /**
274 * @disable:
275 *
276 * This callback should be used to disable the CRTC. With the atomic
277 * drivers it is called after all encoders connected to this CRTC have
278 * been shut off already using their own
279 * &drm_encoder_helper_funcs.disable hook. If that sequence is too
280 * simple drivers can just add their own hooks and call it from this
281 * CRTC callback here by looping over all encoders connected to it using
282 * for_each_encoder_on_crtc().
283 *
284 * This hook is used both by legacy CRTC helpers and atomic helpers.
285 * Atomic drivers don't need to implement it if there's no need to
286 * disable anything at the CRTC level. To ensure that runtime PM
287 * handling (using either DPMS or the new "ACTIVE" property) works
288 * @disable must be the inverse of @atomic_enable for atomic drivers.
289 * Atomic drivers should consider to use @atomic_disable instead of
290 * this one.
291 *
292 * NOTE:
293 *
294 * With legacy CRTC helpers there's a big semantic difference between
295 * @disable and other hooks (like @prepare or @dpms) used to shut down a
296 * CRTC: @disable is only called when also logically disabling the
297 * display pipeline and needs to release any resources acquired in
298 * @mode_set (like shared PLLs, or again release pinned framebuffers).
299 *
300 * Therefore @disable must be the inverse of @mode_set plus @commit for
301 * drivers still using legacy CRTC helpers, which is different from the
302 * rules under atomic.
303 */
304 void (*disable)(struct drm_crtc *crtc);
305
306 /**
307 * @atomic_check:
308 *
309 * Drivers should check plane-update related CRTC constraints in this
310 * hook. They can also check mode related limitations but need to be
311 * aware of the calling order, since this hook is used by
312 * drm_atomic_helper_check_planes() whereas the preparations needed to
313 * check output routing and the display mode is done in
314 * drm_atomic_helper_check_modeset(). Therefore drivers that want to
315 * check output routing and display mode constraints in this callback
316 * must ensure that drm_atomic_helper_check_modeset() has been called
317 * beforehand. This is calling order used by the default helper
318 * implementation in drm_atomic_helper_check().
319 *
320 * When using drm_atomic_helper_check_planes() this hook is called
321 * after the &drm_plane_helper_funcs.atomic_check hook for planes, which
322 * allows drivers to assign shared resources requested by planes in this
323 * callback here. For more complicated dependencies the driver can call
324 * the provided check helpers multiple times until the computed state
325 * has a final configuration and everything has been checked.
326 *
327 * This function is also allowed to inspect any other object's state and
328 * can add more state objects to the atomic commit if needed. Care must
329 * be taken though to ensure that state check and compute functions for
330 * these added states are all called, and derived state in other objects
331 * all updated. Again the recommendation is to just call check helpers
332 * until a maximal configuration is reached.
333 *
334 * This callback is used by the atomic modeset helpers and by the
335 * transitional plane helpers, but it is optional.
336 *
337 * NOTE:
338 *
339 * This function is called in the check phase of an atomic update. The
340 * driver is not allowed to change anything outside of the free-standing
341 * state objects passed-in or assembled in the overall &drm_atomic_state
342 * update tracking structure.
343 *
344 * Also beware that userspace can request its own custom modes, neither
345 * core nor helpers filter modes to the list of probe modes reported by
346 * the GETCONNECTOR IOCTL and stored in &drm_connector.modes. To ensure
347 * that modes are filtered consistently put any CRTC constraints and
348 * limits checks into @mode_valid.
349 *
350 * RETURNS:
351 *
352 * 0 on success, -EINVAL if the state or the transition can't be
353 * supported, -ENOMEM on memory allocation failure and -EDEADLK if an
354 * attempt to obtain another state object ran into a &drm_modeset_lock
355 * deadlock.
356 */
357 int (*atomic_check)(struct drm_crtc *crtc,
358 struct drm_crtc_state *state);
359
360 /**
361 * @atomic_begin:
362 *
363 * Drivers should prepare for an atomic update of multiple planes on
364 * a CRTC in this hook. Depending upon hardware this might be vblank
365 * evasion, blocking updates by setting bits or doing preparatory work
366 * for e.g. manual update display.
367 *
368 * This hook is called before any plane commit functions are called.
369 *
370 * Note that the power state of the display pipe when this function is
371 * called depends upon the exact helpers and calling sequence the driver
372 * has picked. See drm_atomic_helper_commit_planes() for a discussion of
373 * the tradeoffs and variants of plane commit helpers.
374 *
375 * This callback is used by the atomic modeset helpers and by the
376 * transitional plane helpers, but it is optional.
377 */
378 void (*atomic_begin)(struct drm_crtc *crtc,
379 struct drm_crtc_state *old_crtc_state);
380 /**
381 * @atomic_flush:
382 *
383 * Drivers should finalize an atomic update of multiple planes on
384 * a CRTC in this hook. Depending upon hardware this might include
385 * checking that vblank evasion was successful, unblocking updates by
386 * setting bits or setting the GO bit to flush out all updates.
387 *
388 * Simple hardware or hardware with special requirements can commit and
389 * flush out all updates for all planes from this hook and forgo all the
390 * other commit hooks for plane updates.
391 *
392 * This hook is called after any plane commit functions are called.
393 *
394 * Note that the power state of the display pipe when this function is
395 * called depends upon the exact helpers and calling sequence the driver
396 * has picked. See drm_atomic_helper_commit_planes() for a discussion of
397 * the tradeoffs and variants of plane commit helpers.
398 *
399 * This callback is used by the atomic modeset helpers and by the
400 * transitional plane helpers, but it is optional.
401 */
402 void (*atomic_flush)(struct drm_crtc *crtc,
403 struct drm_crtc_state *old_crtc_state);
404
405 /**
406 * @atomic_enable:
407 *
408 * This callback should be used to enable the CRTC. With the atomic
409 * drivers it is called before all encoders connected to this CRTC are
410 * enabled through the encoder's own &drm_encoder_helper_funcs.enable
411 * hook. If that sequence is too simple drivers can just add their own
412 * hooks and call it from this CRTC callback here by looping over all
413 * encoders connected to it using for_each_encoder_on_crtc().
414 *
415 * This hook is used only by atomic helpers, for symmetry with
416 * @atomic_disable. Atomic drivers don't need to implement it if there's
417 * no need to enable anything at the CRTC level. To ensure that runtime
418 * PM handling (using either DPMS or the new "ACTIVE" property) works
419 * @atomic_enable must be the inverse of @atomic_disable for atomic
420 * drivers.
421 *
422 * Drivers can use the @old_crtc_state input parameter if the operations
423 * needed to enable the CRTC don't depend solely on the new state but
424 * also on the transition between the old state and the new state.
425 *
426 * This function is optional.
427 */
428 void (*atomic_enable)(struct drm_crtc *crtc,
429 struct drm_crtc_state *old_crtc_state);
430
431 /**
432 * @atomic_disable:
433 *
434 * This callback should be used to disable the CRTC. With the atomic
435 * drivers it is called after all encoders connected to this CRTC have
436 * been shut off already using their own
437 * &drm_encoder_helper_funcs.disable hook. If that sequence is too
438 * simple drivers can just add their own hooks and call it from this
439 * CRTC callback here by looping over all encoders connected to it using
440 * for_each_encoder_on_crtc().
441 *
442 * This hook is used only by atomic helpers. Atomic drivers don't
443 * need to implement it if there's no need to disable anything at the
444 * CRTC level.
445 *
446 * Comparing to @disable, this one provides the additional input
447 * parameter @old_crtc_state which could be used to access the old
448 * state. Atomic drivers should consider to use this one instead
449 * of @disable.
450 *
451 * This function is optional.
452 */
453 void (*atomic_disable)(struct drm_crtc *crtc,
454 struct drm_crtc_state *old_crtc_state);
455 };
456
457 /**
458 * drm_crtc_helper_add - sets the helper vtable for a crtc
459 * @crtc: DRM CRTC
460 * @funcs: helper vtable to set for @crtc
461 */
drm_crtc_helper_add(struct drm_crtc * crtc,const struct drm_crtc_helper_funcs * funcs)462 static inline void drm_crtc_helper_add(struct drm_crtc *crtc,
463 const struct drm_crtc_helper_funcs *funcs)
464 {
465 crtc->helper_private = funcs;
466 }
467
468 /**
469 * struct drm_encoder_helper_funcs - helper operations for encoders
470 *
471 * These hooks are used by the legacy CRTC helpers, the transitional plane
472 * helpers and the new atomic modesetting helpers.
473 */
474 struct drm_encoder_helper_funcs {
475 /**
476 * @dpms:
477 *
478 * Callback to control power levels on the encoder. If the mode passed in
479 * is unsupported, the provider must use the next lowest power level.
480 * This is used by the legacy encoder helpers to implement DPMS
481 * functionality in drm_helper_connector_dpms().
482 *
483 * This callback is also used to disable an encoder by calling it with
484 * DRM_MODE_DPMS_OFF if the @disable hook isn't used.
485 *
486 * This callback is used by the legacy CRTC helpers. Atomic helpers
487 * also support using this hook for enabling and disabling an encoder to
488 * facilitate transitions to atomic, but it is deprecated. Instead
489 * @enable and @disable should be used.
490 */
491 void (*dpms)(struct drm_encoder *encoder, int mode);
492
493 /**
494 * @mode_valid:
495 *
496 * This callback is used to check if a specific mode is valid in this
497 * encoder. This should be implemented if the encoder has some sort
498 * of restriction in the modes it can display. For example, a given
499 * encoder may be responsible to set a clock value. If the clock can
500 * not produce all the values for the available modes then this callback
501 * can be used to restrict the number of modes to only the ones that
502 * can be displayed.
503 *
504 * This hook is used by the probe helpers to filter the mode list in
505 * drm_helper_probe_single_connector_modes(), and it is used by the
506 * atomic helpers to validate modes supplied by userspace in
507 * drm_atomic_helper_check_modeset().
508 *
509 * This function is optional.
510 *
511 * NOTE:
512 *
513 * Since this function is both called from the check phase of an atomic
514 * commit, and the mode validation in the probe paths it is not allowed
515 * to look at anything else but the passed-in mode, and validate it
516 * against configuration-invariant hardward constraints. Any further
517 * limits which depend upon the configuration can only be checked in
518 * @mode_fixup or @atomic_check.
519 *
520 * RETURNS:
521 *
522 * drm_mode_status Enum
523 */
524 enum drm_mode_status (*mode_valid)(struct drm_encoder *crtc,
525 const struct drm_display_mode *mode);
526
527 /**
528 * @mode_fixup:
529 *
530 * This callback is used to validate and adjust a mode. The parameter
531 * mode is the display mode that should be fed to the next element in
532 * the display chain, either the final &drm_connector or a &drm_bridge.
533 * The parameter adjusted_mode is the input mode the encoder requires. It
534 * can be modified by this callback and does not need to match mode. See
535 * also &drm_crtc_state.adjusted_mode for more details.
536 *
537 * This function is used by both legacy CRTC helpers and atomic helpers.
538 * This hook is optional.
539 *
540 * NOTE:
541 *
542 * This function is called in the check phase of atomic modesets, which
543 * can be aborted for any reason (including on userspace's request to
544 * just check whether a configuration would be possible). Atomic drivers
545 * MUST NOT touch any persistent state (hardware or software) or data
546 * structures except the passed in adjusted_mode parameter.
547 *
548 * This is in contrast to the legacy CRTC helpers where this was
549 * allowed.
550 *
551 * Atomic drivers which need to inspect and adjust more state should
552 * instead use the @atomic_check callback. If @atomic_check is used,
553 * this hook isn't called since @atomic_check allows a strict superset
554 * of the functionality of @mode_fixup.
555 *
556 * Also beware that userspace can request its own custom modes, neither
557 * core nor helpers filter modes to the list of probe modes reported by
558 * the GETCONNECTOR IOCTL and stored in &drm_connector.modes. To ensure
559 * that modes are filtered consistently put any encoder constraints and
560 * limits checks into @mode_valid.
561 *
562 * RETURNS:
563 *
564 * True if an acceptable configuration is possible, false if the modeset
565 * operation should be rejected.
566 */
567 bool (*mode_fixup)(struct drm_encoder *encoder,
568 const struct drm_display_mode *mode,
569 struct drm_display_mode *adjusted_mode);
570
571 /**
572 * @prepare:
573 *
574 * This callback should prepare the encoder for a subsequent modeset,
575 * which in practice means the driver should disable the encoder if it
576 * is running. Most drivers ended up implementing this by calling their
577 * @dpms hook with DRM_MODE_DPMS_OFF.
578 *
579 * This callback is used by the legacy CRTC helpers. Atomic helpers
580 * also support using this hook for disabling an encoder to facilitate
581 * transitions to atomic, but it is deprecated. Instead @disable should
582 * be used.
583 */
584 void (*prepare)(struct drm_encoder *encoder);
585
586 /**
587 * @commit:
588 *
589 * This callback should commit the new mode on the encoder after a modeset,
590 * which in practice means the driver should enable the encoder. Most
591 * drivers ended up implementing this by calling their @dpms hook with
592 * DRM_MODE_DPMS_ON.
593 *
594 * This callback is used by the legacy CRTC helpers. Atomic helpers
595 * also support using this hook for enabling an encoder to facilitate
596 * transitions to atomic, but it is deprecated. Instead @enable should
597 * be used.
598 */
599 void (*commit)(struct drm_encoder *encoder);
600
601 /**
602 * @mode_set:
603 *
604 * This callback is used to update the display mode of an encoder.
605 *
606 * Note that the display pipe is completely off when this function is
607 * called. Drivers which need hardware to be running before they program
608 * the new display mode (because they implement runtime PM) should not
609 * use this hook, because the helper library calls it only once and not
610 * every time the display pipeline is suspend using either DPMS or the
611 * new "ACTIVE" property. Such drivers should instead move all their
612 * encoder setup into the @enable callback.
613 *
614 * This callback is used both by the legacy CRTC helpers and the atomic
615 * modeset helpers. It is optional in the atomic helpers.
616 *
617 * NOTE:
618 *
619 * If the driver uses the atomic modeset helpers and needs to inspect
620 * the connector state or connector display info during mode setting,
621 * @atomic_mode_set can be used instead.
622 */
623 void (*mode_set)(struct drm_encoder *encoder,
624 struct drm_display_mode *mode,
625 struct drm_display_mode *adjusted_mode);
626
627 /**
628 * @atomic_mode_set:
629 *
630 * This callback is used to update the display mode of an encoder.
631 *
632 * Note that the display pipe is completely off when this function is
633 * called. Drivers which need hardware to be running before they program
634 * the new display mode (because they implement runtime PM) should not
635 * use this hook, because the helper library calls it only once and not
636 * every time the display pipeline is suspended using either DPMS or the
637 * new "ACTIVE" property. Such drivers should instead move all their
638 * encoder setup into the @enable callback.
639 *
640 * This callback is used by the atomic modeset helpers in place of the
641 * @mode_set callback, if set by the driver. It is optional and should
642 * be used instead of @mode_set if the driver needs to inspect the
643 * connector state or display info, since there is no direct way to
644 * go from the encoder to the current connector.
645 */
646 void (*atomic_mode_set)(struct drm_encoder *encoder,
647 struct drm_crtc_state *crtc_state,
648 struct drm_connector_state *conn_state);
649
650 /**
651 * @get_crtc:
652 *
653 * This callback is used by the legacy CRTC helpers to work around
654 * deficiencies in its own book-keeping.
655 *
656 * Do not use, use atomic helpers instead, which get the book keeping
657 * right.
658 *
659 * FIXME:
660 *
661 * Currently only nouveau is using this, and as soon as nouveau is
662 * atomic we can ditch this hook.
663 */
664 struct drm_crtc *(*get_crtc)(struct drm_encoder *encoder);
665
666 /**
667 * @detect:
668 *
669 * This callback can be used by drivers who want to do detection on the
670 * encoder object instead of in connector functions.
671 *
672 * It is not used by any helper and therefore has purely driver-specific
673 * semantics. New drivers shouldn't use this and instead just implement
674 * their own private callbacks.
675 *
676 * FIXME:
677 *
678 * This should just be converted into a pile of driver vfuncs.
679 * Currently radeon, amdgpu and nouveau are using it.
680 */
681 enum drm_connector_status (*detect)(struct drm_encoder *encoder,
682 struct drm_connector *connector);
683
684 /**
685 * @atomic_disable:
686 *
687 * This callback should be used to disable the encoder. With the atomic
688 * drivers it is called before this encoder's CRTC has been shut off
689 * using their own &drm_crtc_helper_funcs.atomic_disable hook. If that
690 * sequence is too simple drivers can just add their own driver private
691 * encoder hooks and call them from CRTC's callback by looping over all
692 * encoders connected to it using for_each_encoder_on_crtc().
693 *
694 * This callback is a variant of @disable that provides the atomic state
695 * to the driver. If @atomic_disable is implemented, @disable is not
696 * called by the helpers.
697 *
698 * This hook is only used by atomic helpers. Atomic drivers don't need
699 * to implement it if there's no need to disable anything at the encoder
700 * level. To ensure that runtime PM handling (using either DPMS or the
701 * new "ACTIVE" property) works @atomic_disable must be the inverse of
702 * @atomic_enable.
703 */
704 void (*atomic_disable)(struct drm_encoder *encoder,
705 struct drm_atomic_state *state);
706
707 /**
708 * @atomic_enable:
709 *
710 * This callback should be used to enable the encoder. It is called
711 * after this encoder's CRTC has been enabled using their own
712 * &drm_crtc_helper_funcs.atomic_enable hook. If that sequence is
713 * too simple drivers can just add their own driver private encoder
714 * hooks and call them from CRTC's callback by looping over all encoders
715 * connected to it using for_each_encoder_on_crtc().
716 *
717 * This callback is a variant of @enable that provides the atomic state
718 * to the driver. If @atomic_enable is implemented, @enable is not
719 * called by the helpers.
720 *
721 * This hook is only used by atomic helpers, it is the opposite of
722 * @atomic_disable. Atomic drivers don't need to implement it if there's
723 * no need to enable anything at the encoder level. To ensure that
724 * runtime PM handling works @atomic_enable must be the inverse of
725 * @atomic_disable.
726 */
727 void (*atomic_enable)(struct drm_encoder *encoder,
728 struct drm_atomic_state *state);
729
730 /**
731 * @disable:
732 *
733 * This callback should be used to disable the encoder. With the atomic
734 * drivers it is called before this encoder's CRTC has been shut off
735 * using their own &drm_crtc_helper_funcs.disable hook. If that
736 * sequence is too simple drivers can just add their own driver private
737 * encoder hooks and call them from CRTC's callback by looping over all
738 * encoders connected to it using for_each_encoder_on_crtc().
739 *
740 * This hook is used both by legacy CRTC helpers and atomic helpers.
741 * Atomic drivers don't need to implement it if there's no need to
742 * disable anything at the encoder level. To ensure that runtime PM
743 * handling (using either DPMS or the new "ACTIVE" property) works
744 * @disable must be the inverse of @enable for atomic drivers.
745 *
746 * For atomic drivers also consider @atomic_disable and save yourself
747 * from having to read the NOTE below!
748 *
749 * NOTE:
750 *
751 * With legacy CRTC helpers there's a big semantic difference between
752 * @disable and other hooks (like @prepare or @dpms) used to shut down a
753 * encoder: @disable is only called when also logically disabling the
754 * display pipeline and needs to release any resources acquired in
755 * @mode_set (like shared PLLs, or again release pinned framebuffers).
756 *
757 * Therefore @disable must be the inverse of @mode_set plus @commit for
758 * drivers still using legacy CRTC helpers, which is different from the
759 * rules under atomic.
760 */
761 void (*disable)(struct drm_encoder *encoder);
762
763 /**
764 * @enable:
765 *
766 * This callback should be used to enable the encoder. With the atomic
767 * drivers it is called after this encoder's CRTC has been enabled using
768 * their own &drm_crtc_helper_funcs.enable hook. If that sequence is
769 * too simple drivers can just add their own driver private encoder
770 * hooks and call them from CRTC's callback by looping over all encoders
771 * connected to it using for_each_encoder_on_crtc().
772 *
773 * This hook is only used by atomic helpers, it is the opposite of
774 * @disable. Atomic drivers don't need to implement it if there's no
775 * need to enable anything at the encoder level. To ensure that
776 * runtime PM handling (using either DPMS or the new "ACTIVE" property)
777 * works @enable must be the inverse of @disable for atomic drivers.
778 */
779 void (*enable)(struct drm_encoder *encoder);
780
781 /**
782 * @atomic_check:
783 *
784 * This callback is used to validate encoder state for atomic drivers.
785 * Since the encoder is the object connecting the CRTC and connector it
786 * gets passed both states, to be able to validate interactions and
787 * update the CRTC to match what the encoder needs for the requested
788 * connector.
789 *
790 * Since this provides a strict superset of the functionality of
791 * @mode_fixup (the requested and adjusted modes are both available
792 * through the passed in &struct drm_crtc_state) @mode_fixup is not
793 * called when @atomic_check is implemented.
794 *
795 * This function is used by the atomic helpers, but it is optional.
796 *
797 * NOTE:
798 *
799 * This function is called in the check phase of an atomic update. The
800 * driver is not allowed to change anything outside of the free-standing
801 * state objects passed-in or assembled in the overall &drm_atomic_state
802 * update tracking structure.
803 *
804 * Also beware that userspace can request its own custom modes, neither
805 * core nor helpers filter modes to the list of probe modes reported by
806 * the GETCONNECTOR IOCTL and stored in &drm_connector.modes. To ensure
807 * that modes are filtered consistently put any encoder constraints and
808 * limits checks into @mode_valid.
809 *
810 * RETURNS:
811 *
812 * 0 on success, -EINVAL if the state or the transition can't be
813 * supported, -ENOMEM on memory allocation failure and -EDEADLK if an
814 * attempt to obtain another state object ran into a &drm_modeset_lock
815 * deadlock.
816 */
817 int (*atomic_check)(struct drm_encoder *encoder,
818 struct drm_crtc_state *crtc_state,
819 struct drm_connector_state *conn_state);
820 };
821
822 /**
823 * drm_encoder_helper_add - sets the helper vtable for an encoder
824 * @encoder: DRM encoder
825 * @funcs: helper vtable to set for @encoder
826 */
drm_encoder_helper_add(struct drm_encoder * encoder,const struct drm_encoder_helper_funcs * funcs)827 static inline void drm_encoder_helper_add(struct drm_encoder *encoder,
828 const struct drm_encoder_helper_funcs *funcs)
829 {
830 encoder->helper_private = funcs;
831 }
832
833 /**
834 * struct drm_connector_helper_funcs - helper operations for connectors
835 *
836 * These functions are used by the atomic and legacy modeset helpers and by the
837 * probe helpers.
838 */
839 struct drm_connector_helper_funcs {
840 /**
841 * @get_modes:
842 *
843 * This function should fill in all modes currently valid for the sink
844 * into the &drm_connector.probed_modes list. It should also update the
845 * EDID property by calling drm_connector_update_edid_property().
846 *
847 * The usual way to implement this is to cache the EDID retrieved in the
848 * probe callback somewhere in the driver-private connector structure.
849 * In this function drivers then parse the modes in the EDID and add
850 * them by calling drm_add_edid_modes(). But connectors that driver a
851 * fixed panel can also manually add specific modes using
852 * drm_mode_probed_add(). Drivers which manually add modes should also
853 * make sure that the &drm_connector.display_info,
854 * &drm_connector.width_mm and &drm_connector.height_mm fields are
855 * filled in.
856 *
857 * Virtual drivers that just want some standard VESA mode with a given
858 * resolution can call drm_add_modes_noedid(), and mark the preferred
859 * one using drm_set_preferred_mode().
860 *
861 * This function is only called after the @detect hook has indicated
862 * that a sink is connected and when the EDID isn't overridden through
863 * sysfs or the kernel commandline.
864 *
865 * This callback is used by the probe helpers in e.g.
866 * drm_helper_probe_single_connector_modes().
867 *
868 * To avoid races with concurrent connector state updates, the helper
869 * libraries always call this with the &drm_mode_config.connection_mutex
870 * held. Because of this it's safe to inspect &drm_connector->state.
871 *
872 * RETURNS:
873 *
874 * The number of modes added by calling drm_mode_probed_add().
875 */
876 int (*get_modes)(struct drm_connector *connector);
877
878 /**
879 * @detect_ctx:
880 *
881 * Check to see if anything is attached to the connector. The parameter
882 * force is set to false whilst polling, true when checking the
883 * connector due to a user request. force can be used by the driver to
884 * avoid expensive, destructive operations during automated probing.
885 *
886 * This callback is optional, if not implemented the connector will be
887 * considered as always being attached.
888 *
889 * This is the atomic version of &drm_connector_funcs.detect.
890 *
891 * To avoid races against concurrent connector state updates, the
892 * helper libraries always call this with ctx set to a valid context,
893 * and &drm_mode_config.connection_mutex will always be locked with
894 * the ctx parameter set to this ctx. This allows taking additional
895 * locks as required.
896 *
897 * RETURNS:
898 *
899 * &drm_connector_status indicating the connector's status,
900 * or the error code returned by drm_modeset_lock(), -EDEADLK.
901 */
902 int (*detect_ctx)(struct drm_connector *connector,
903 struct drm_modeset_acquire_ctx *ctx,
904 bool force);
905
906 /**
907 * @mode_valid:
908 *
909 * Callback to validate a mode for a connector, irrespective of the
910 * specific display configuration.
911 *
912 * This callback is used by the probe helpers to filter the mode list
913 * (which is usually derived from the EDID data block from the sink).
914 * See e.g. drm_helper_probe_single_connector_modes().
915 *
916 * This function is optional.
917 *
918 * NOTE:
919 *
920 * This only filters the mode list supplied to userspace in the
921 * GETCONNECTOR IOCTL. Compared to &drm_encoder_helper_funcs.mode_valid,
922 * &drm_crtc_helper_funcs.mode_valid and &drm_bridge_funcs.mode_valid,
923 * which are also called by the atomic helpers from
924 * drm_atomic_helper_check_modeset(). This allows userspace to force and
925 * ignore sink constraint (like the pixel clock limits in the screen's
926 * EDID), which is useful for e.g. testing, or working around a broken
927 * EDID. Any source hardware constraint (which always need to be
928 * enforced) therefore should be checked in one of the above callbacks,
929 * and not this one here.
930 *
931 * To avoid races with concurrent connector state updates, the helper
932 * libraries always call this with the &drm_mode_config.connection_mutex
933 * held. Because of this it's safe to inspect &drm_connector->state.
934 *
935 * RETURNS:
936 *
937 * Either &drm_mode_status.MODE_OK or one of the failure reasons in &enum
938 * drm_mode_status.
939 */
940 enum drm_mode_status (*mode_valid)(struct drm_connector *connector,
941 struct drm_display_mode *mode);
942 /**
943 * @best_encoder:
944 *
945 * This function should select the best encoder for the given connector.
946 *
947 * This function is used by both the atomic helpers (in the
948 * drm_atomic_helper_check_modeset() function) and in the legacy CRTC
949 * helpers.
950 *
951 * NOTE:
952 *
953 * In atomic drivers this function is called in the check phase of an
954 * atomic update. The driver is not allowed to change or inspect
955 * anything outside of arguments passed-in. Atomic drivers which need to
956 * inspect dynamic configuration state should instead use
957 * @atomic_best_encoder.
958 *
959 * You can leave this function to NULL if the connector is only
960 * attached to a single encoder. In this case, the core will call
961 * drm_connector_get_single_encoder() for you.
962 *
963 * RETURNS:
964 *
965 * Encoder that should be used for the given connector and connector
966 * state, or NULL if no suitable encoder exists. Note that the helpers
967 * will ensure that encoders aren't used twice, drivers should not check
968 * for this.
969 */
970 struct drm_encoder *(*best_encoder)(struct drm_connector *connector);
971
972 /**
973 * @atomic_best_encoder:
974 *
975 * This is the atomic version of @best_encoder for atomic drivers which
976 * need to select the best encoder depending upon the desired
977 * configuration and can't select it statically.
978 *
979 * This function is used by drm_atomic_helper_check_modeset().
980 * If it is not implemented, the core will fallback to @best_encoder
981 * (or drm_connector_get_single_encoder() if @best_encoder is NULL).
982 *
983 * NOTE:
984 *
985 * This function is called in the check phase of an atomic update. The
986 * driver is not allowed to change anything outside of the free-standing
987 * state objects passed-in or assembled in the overall &drm_atomic_state
988 * update tracking structure.
989 *
990 * RETURNS:
991 *
992 * Encoder that should be used for the given connector and connector
993 * state, or NULL if no suitable encoder exists. Note that the helpers
994 * will ensure that encoders aren't used twice, drivers should not check
995 * for this.
996 */
997 struct drm_encoder *(*atomic_best_encoder)(struct drm_connector *connector,
998 struct drm_connector_state *connector_state);
999
1000 /**
1001 * @atomic_check:
1002 *
1003 * This hook is used to validate connector state. This function is
1004 * called from &drm_atomic_helper_check_modeset, and is called when
1005 * a connector property is set, or a modeset on the crtc is forced.
1006 *
1007 * Because &drm_atomic_helper_check_modeset may be called multiple times,
1008 * this function should handle being called multiple times as well.
1009 *
1010 * This function is also allowed to inspect any other object's state and
1011 * can add more state objects to the atomic commit if needed. Care must
1012 * be taken though to ensure that state check and compute functions for
1013 * these added states are all called, and derived state in other objects
1014 * all updated. Again the recommendation is to just call check helpers
1015 * until a maximal configuration is reached.
1016 *
1017 * NOTE:
1018 *
1019 * This function is called in the check phase of an atomic update. The
1020 * driver is not allowed to change anything outside of the free-standing
1021 * state objects passed-in or assembled in the overall &drm_atomic_state
1022 * update tracking structure.
1023 *
1024 * RETURNS:
1025 *
1026 * 0 on success, -EINVAL if the state or the transition can't be
1027 * supported, -ENOMEM on memory allocation failure and -EDEADLK if an
1028 * attempt to obtain another state object ran into a &drm_modeset_lock
1029 * deadlock.
1030 */
1031 int (*atomic_check)(struct drm_connector *connector,
1032 struct drm_atomic_state *state);
1033
1034 /**
1035 * @atomic_commit:
1036 *
1037 * This hook is to be used by drivers implementing writeback connectors
1038 * that need a point when to commit the writeback job to the hardware.
1039 * The writeback_job to commit is available in
1040 * &drm_connector_state.writeback_job.
1041 *
1042 * This hook is optional.
1043 *
1044 * This callback is used by the atomic modeset helpers.
1045 */
1046 void (*atomic_commit)(struct drm_connector *connector,
1047 struct drm_connector_state *state);
1048
1049 int (*prepare_writeback_job)(struct drm_writeback_connector *connector,
1050 struct drm_writeback_job *job);
1051 void (*cleanup_writeback_job)(struct drm_writeback_connector *connector,
1052 struct drm_writeback_job *job);
1053 };
1054
1055 /**
1056 * drm_connector_helper_add - sets the helper vtable for a connector
1057 * @connector: DRM connector
1058 * @funcs: helper vtable to set for @connector
1059 */
drm_connector_helper_add(struct drm_connector * connector,const struct drm_connector_helper_funcs * funcs)1060 static inline void drm_connector_helper_add(struct drm_connector *connector,
1061 const struct drm_connector_helper_funcs *funcs)
1062 {
1063 connector->helper_private = funcs;
1064 }
1065
1066 /**
1067 * struct drm_plane_helper_funcs - helper operations for planes
1068 *
1069 * These functions are used by the atomic helpers and by the transitional plane
1070 * helpers.
1071 */
1072 struct drm_plane_helper_funcs {
1073 /**
1074 * @prepare_fb:
1075 *
1076 * This hook is to prepare a framebuffer for scanout by e.g. pinning
1077 * its backing storage or relocating it into a contiguous block of
1078 * VRAM. Other possible preparatory work includes flushing caches.
1079 *
1080 * This function must not block for outstanding rendering, since it is
1081 * called in the context of the atomic IOCTL even for async commits to
1082 * be able to return any errors to userspace. Instead the recommended
1083 * way is to fill out the &drm_plane_state.fence of the passed-in
1084 * &drm_plane_state. If the driver doesn't support native fences then
1085 * equivalent functionality should be implemented through private
1086 * members in the plane structure.
1087 *
1088 * Drivers which always have their buffers pinned should use
1089 * drm_gem_fb_prepare_fb() for this hook.
1090 *
1091 * The helpers will call @cleanup_fb with matching arguments for every
1092 * successful call to this hook.
1093 *
1094 * This callback is used by the atomic modeset helpers and by the
1095 * transitional plane helpers, but it is optional.
1096 *
1097 * RETURNS:
1098 *
1099 * 0 on success or one of the following negative error codes allowed by
1100 * the &drm_mode_config_funcs.atomic_commit vfunc. When using helpers
1101 * this callback is the only one which can fail an atomic commit,
1102 * everything else must complete successfully.
1103 */
1104 int (*prepare_fb)(struct drm_plane *plane,
1105 struct drm_plane_state *new_state);
1106 /**
1107 * @cleanup_fb:
1108 *
1109 * This hook is called to clean up any resources allocated for the given
1110 * framebuffer and plane configuration in @prepare_fb.
1111 *
1112 * This callback is used by the atomic modeset helpers and by the
1113 * transitional plane helpers, but it is optional.
1114 */
1115 void (*cleanup_fb)(struct drm_plane *plane,
1116 struct drm_plane_state *old_state);
1117
1118 /**
1119 * @atomic_check:
1120 *
1121 * Drivers should check plane specific constraints in this hook.
1122 *
1123 * When using drm_atomic_helper_check_planes() plane's @atomic_check
1124 * hooks are called before the ones for CRTCs, which allows drivers to
1125 * request shared resources that the CRTC controls here. For more
1126 * complicated dependencies the driver can call the provided check helpers
1127 * multiple times until the computed state has a final configuration and
1128 * everything has been checked.
1129 *
1130 * This function is also allowed to inspect any other object's state and
1131 * can add more state objects to the atomic commit if needed. Care must
1132 * be taken though to ensure that state check and compute functions for
1133 * these added states are all called, and derived state in other objects
1134 * all updated. Again the recommendation is to just call check helpers
1135 * until a maximal configuration is reached.
1136 *
1137 * This callback is used by the atomic modeset helpers and by the
1138 * transitional plane helpers, but it is optional.
1139 *
1140 * NOTE:
1141 *
1142 * This function is called in the check phase of an atomic update. The
1143 * driver is not allowed to change anything outside of the free-standing
1144 * state objects passed-in or assembled in the overall &drm_atomic_state
1145 * update tracking structure.
1146 *
1147 * RETURNS:
1148 *
1149 * 0 on success, -EINVAL if the state or the transition can't be
1150 * supported, -ENOMEM on memory allocation failure and -EDEADLK if an
1151 * attempt to obtain another state object ran into a &drm_modeset_lock
1152 * deadlock.
1153 */
1154 int (*atomic_check)(struct drm_plane *plane,
1155 struct drm_plane_state *state);
1156
1157 /**
1158 * @atomic_update:
1159 *
1160 * Drivers should use this function to update the plane state. This
1161 * hook is called in-between the &drm_crtc_helper_funcs.atomic_begin and
1162 * drm_crtc_helper_funcs.atomic_flush callbacks.
1163 *
1164 * Note that the power state of the display pipe when this function is
1165 * called depends upon the exact helpers and calling sequence the driver
1166 * has picked. See drm_atomic_helper_commit_planes() for a discussion of
1167 * the tradeoffs and variants of plane commit helpers.
1168 *
1169 * This callback is used by the atomic modeset helpers and by the
1170 * transitional plane helpers, but it is optional.
1171 */
1172 void (*atomic_update)(struct drm_plane *plane,
1173 struct drm_plane_state *old_state);
1174 /**
1175 * @atomic_disable:
1176 *
1177 * Drivers should use this function to unconditionally disable a plane.
1178 * This hook is called in-between the
1179 * &drm_crtc_helper_funcs.atomic_begin and
1180 * drm_crtc_helper_funcs.atomic_flush callbacks. It is an alternative to
1181 * @atomic_update, which will be called for disabling planes, too, if
1182 * the @atomic_disable hook isn't implemented.
1183 *
1184 * This hook is also useful to disable planes in preparation of a modeset,
1185 * by calling drm_atomic_helper_disable_planes_on_crtc() from the
1186 * &drm_crtc_helper_funcs.disable hook.
1187 *
1188 * Note that the power state of the display pipe when this function is
1189 * called depends upon the exact helpers and calling sequence the driver
1190 * has picked. See drm_atomic_helper_commit_planes() for a discussion of
1191 * the tradeoffs and variants of plane commit helpers.
1192 *
1193 * This callback is used by the atomic modeset helpers and by the
1194 * transitional plane helpers, but it is optional.
1195 */
1196 void (*atomic_disable)(struct drm_plane *plane,
1197 struct drm_plane_state *old_state);
1198
1199 /**
1200 * @atomic_async_check:
1201 *
1202 * Drivers should set this function pointer to check if the plane state
1203 * can be updated in a async fashion. Here async means "not vblank
1204 * synchronized".
1205 *
1206 * This hook is called by drm_atomic_async_check() to establish if a
1207 * given update can be committed asynchronously, that is, if it can
1208 * jump ahead of the state currently queued for update.
1209 *
1210 * RETURNS:
1211 *
1212 * Return 0 on success and any error returned indicates that the update
1213 * can not be applied in asynchronous manner.
1214 */
1215 int (*atomic_async_check)(struct drm_plane *plane,
1216 struct drm_plane_state *state);
1217
1218 /**
1219 * @atomic_async_update:
1220 *
1221 * Drivers should set this function pointer to perform asynchronous
1222 * updates of planes, that is, jump ahead of the currently queued
1223 * state and update the plane. Here async means "not vblank
1224 * synchronized".
1225 *
1226 * This hook is called by drm_atomic_helper_async_commit().
1227 *
1228 * An async update will happen on legacy cursor updates. An async
1229 * update won't happen if there is an outstanding commit modifying
1230 * the same plane.
1231 *
1232 * Note that unlike &drm_plane_helper_funcs.atomic_update this hook
1233 * takes the new &drm_plane_state as parameter. When doing async_update
1234 * drivers shouldn't replace the &drm_plane_state but update the
1235 * current one with the new plane configurations in the new
1236 * plane_state.
1237 *
1238 * Drivers should also swap the framebuffers between current plane
1239 * state (&drm_plane.state) and new_state.
1240 * This is required since cleanup for async commits is performed on
1241 * the new state, rather than old state like for traditional commits.
1242 * Since we want to give up the reference on the current (old) fb
1243 * instead of our brand new one, swap them in the driver during the
1244 * async commit.
1245 *
1246 * FIXME:
1247 * - It only works for single plane updates
1248 * - Async Pageflips are not supported yet
1249 * - Some hw might still scan out the old buffer until the next
1250 * vblank, however we let go of the fb references as soon as
1251 * we run this hook. For now drivers must implement their own workers
1252 * for deferring if needed, until a common solution is created.
1253 */
1254 void (*atomic_async_update)(struct drm_plane *plane,
1255 struct drm_plane_state *new_state);
1256 };
1257
1258 /**
1259 * drm_plane_helper_add - sets the helper vtable for a plane
1260 * @plane: DRM plane
1261 * @funcs: helper vtable to set for @plane
1262 */
drm_plane_helper_add(struct drm_plane * plane,const struct drm_plane_helper_funcs * funcs)1263 static inline void drm_plane_helper_add(struct drm_plane *plane,
1264 const struct drm_plane_helper_funcs *funcs)
1265 {
1266 plane->helper_private = funcs;
1267 }
1268
1269 /**
1270 * struct drm_mode_config_helper_funcs - global modeset helper operations
1271 *
1272 * These helper functions are used by the atomic helpers.
1273 */
1274 struct drm_mode_config_helper_funcs {
1275 /**
1276 * @atomic_commit_tail:
1277 *
1278 * This hook is used by the default atomic_commit() hook implemented in
1279 * drm_atomic_helper_commit() together with the nonblocking commit
1280 * helpers (see drm_atomic_helper_setup_commit() for a starting point)
1281 * to implement blocking and nonblocking commits easily. It is not used
1282 * by the atomic helpers
1283 *
1284 * This function is called when the new atomic state has already been
1285 * swapped into the various state pointers. The passed in state
1286 * therefore contains copies of the old/previous state. This hook should
1287 * commit the new state into hardware. Note that the helpers have
1288 * already waited for preceeding atomic commits and fences, but drivers
1289 * can add more waiting calls at the start of their implementation, e.g.
1290 * to wait for driver-internal request for implicit syncing, before
1291 * starting to commit the update to the hardware.
1292 *
1293 * After the atomic update is committed to the hardware this hook needs
1294 * to call drm_atomic_helper_commit_hw_done(). Then wait for the upate
1295 * to be executed by the hardware, for example using
1296 * drm_atomic_helper_wait_for_vblanks() or
1297 * drm_atomic_helper_wait_for_flip_done(), and then clean up the old
1298 * framebuffers using drm_atomic_helper_cleanup_planes().
1299 *
1300 * When disabling a CRTC this hook _must_ stall for the commit to
1301 * complete. Vblank waits don't work on disabled CRTC, hence the core
1302 * can't take care of this. And it also can't rely on the vblank event,
1303 * since that can be signalled already when the screen shows black,
1304 * which can happen much earlier than the last hardware access needed to
1305 * shut off the display pipeline completely.
1306 *
1307 * This hook is optional, the default implementation is
1308 * drm_atomic_helper_commit_tail().
1309 */
1310 void (*atomic_commit_tail)(struct drm_atomic_state *state);
1311 };
1312
1313 #endif
1314