blob: c01c328f6cc80c1945b9f8355d89fd314bfb424a [file] [log] [blame]
Daniel Vetter092d01d2015-12-04 09:45:44 +01001/*
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>
Laurent Pinchart93382032016-11-28 20:51:09 +020033#include <drm/drm_encoder.h>
Daniel Vetter092d01d2015-12-04 09:45:44 +010034
35/**
36 * DOC: overview
37 *
38 * The DRM mode setting helper functions are common code for drivers to use if
39 * they wish. Drivers are not forced to use this code in their
40 * implementations but it would be useful if the code they do use at least
41 * provides a consistent interface and operation to userspace. Therefore it is
42 * highly recommended to use the provided helpers as much as possible.
43 *
44 * Because there is only one pointer per modeset object to hold a vfunc table
45 * for helper libraries they are by necessity shared among the different
46 * helpers.
47 *
48 * To make this clear all the helper vtables are pulled together in this location here.
49 */
50
51enum mode_set_atomic;
52
53/**
54 * struct drm_crtc_helper_funcs - helper operations for CRTCs
Daniel Vetter092d01d2015-12-04 09:45:44 +010055 *
Daniel Vetter36b66082015-12-04 09:46:08 +010056 * These hooks are used by the legacy CRTC helpers, the transitional plane
57 * helpers and the new atomic modesetting helpers.
Daniel Vetter092d01d2015-12-04 09:45:44 +010058 */
59struct drm_crtc_helper_funcs {
Daniel Vetter36b66082015-12-04 09:46:08 +010060 /**
61 * @dpms:
62 *
63 * Callback to control power levels on the CRTC. If the mode passed in
64 * is unsupported, the provider must use the next lowest power level.
65 * This is used by the legacy CRTC helpers to implement DPMS
66 * functionality in drm_helper_connector_dpms().
67 *
68 * This callback is also used to disable a CRTC by calling it with
69 * DRM_MODE_DPMS_OFF if the @disable hook isn't used.
70 *
71 * This callback is used by the legacy CRTC helpers. Atomic helpers
72 * also support using this hook for enabling and disabling a CRTC to
73 * facilitate transitions to atomic, but it is deprecated. Instead
74 * @enable and @disable should be used.
Daniel Vetter092d01d2015-12-04 09:45:44 +010075 */
76 void (*dpms)(struct drm_crtc *crtc, int mode);
Daniel Vetter36b66082015-12-04 09:46:08 +010077
78 /**
79 * @prepare:
80 *
81 * This callback should prepare the CRTC for a subsequent modeset, which
82 * in practice means the driver should disable the CRTC if it is
83 * running. Most drivers ended up implementing this by calling their
84 * @dpms hook with DRM_MODE_DPMS_OFF.
85 *
86 * This callback is used by the legacy CRTC helpers. Atomic helpers
87 * also support using this hook for disabling a CRTC to facilitate
88 * transitions to atomic, but it is deprecated. Instead @disable should
89 * be used.
90 */
Daniel Vetter092d01d2015-12-04 09:45:44 +010091 void (*prepare)(struct drm_crtc *crtc);
Daniel Vetter36b66082015-12-04 09:46:08 +010092
93 /**
94 * @commit:
95 *
96 * This callback should commit the new mode on the CRTC after a modeset,
97 * which in practice means the driver should enable the CRTC. Most
98 * drivers ended up implementing this by calling their @dpms hook with
99 * DRM_MODE_DPMS_ON.
100 *
101 * This callback is used by the legacy CRTC helpers. Atomic helpers
102 * also support using this hook for enabling a CRTC to facilitate
103 * transitions to atomic, but it is deprecated. Instead @enable should
104 * be used.
105 */
Daniel Vetter092d01d2015-12-04 09:45:44 +0100106 void (*commit)(struct drm_crtc *crtc);
107
Daniel Vetter36b66082015-12-04 09:46:08 +0100108 /**
109 * @mode_fixup:
110 *
111 * This callback is used to validate a mode. The parameter mode is the
112 * display mode that userspace requested, adjusted_mode is the mode the
113 * encoders need to be fed with. Note that this is the inverse semantics
Daniel Vetter6806cdf2017-01-25 07:26:43 +0100114 * of the meaning for the &drm_encoder and &drm_bridge_funcs.mode_fixup
115 * vfunc. If the CRTC cannot support the requested conversion from mode
116 * to adjusted_mode it should reject the modeset.
Daniel Vetter36b66082015-12-04 09:46:08 +0100117 *
118 * This function is used by both legacy CRTC helpers and atomic helpers.
119 * With atomic helpers it is optional.
120 *
121 * NOTE:
122 *
123 * This function is called in the check phase of atomic modesets, which
124 * can be aborted for any reason (including on userspace's request to
125 * just check whether a configuration would be possible). Atomic drivers
126 * MUST NOT touch any persistent state (hardware or software) or data
127 * structures except the passed in adjusted_mode parameter.
128 *
129 * This is in contrast to the legacy CRTC helpers where this was
130 * allowed.
131 *
132 * Atomic drivers which need to inspect and adjust more state should
133 * instead use the @atomic_check callback.
134 *
Daniel Vetterdf7d6782016-01-04 07:53:36 +0100135 * Also beware that neither core nor helpers filter modes before
136 * passing them to the driver: While the list of modes that is
Daniel Vetter6806cdf2017-01-25 07:26:43 +0100137 * advertised to userspace is filtered using the
138 * &drm_connector.mode_valid callback, neither the core nor the helpers
139 * do any filtering on modes passed in from userspace when setting a
140 * mode. It is therefore possible for userspace to pass in a mode that
141 * was previously filtered out using &drm_connector.mode_valid or add a
142 * custom mode that wasn't probed from EDID or similar to begin with.
143 * Even though this is an advanced feature and rarely used nowadays,
144 * some users rely on being able to specify modes manually so drivers
145 * must be prepared to deal with it. Specifically this means that all
146 * drivers need not only validate modes in &drm_connector.mode_valid but
147 * also in this or in the &drm_encoder_helper_funcs.mode_fixup callback
148 * to make sure invalid modes passed in from userspace are rejected.
Daniel Vetterdf7d6782016-01-04 07:53:36 +0100149 *
Daniel Vetter36b66082015-12-04 09:46:08 +0100150 * RETURNS:
151 *
152 * True if an acceptable configuration is possible, false if the modeset
153 * operation should be rejected.
154 */
Daniel Vetter092d01d2015-12-04 09:45:44 +0100155 bool (*mode_fixup)(struct drm_crtc *crtc,
156 const struct drm_display_mode *mode,
157 struct drm_display_mode *adjusted_mode);
Daniel Vetter36b66082015-12-04 09:46:08 +0100158
159 /**
160 * @mode_set:
161 *
162 * This callback is used by the legacy CRTC helpers to set a new mode,
163 * position and framebuffer. Since it ties the primary plane to every
164 * mode change it is incompatible with universal plane support. And
165 * since it can't update other planes it's incompatible with atomic
166 * modeset support.
167 *
168 * This callback is only used by CRTC helpers and deprecated.
169 *
170 * RETURNS:
171 *
172 * 0 on success or a negative error code on failure.
173 */
Daniel Vetter092d01d2015-12-04 09:45:44 +0100174 int (*mode_set)(struct drm_crtc *crtc, struct drm_display_mode *mode,
175 struct drm_display_mode *adjusted_mode, int x, int y,
176 struct drm_framebuffer *old_fb);
Daniel Vetter36b66082015-12-04 09:46:08 +0100177
178 /**
179 * @mode_set_nofb:
180 *
181 * This callback is used to update the display mode of a CRTC without
182 * changing anything of the primary plane configuration. This fits the
183 * requirement of atomic and hence is used by the atomic helpers. It is
184 * also used by the transitional plane helpers to implement a
185 * @mode_set hook in drm_helper_crtc_mode_set().
186 *
187 * Note that the display pipe is completely off when this function is
188 * called. Atomic drivers which need hardware to be running before they
189 * program the new display mode (e.g. because they implement runtime PM)
190 * should not use this hook. This is because the helper library calls
191 * this hook only once per mode change and not every time the display
192 * pipeline is suspended using either DPMS or the new "ACTIVE" property.
193 * Which means register values set in this callback might get reset when
194 * the CRTC is suspended, but not restored. Such drivers should instead
195 * move all their CRTC setup into the @enable callback.
196 *
197 * This callback is optional.
198 */
Daniel Vetter092d01d2015-12-04 09:45:44 +0100199 void (*mode_set_nofb)(struct drm_crtc *crtc);
200
Daniel Vetter36b66082015-12-04 09:46:08 +0100201 /**
202 * @mode_set_base:
203 *
204 * This callback is used by the legacy CRTC helpers to set a new
205 * framebuffer and scanout position. It is optional and used as an
206 * optimized fast-path instead of a full mode set operation with all the
Daniel Vetterdf7d6782016-01-04 07:53:36 +0100207 * resulting flickering. If it is not present
208 * drm_crtc_helper_set_config() will fall back to a full modeset, using
Daniel Vetter6806cdf2017-01-25 07:26:43 +0100209 * the @mode_set callback. Since it can't update other planes it's
Daniel Vetter36b66082015-12-04 09:46:08 +0100210 * incompatible with atomic modeset support.
211 *
212 * This callback is only used by the CRTC helpers and deprecated.
213 *
214 * RETURNS:
215 *
216 * 0 on success or a negative error code on failure.
217 */
Daniel Vetter092d01d2015-12-04 09:45:44 +0100218 int (*mode_set_base)(struct drm_crtc *crtc, int x, int y,
219 struct drm_framebuffer *old_fb);
Daniel Vetter36b66082015-12-04 09:46:08 +0100220
221 /**
222 * @mode_set_base_atomic:
223 *
224 * This callback is used by the fbdev helpers to set a new framebuffer
225 * and scanout without sleeping, i.e. from an atomic calling context. It
226 * is only used to implement kgdb support.
227 *
228 * This callback is optional and only needed for kgdb support in the fbdev
229 * helpers.
230 *
231 * RETURNS:
232 *
233 * 0 on success or a negative error code on failure.
234 */
Daniel Vetter092d01d2015-12-04 09:45:44 +0100235 int (*mode_set_base_atomic)(struct drm_crtc *crtc,
236 struct drm_framebuffer *fb, int x, int y,
237 enum mode_set_atomic);
238
Daniel Vetter36b66082015-12-04 09:46:08 +0100239 /**
240 * @load_lut:
241 *
Daniel Vetter6806cdf2017-01-25 07:26:43 +0100242 * Load a LUT prepared with the &drm_fb_helper_funcs.gamma_set vfunc.
Daniel Vetter36b66082015-12-04 09:46:08 +0100243 *
244 * This callback is optional and is only used by the fbdev emulation
245 * helpers.
246 *
247 * FIXME:
248 *
249 * This callback is functionally redundant with the core gamma table
250 * support and simply exists because the fbdev hasn't yet been
251 * refactored to use the core gamma table interfaces.
252 */
Daniel Vetter092d01d2015-12-04 09:45:44 +0100253 void (*load_lut)(struct drm_crtc *crtc);
254
Daniel Vetter36b66082015-12-04 09:46:08 +0100255 /**
256 * @disable:
257 *
258 * This callback should be used to disable the CRTC. With the atomic
259 * drivers it is called after all encoders connected to this CRTC have
Daniel Vetter6806cdf2017-01-25 07:26:43 +0100260 * been shut off already using their own
261 * &drm_encoder_helper_funcs.disable hook. If that sequence is too
262 * simple drivers can just add their own hooks and call it from this
263 * CRTC callback here by looping over all encoders connected to it using
264 * for_each_encoder_on_crtc().
Daniel Vetter36b66082015-12-04 09:46:08 +0100265 *
266 * This hook is used both by legacy CRTC helpers and atomic helpers.
267 * Atomic drivers don't need to implement it if there's no need to
268 * disable anything at the CRTC level. To ensure that runtime PM
269 * handling (using either DPMS or the new "ACTIVE" property) works
270 * @disable must be the inverse of @enable for atomic drivers.
Liu Yingc9ac8b42016-08-26 15:30:38 +0800271 * Atomic drivers should consider to use @atomic_disable instead of
272 * this one.
Daniel Vetter36b66082015-12-04 09:46:08 +0100273 *
274 * NOTE:
275 *
276 * With legacy CRTC helpers there's a big semantic difference between
277 * @disable and other hooks (like @prepare or @dpms) used to shut down a
278 * CRTC: @disable is only called when also logically disabling the
279 * display pipeline and needs to release any resources acquired in
280 * @mode_set (like shared PLLs, or again release pinned framebuffers).
281 *
282 * Therefore @disable must be the inverse of @mode_set plus @commit for
283 * drivers still using legacy CRTC helpers, which is different from the
284 * rules under atomic.
285 */
Daniel Vetter092d01d2015-12-04 09:45:44 +0100286 void (*disable)(struct drm_crtc *crtc);
Daniel Vetter36b66082015-12-04 09:46:08 +0100287
288 /**
289 * @enable:
290 *
291 * This callback should be used to enable the CRTC. With the atomic
292 * drivers it is called before all encoders connected to this CRTC are
Daniel Vetter6806cdf2017-01-25 07:26:43 +0100293 * enabled through the encoder's own &drm_encoder_helper_funcs.enable
294 * hook. If that sequence is too simple drivers can just add their own
295 * hooks and call it from this CRTC callback here by looping over all
296 * encoders connected to it using for_each_encoder_on_crtc().
Daniel Vetter36b66082015-12-04 09:46:08 +0100297 *
298 * This hook is used only by atomic helpers, for symmetry with @disable.
299 * Atomic drivers don't need to implement it if there's no need to
300 * enable anything at the CRTC level. To ensure that runtime PM handling
301 * (using either DPMS or the new "ACTIVE" property) works
302 * @enable must be the inverse of @disable for atomic drivers.
303 */
Daniel Vetter092d01d2015-12-04 09:45:44 +0100304 void (*enable)(struct drm_crtc *crtc);
305
Daniel Vetter11a0ba92015-12-04 09:46:04 +0100306 /**
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 *
Daniel Vetter6806cdf2017-01-25 07:26:43 +0100320 * When using drm_atomic_helper_check_planes() this hook is called
321 * after the &drm_plane_helper_funcs.atomc_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.
Daniel Vetter11a0ba92015-12-04 09:46:04 +0100326 *
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
Daniel Vetter6806cdf2017-01-25 07:26:43 +0100329 * be taken though to ensure that state check and compute functions for
Daniel Vetter11a0ba92015-12-04 09:46:04 +0100330 * 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 * RETURNS:
345 *
346 * 0 on success, -EINVAL if the state or the transition can't be
347 * supported, -ENOMEM on memory allocation failure and -EDEADLK if an
348 * attempt to obtain another state object ran into a &drm_modeset_lock
349 * deadlock.
350 */
Daniel Vetter092d01d2015-12-04 09:45:44 +0100351 int (*atomic_check)(struct drm_crtc *crtc,
352 struct drm_crtc_state *state);
Daniel Vetter11a0ba92015-12-04 09:46:04 +0100353
354 /**
355 * @atomic_begin:
356 *
357 * Drivers should prepare for an atomic update of multiple planes on
358 * a CRTC in this hook. Depending upon hardware this might be vblank
359 * evasion, blocking updates by setting bits or doing preparatory work
360 * for e.g. manual update display.
361 *
362 * This hook is called before any plane commit functions are called.
363 *
364 * Note that the power state of the display pipe when this function is
365 * called depends upon the exact helpers and calling sequence the driver
Stefan Agner0dc99672016-10-31 10:36:46 -0700366 * has picked. See drm_atomic_helper_commit_planes() for a discussion of
367 * the tradeoffs and variants of plane commit helpers.
Daniel Vetter11a0ba92015-12-04 09:46:04 +0100368 *
369 * This callback is used by the atomic modeset helpers and by the
370 * transitional plane helpers, but it is optional.
371 */
Daniel Vetter092d01d2015-12-04 09:45:44 +0100372 void (*atomic_begin)(struct drm_crtc *crtc,
373 struct drm_crtc_state *old_crtc_state);
Daniel Vetter11a0ba92015-12-04 09:46:04 +0100374 /**
375 * @atomic_flush:
376 *
377 * Drivers should finalize an atomic update of multiple planes on
378 * a CRTC in this hook. Depending upon hardware this might include
379 * checking that vblank evasion was successful, unblocking updates by
380 * setting bits or setting the GO bit to flush out all updates.
381 *
382 * Simple hardware or hardware with special requirements can commit and
383 * flush out all updates for all planes from this hook and forgo all the
384 * other commit hooks for plane updates.
385 *
386 * This hook is called after any plane commit functions are called.
387 *
388 * Note that the power state of the display pipe when this function is
389 * called depends upon the exact helpers and calling sequence the driver
Stefan Agner0dc99672016-10-31 10:36:46 -0700390 * has picked. See drm_atomic_helper_commit_planes() for a discussion of
391 * the tradeoffs and variants of plane commit helpers.
Daniel Vetter11a0ba92015-12-04 09:46:04 +0100392 *
393 * This callback is used by the atomic modeset helpers and by the
394 * transitional plane helpers, but it is optional.
395 */
Daniel Vetter092d01d2015-12-04 09:45:44 +0100396 void (*atomic_flush)(struct drm_crtc *crtc,
397 struct drm_crtc_state *old_crtc_state);
Liu Yingc9ac8b42016-08-26 15:30:38 +0800398
399 /**
400 * @atomic_disable:
401 *
402 * This callback should be used to disable the CRTC. With the atomic
403 * drivers it is called after all encoders connected to this CRTC have
Daniel Vetter6806cdf2017-01-25 07:26:43 +0100404 * been shut off already using their own
405 * &drm_encoder_helper_funcs.disable hook. If that sequence is too
406 * simple drivers can just add their own hooks and call it from this
407 * CRTC callback here by looping over all encoders connected to it using
408 * for_each_encoder_on_crtc().
Liu Yingc9ac8b42016-08-26 15:30:38 +0800409 *
410 * This hook is used only by atomic helpers. Atomic drivers don't
411 * need to implement it if there's no need to disable anything at the
412 * CRTC level.
413 *
414 * Comparing to @disable, this one provides the additional input
415 * parameter @old_crtc_state which could be used to access the old
416 * state. Atomic drivers should consider to use this one instead
417 * of @disable.
418 */
419 void (*atomic_disable)(struct drm_crtc *crtc,
420 struct drm_crtc_state *old_crtc_state);
Daniel Vetter092d01d2015-12-04 09:45:44 +0100421};
422
423/**
424 * drm_crtc_helper_add - sets the helper vtable for a crtc
425 * @crtc: DRM CRTC
426 * @funcs: helper vtable to set for @crtc
427 */
428static inline void drm_crtc_helper_add(struct drm_crtc *crtc,
429 const struct drm_crtc_helper_funcs *funcs)
430{
431 crtc->helper_private = funcs;
432}
433
434/**
435 * struct drm_encoder_helper_funcs - helper operations for encoders
Daniel Vetter092d01d2015-12-04 09:45:44 +0100436 *
Daniel Vetter36b66082015-12-04 09:46:08 +0100437 * These hooks are used by the legacy CRTC helpers, the transitional plane
438 * helpers and the new atomic modesetting helpers.
Daniel Vetter092d01d2015-12-04 09:45:44 +0100439 */
440struct drm_encoder_helper_funcs {
Daniel Vetter36b66082015-12-04 09:46:08 +0100441 /**
442 * @dpms:
443 *
444 * Callback to control power levels on the encoder. If the mode passed in
445 * is unsupported, the provider must use the next lowest power level.
446 * This is used by the legacy encoder helpers to implement DPMS
447 * functionality in drm_helper_connector_dpms().
448 *
449 * This callback is also used to disable an encoder by calling it with
450 * DRM_MODE_DPMS_OFF if the @disable hook isn't used.
451 *
452 * This callback is used by the legacy CRTC helpers. Atomic helpers
453 * also support using this hook for enabling and disabling an encoder to
454 * facilitate transitions to atomic, but it is deprecated. Instead
455 * @enable and @disable should be used.
456 */
Daniel Vetter092d01d2015-12-04 09:45:44 +0100457 void (*dpms)(struct drm_encoder *encoder, int mode);
Daniel Vetter092d01d2015-12-04 09:45:44 +0100458
Daniel Vetter36b66082015-12-04 09:46:08 +0100459 /**
460 * @mode_fixup:
461 *
462 * This callback is used to validate and adjust a mode. The parameter
463 * mode is the display mode that should be fed to the next element in
464 * the display chain, either the final &drm_connector or a &drm_bridge.
465 * The parameter adjusted_mode is the input mode the encoder requires. It
466 * can be modified by this callback and does not need to match mode.
467 *
468 * This function is used by both legacy CRTC helpers and atomic helpers.
Carlos Palminha3c5b2672016-02-10 12:15:22 +0000469 * This hook is optional.
Daniel Vetter36b66082015-12-04 09:46:08 +0100470 *
471 * NOTE:
472 *
473 * This function is called in the check phase of atomic modesets, which
474 * can be aborted for any reason (including on userspace's request to
475 * just check whether a configuration would be possible). Atomic drivers
476 * MUST NOT touch any persistent state (hardware or software) or data
477 * structures except the passed in adjusted_mode parameter.
478 *
479 * This is in contrast to the legacy CRTC helpers where this was
480 * allowed.
481 *
482 * Atomic drivers which need to inspect and adjust more state should
483 * instead use the @atomic_check callback.
484 *
Daniel Vetterdf7d6782016-01-04 07:53:36 +0100485 * Also beware that neither core nor helpers filter modes before
486 * passing them to the driver: While the list of modes that is
487 * advertised to userspace is filtered using the connector's
Daniel Vetter6806cdf2017-01-25 07:26:43 +0100488 * &drm_connector_helper_funcs.mode_valid callback, neither the core nor
489 * the helpers do any filtering on modes passed in from userspace when
490 * setting a mode. It is therefore possible for userspace to pass in a
491 * mode that was previously filtered out using
492 * &drm_connector_helper_funcs.mode_valid or add a custom mode that
493 * wasn't probed from EDID or similar to begin with. Even though this
494 * is an advanced feature and rarely used nowadays, some users rely on
495 * being able to specify modes manually so drivers must be prepared to
496 * deal with it. Specifically this means that all drivers need not only
497 * validate modes in &drm_connector.mode_valid but also in this or in
498 * the &drm_crtc_helper_funcs.mode_fixup callback to make sure
499 * invalid modes passed in from userspace are rejected.
Daniel Vetterdf7d6782016-01-04 07:53:36 +0100500 *
Daniel Vetter36b66082015-12-04 09:46:08 +0100501 * RETURNS:
502 *
503 * True if an acceptable configuration is possible, false if the modeset
504 * operation should be rejected.
505 */
Daniel Vetter092d01d2015-12-04 09:45:44 +0100506 bool (*mode_fixup)(struct drm_encoder *encoder,
507 const struct drm_display_mode *mode,
508 struct drm_display_mode *adjusted_mode);
Daniel Vetter36b66082015-12-04 09:46:08 +0100509
510 /**
511 * @prepare:
512 *
513 * This callback should prepare the encoder for a subsequent modeset,
514 * which in practice means the driver should disable the encoder if it
515 * is running. Most drivers ended up implementing this by calling their
516 * @dpms hook with DRM_MODE_DPMS_OFF.
517 *
518 * This callback is used by the legacy CRTC helpers. Atomic helpers
519 * also support using this hook for disabling an encoder to facilitate
520 * transitions to atomic, but it is deprecated. Instead @disable should
521 * be used.
522 */
Daniel Vetter092d01d2015-12-04 09:45:44 +0100523 void (*prepare)(struct drm_encoder *encoder);
Daniel Vetter36b66082015-12-04 09:46:08 +0100524
525 /**
526 * @commit:
527 *
528 * This callback should commit the new mode on the encoder after a modeset,
529 * which in practice means the driver should enable the encoder. Most
530 * drivers ended up implementing this by calling their @dpms hook with
531 * DRM_MODE_DPMS_ON.
532 *
533 * This callback is used by the legacy CRTC helpers. Atomic helpers
534 * also support using this hook for enabling an encoder to facilitate
535 * transitions to atomic, but it is deprecated. Instead @enable should
536 * be used.
537 */
Daniel Vetter092d01d2015-12-04 09:45:44 +0100538 void (*commit)(struct drm_encoder *encoder);
Daniel Vetter36b66082015-12-04 09:46:08 +0100539
540 /**
541 * @mode_set:
542 *
543 * This callback is used to update the display mode of an encoder.
544 *
545 * Note that the display pipe is completely off when this function is
546 * called. Drivers which need hardware to be running before they program
547 * the new display mode (because they implement runtime PM) should not
548 * use this hook, because the helper library calls it only once and not
549 * every time the display pipeline is suspend using either DPMS or the
550 * new "ACTIVE" property. Such drivers should instead move all their
Daniel Vetter6806cdf2017-01-25 07:26:43 +0100551 * encoder setup into the @enable callback.
Daniel Vetter36b66082015-12-04 09:46:08 +0100552 *
553 * This callback is used both by the legacy CRTC helpers and the atomic
554 * modeset helpers. It is optional in the atomic helpers.
Philipp Zabelfe4a11c2016-07-22 12:20:47 +0200555 *
556 * NOTE:
557 *
558 * If the driver uses the atomic modeset helpers and needs to inspect
559 * the connector state or connector display info during mode setting,
560 * @atomic_mode_set can be used instead.
Daniel Vetter36b66082015-12-04 09:46:08 +0100561 */
Daniel Vetter092d01d2015-12-04 09:45:44 +0100562 void (*mode_set)(struct drm_encoder *encoder,
563 struct drm_display_mode *mode,
564 struct drm_display_mode *adjusted_mode);
Daniel Vetter36b66082015-12-04 09:46:08 +0100565
566 /**
Philipp Zabelfe4a11c2016-07-22 12:20:47 +0200567 * @atomic_mode_set:
568 *
569 * This callback is used to update the display mode of an encoder.
570 *
571 * Note that the display pipe is completely off when this function is
572 * called. Drivers which need hardware to be running before they program
573 * the new display mode (because they implement runtime PM) should not
574 * use this hook, because the helper library calls it only once and not
575 * every time the display pipeline is suspended using either DPMS or the
576 * new "ACTIVE" property. Such drivers should instead move all their
Daniel Vetter6806cdf2017-01-25 07:26:43 +0100577 * encoder setup into the @enable callback.
Philipp Zabelfe4a11c2016-07-22 12:20:47 +0200578 *
579 * This callback is used by the atomic modeset helpers in place of the
580 * @mode_set callback, if set by the driver. It is optional and should
581 * be used instead of @mode_set if the driver needs to inspect the
582 * connector state or display info, since there is no direct way to
583 * go from the encoder to the current connector.
584 */
585 void (*atomic_mode_set)(struct drm_encoder *encoder,
586 struct drm_crtc_state *crtc_state,
587 struct drm_connector_state *conn_state);
588
589 /**
Daniel Vetter36b66082015-12-04 09:46:08 +0100590 * @get_crtc:
591 *
592 * This callback is used by the legacy CRTC helpers to work around
593 * deficiencies in its own book-keeping.
594 *
595 * Do not use, use atomic helpers instead, which get the book keeping
596 * right.
597 *
598 * FIXME:
599 *
600 * Currently only nouveau is using this, and as soon as nouveau is
601 * atomic we can ditch this hook.
602 */
Daniel Vetter092d01d2015-12-04 09:45:44 +0100603 struct drm_crtc *(*get_crtc)(struct drm_encoder *encoder);
Daniel Vetter36b66082015-12-04 09:46:08 +0100604
605 /**
606 * @detect:
607 *
608 * This callback can be used by drivers who want to do detection on the
609 * encoder object instead of in connector functions.
610 *
611 * It is not used by any helper and therefore has purely driver-specific
612 * semantics. New drivers shouldn't use this and instead just implement
613 * their own private callbacks.
614 *
615 * FIXME:
616 *
617 * This should just be converted into a pile of driver vfuncs.
618 * Currently radeon, amdgpu and nouveau are using it.
619 */
Daniel Vetter092d01d2015-12-04 09:45:44 +0100620 enum drm_connector_status (*detect)(struct drm_encoder *encoder,
621 struct drm_connector *connector);
Daniel Vetter36b66082015-12-04 09:46:08 +0100622
623 /**
624 * @disable:
625 *
626 * This callback should be used to disable the encoder. With the atomic
627 * drivers it is called before this encoder's CRTC has been shut off
Daniel Vetter6806cdf2017-01-25 07:26:43 +0100628 * using their own &drm_crtc_helper_funcs.disable hook. If that
629 * sequence is too simple drivers can just add their own driver private
630 * encoder hooks and call them from CRTC's callback by looping over all
631 * encoders connected to it using for_each_encoder_on_crtc().
Daniel Vetter36b66082015-12-04 09:46:08 +0100632 *
633 * This hook is used both by legacy CRTC helpers and atomic helpers.
634 * Atomic drivers don't need to implement it if there's no need to
635 * disable anything at the encoder level. To ensure that runtime PM
636 * handling (using either DPMS or the new "ACTIVE" property) works
637 * @disable must be the inverse of @enable for atomic drivers.
638 *
639 * NOTE:
640 *
641 * With legacy CRTC helpers there's a big semantic difference between
642 * @disable and other hooks (like @prepare or @dpms) used to shut down a
643 * encoder: @disable is only called when also logically disabling the
644 * display pipeline and needs to release any resources acquired in
645 * @mode_set (like shared PLLs, or again release pinned framebuffers).
646 *
647 * Therefore @disable must be the inverse of @mode_set plus @commit for
648 * drivers still using legacy CRTC helpers, which is different from the
649 * rules under atomic.
650 */
Daniel Vetter092d01d2015-12-04 09:45:44 +0100651 void (*disable)(struct drm_encoder *encoder);
652
Daniel Vetter36b66082015-12-04 09:46:08 +0100653 /**
654 * @enable:
655 *
656 * This callback should be used to enable the encoder. With the atomic
657 * drivers it is called after this encoder's CRTC has been enabled using
Daniel Vetter6806cdf2017-01-25 07:26:43 +0100658 * their own &drm_crtc_helper_funcs.enable hook. If that sequence is
659 * too simple drivers can just add their own driver private encoder
660 * hooks and call them from CRTC's callback by looping over all encoders
661 * connected to it using for_each_encoder_on_crtc().
Daniel Vetter36b66082015-12-04 09:46:08 +0100662 *
663 * This hook is used only by atomic helpers, for symmetry with @disable.
664 * Atomic drivers don't need to implement it if there's no need to
665 * enable anything at the encoder level. To ensure that runtime PM handling
666 * (using either DPMS or the new "ACTIVE" property) works
667 * @enable must be the inverse of @disable for atomic drivers.
668 */
Daniel Vetter092d01d2015-12-04 09:45:44 +0100669 void (*enable)(struct drm_encoder *encoder);
670
Daniel Vetter36b66082015-12-04 09:46:08 +0100671 /**
672 * @atomic_check:
673 *
674 * This callback is used to validate encoder state for atomic drivers.
675 * Since the encoder is the object connecting the CRTC and connector it
676 * gets passed both states, to be able to validate interactions and
677 * update the CRTC to match what the encoder needs for the requested
678 * connector.
679 *
680 * This function is used by the atomic helpers, but it is optional.
681 *
682 * NOTE:
683 *
684 * This function is called in the check phase of an atomic update. The
685 * driver is not allowed to change anything outside of the free-standing
686 * state objects passed-in or assembled in the overall &drm_atomic_state
687 * update tracking structure.
688 *
689 * RETURNS:
690 *
691 * 0 on success, -EINVAL if the state or the transition can't be
692 * supported, -ENOMEM on memory allocation failure and -EDEADLK if an
693 * attempt to obtain another state object ran into a &drm_modeset_lock
694 * deadlock.
695 */
Daniel Vetter092d01d2015-12-04 09:45:44 +0100696 int (*atomic_check)(struct drm_encoder *encoder,
697 struct drm_crtc_state *crtc_state,
698 struct drm_connector_state *conn_state);
699};
700
701/**
Daniel Vetter36b66082015-12-04 09:46:08 +0100702 * drm_encoder_helper_add - sets the helper vtable for an encoder
Daniel Vetter092d01d2015-12-04 09:45:44 +0100703 * @encoder: DRM encoder
704 * @funcs: helper vtable to set for @encoder
705 */
706static inline void drm_encoder_helper_add(struct drm_encoder *encoder,
707 const struct drm_encoder_helper_funcs *funcs)
708{
709 encoder->helper_private = funcs;
710}
711
712/**
713 * struct drm_connector_helper_funcs - helper operations for connectors
Daniel Vetter092d01d2015-12-04 09:45:44 +0100714 *
Daniel Vetter4ee60342015-12-04 09:46:05 +0100715 * These functions are used by the atomic and legacy modeset helpers and by the
716 * probe helpers.
Daniel Vetter092d01d2015-12-04 09:45:44 +0100717 */
718struct drm_connector_helper_funcs {
Daniel Vetter4ee60342015-12-04 09:46:05 +0100719 /**
720 * @get_modes:
721 *
722 * This function should fill in all modes currently valid for the sink
Daniel Vetter6806cdf2017-01-25 07:26:43 +0100723 * into the &drm_connector.probed_modes list. It should also update the
Daniel Vetter4ee60342015-12-04 09:46:05 +0100724 * EDID property by calling drm_mode_connector_update_edid_property().
725 *
726 * The usual way to implement this is to cache the EDID retrieved in the
727 * probe callback somewhere in the driver-private connector structure.
728 * In this function drivers then parse the modes in the EDID and add
729 * them by calling drm_add_edid_modes(). But connectors that driver a
730 * fixed panel can also manually add specific modes using
Daniel Vetterdf7d6782016-01-04 07:53:36 +0100731 * drm_mode_probed_add(). Drivers which manually add modes should also
Daniel Vetter6806cdf2017-01-25 07:26:43 +0100732 * make sure that the &drm_connector.display_info,
733 * &drm_connector.width_mm and &drm_connector.height_mm fields are
734 * filled in.
Daniel Vetterdf7d6782016-01-04 07:53:36 +0100735 *
736 * Virtual drivers that just want some standard VESA mode with a given
737 * resolution can call drm_add_modes_noedid(), and mark the preferred
738 * one using drm_set_preferred_mode().
739 *
740 * Finally drivers that support audio probably want to update the ELD
741 * data, too, using drm_edid_to_eld().
Daniel Vetter4ee60342015-12-04 09:46:05 +0100742 *
Daniel Vetter6806cdf2017-01-25 07:26:43 +0100743 * This function is only called after the @detect hook has indicated
Daniel Vetter4ee60342015-12-04 09:46:05 +0100744 * that a sink is connected and when the EDID isn't overridden through
745 * sysfs or the kernel commandline.
746 *
747 * This callback is used by the probe helpers in e.g.
748 * drm_helper_probe_single_connector_modes().
749 *
Maarten Lankhorst6c5ed5a2017-04-06 20:55:20 +0200750 * To avoid races with concurrent connector state updates, the helper
751 * libraries always call this with the &drm_mode_config.connection_mutex
752 * held. Because of this it's safe to inspect &drm_connector->state.
753 *
Daniel Vetter4ee60342015-12-04 09:46:05 +0100754 * RETURNS:
755 *
756 * The number of modes added by calling drm_mode_probed_add().
757 */
Daniel Vetter092d01d2015-12-04 09:45:44 +0100758 int (*get_modes)(struct drm_connector *connector);
Daniel Vetter4ee60342015-12-04 09:46:05 +0100759
760 /**
Maarten Lankhorst6c5ed5a2017-04-06 20:55:20 +0200761 * @detect_ctx:
762 *
763 * Check to see if anything is attached to the connector. The parameter
764 * force is set to false whilst polling, true when checking the
765 * connector due to a user request. force can be used by the driver to
766 * avoid expensive, destructive operations during automated probing.
767 *
768 * This callback is optional, if not implemented the connector will be
769 * considered as always being attached.
770 *
771 * This is the atomic version of &drm_connector_funcs.detect.
772 *
773 * To avoid races against concurrent connector state updates, the
774 * helper libraries always call this with ctx set to a valid context,
775 * and &drm_mode_config.connection_mutex will always be locked with
776 * the ctx parameter set to this ctx. This allows taking additional
777 * locks as required.
778 *
779 * RETURNS:
780 *
781 * &drm_connector_status indicating the connector's status,
782 * or the error code returned by drm_modeset_lock(), -EDEADLK.
783 */
784 int (*detect_ctx)(struct drm_connector *connector,
785 struct drm_modeset_acquire_ctx *ctx,
786 bool force);
787
788 /**
Daniel Vetter4ee60342015-12-04 09:46:05 +0100789 * @mode_valid:
790 *
791 * Callback to validate a mode for a connector, irrespective of the
792 * specific display configuration.
793 *
794 * This callback is used by the probe helpers to filter the mode list
795 * (which is usually derived from the EDID data block from the sink).
796 * See e.g. drm_helper_probe_single_connector_modes().
797 *
798 * NOTE:
799 *
800 * This only filters the mode list supplied to userspace in the
801 * GETCONNECOTR IOCTL. Userspace is free to create modes of its own and
802 * ask the kernel to use them. It this case the atomic helpers or legacy
803 * CRTC helpers will not call this function. Drivers therefore must
804 * still fully validate any mode passed in in a modeset request.
805 *
Maarten Lankhorst6c5ed5a2017-04-06 20:55:20 +0200806 * To avoid races with concurrent connector state updates, the helper
807 * libraries always call this with the &drm_mode_config.connection_mutex
808 * held. Because of this it's safe to inspect &drm_connector->state.
809 *
Daniel Vetter4ee60342015-12-04 09:46:05 +0100810 * RETURNS:
811 *
Daniel Vetter6806cdf2017-01-25 07:26:43 +0100812 * Either &drm_mode_status.MODE_OK or one of the failure reasons in &enum
813 * drm_mode_status.
Daniel Vetter4ee60342015-12-04 09:46:05 +0100814 */
Daniel Vetter092d01d2015-12-04 09:45:44 +0100815 enum drm_mode_status (*mode_valid)(struct drm_connector *connector,
816 struct drm_display_mode *mode);
Daniel Vetter4ee60342015-12-04 09:46:05 +0100817 /**
818 * @best_encoder:
819 *
820 * This function should select the best encoder for the given connector.
821 *
822 * This function is used by both the atomic helpers (in the
823 * drm_atomic_helper_check_modeset() function) and in the legacy CRTC
824 * helpers.
825 *
826 * NOTE:
827 *
828 * In atomic drivers this function is called in the check phase of an
829 * atomic update. The driver is not allowed to change or inspect
830 * anything outside of arguments passed-in. Atomic drivers which need to
831 * inspect dynamic configuration state should instead use
832 * @atomic_best_encoder.
833 *
Boris Brezillonc61b93f2016-06-07 13:47:56 +0200834 * You can leave this function to NULL if the connector is only
835 * attached to a single encoder and you are using the atomic helpers.
836 * In this case, the core will call drm_atomic_helper_best_encoder()
837 * for you.
838 *
Daniel Vetter4ee60342015-12-04 09:46:05 +0100839 * RETURNS:
840 *
841 * Encoder that should be used for the given connector and connector
842 * state, or NULL if no suitable encoder exists. Note that the helpers
843 * will ensure that encoders aren't used twice, drivers should not check
844 * for this.
845 */
Daniel Vetter092d01d2015-12-04 09:45:44 +0100846 struct drm_encoder *(*best_encoder)(struct drm_connector *connector);
Daniel Vetter4ee60342015-12-04 09:46:05 +0100847
848 /**
849 * @atomic_best_encoder:
850 *
851 * This is the atomic version of @best_encoder for atomic drivers which
852 * need to select the best encoder depending upon the desired
853 * configuration and can't select it statically.
854 *
Boris Brezillonc61b93f2016-06-07 13:47:56 +0200855 * This function is used by drm_atomic_helper_check_modeset().
856 * If it is not implemented, the core will fallback to @best_encoder
857 * (or drm_atomic_helper_best_encoder() if @best_encoder is NULL).
Daniel Vetter4ee60342015-12-04 09:46:05 +0100858 *
859 * NOTE:
860 *
861 * This function is called in the check phase of an atomic update. The
862 * driver is not allowed to change anything outside of the free-standing
863 * state objects passed-in or assembled in the overall &drm_atomic_state
864 * update tracking structure.
865 *
866 * RETURNS:
867 *
868 * Encoder that should be used for the given connector and connector
869 * state, or NULL if no suitable encoder exists. Note that the helpers
870 * will ensure that encoders aren't used twice, drivers should not check
871 * for this.
872 */
Daniel Vetter092d01d2015-12-04 09:45:44 +0100873 struct drm_encoder *(*atomic_best_encoder)(struct drm_connector *connector,
874 struct drm_connector_state *connector_state);
Maarten Lankhorstce09d762017-04-06 13:19:03 +0200875
876 /**
877 * @atomic_check:
878 *
879 * This hook is used to validate connector state. This function is
880 * called from &drm_atomic_helper_check_modeset, and is called when
881 * a connector property is set, or a modeset on the crtc is forced.
882 *
883 * Because &drm_atomic_helper_check_modeset may be called multiple times,
884 * this function should handle being called multiple times as well.
885 *
886 * This function is also allowed to inspect any other object's state and
887 * can add more state objects to the atomic commit if needed. Care must
888 * be taken though to ensure that state check and compute functions for
889 * these added states are all called, and derived state in other objects
890 * all updated. Again the recommendation is to just call check helpers
891 * until a maximal configuration is reached.
892 *
893 * NOTE:
894 *
895 * This function is called in the check phase of an atomic update. The
896 * driver is not allowed to change anything outside of the free-standing
897 * state objects passed-in or assembled in the overall &drm_atomic_state
898 * update tracking structure.
899 *
900 * RETURNS:
901 *
902 * 0 on success, -EINVAL if the state or the transition can't be
903 * supported, -ENOMEM on memory allocation failure and -EDEADLK if an
904 * attempt to obtain another state object ran into a &drm_modeset_lock
905 * deadlock.
906 */
907 int (*atomic_check)(struct drm_connector *connector,
908 struct drm_connector_state *state);
Daniel Vetter092d01d2015-12-04 09:45:44 +0100909};
910
911/**
912 * drm_connector_helper_add - sets the helper vtable for a connector
913 * @connector: DRM connector
914 * @funcs: helper vtable to set for @connector
915 */
916static inline void drm_connector_helper_add(struct drm_connector *connector,
917 const struct drm_connector_helper_funcs *funcs)
918{
919 connector->helper_private = funcs;
920}
921
922/**
Daniel Vetter11a0ba92015-12-04 09:46:04 +0100923 * struct drm_plane_helper_funcs - helper operations for planes
Daniel Vetter092d01d2015-12-04 09:45:44 +0100924 *
Daniel Vetter11a0ba92015-12-04 09:46:04 +0100925 * These functions are used by the atomic helpers and by the transitional plane
926 * helpers.
Daniel Vetter092d01d2015-12-04 09:45:44 +0100927 */
928struct drm_plane_helper_funcs {
Daniel Vetter11a0ba92015-12-04 09:46:04 +0100929 /**
930 * @prepare_fb:
931 *
932 * This hook is to prepare a framebuffer for scanout by e.g. pinning
933 * it's backing storage or relocating it into a contiguous block of
934 * VRAM. Other possible preparatory work includes flushing caches.
935 *
936 * This function must not block for outstanding rendering, since it is
937 * called in the context of the atomic IOCTL even for async commits to
938 * be able to return any errors to userspace. Instead the recommended
939 * way is to fill out the fence member of the passed-in
940 * &drm_plane_state. If the driver doesn't support native fences then
941 * equivalent functionality should be implemented through private
942 * members in the plane structure.
943 *
944 * The helpers will call @cleanup_fb with matching arguments for every
945 * successful call to this hook.
946 *
947 * This callback is used by the atomic modeset helpers and by the
948 * transitional plane helpers, but it is optional.
949 *
950 * RETURNS:
951 *
952 * 0 on success or one of the following negative error codes allowed by
Daniel Vetter6806cdf2017-01-25 07:26:43 +0100953 * the &drm_mode_config_funcs.atomic_commit vfunc. When using helpers
Daniel Vetter11a0ba92015-12-04 09:46:04 +0100954 * this callback is the only one which can fail an atomic commit,
955 * everything else must complete successfully.
956 */
Daniel Vetter092d01d2015-12-04 09:45:44 +0100957 int (*prepare_fb)(struct drm_plane *plane,
Chris Wilson18320402016-08-18 19:00:16 +0100958 struct drm_plane_state *new_state);
Daniel Vetter11a0ba92015-12-04 09:46:04 +0100959 /**
960 * @cleanup_fb:
961 *
962 * This hook is called to clean up any resources allocated for the given
963 * framebuffer and plane configuration in @prepare_fb.
964 *
965 * This callback is used by the atomic modeset helpers and by the
966 * transitional plane helpers, but it is optional.
967 */
Daniel Vetter092d01d2015-12-04 09:45:44 +0100968 void (*cleanup_fb)(struct drm_plane *plane,
Chris Wilson18320402016-08-18 19:00:16 +0100969 struct drm_plane_state *old_state);
Daniel Vetter092d01d2015-12-04 09:45:44 +0100970
Daniel Vetter11a0ba92015-12-04 09:46:04 +0100971 /**
972 * @atomic_check:
973 *
974 * Drivers should check plane specific constraints in this hook.
975 *
Daniel Vetter6806cdf2017-01-25 07:26:43 +0100976 * When using drm_atomic_helper_check_planes() plane's @atomic_check
Daniel Vetter11a0ba92015-12-04 09:46:04 +0100977 * hooks are called before the ones for CRTCs, which allows drivers to
978 * request shared resources that the CRTC controls here. For more
979 * complicated dependencies the driver can call the provided check helpers
980 * multiple times until the computed state has a final configuration and
981 * everything has been checked.
982 *
983 * This function is also allowed to inspect any other object's state and
984 * can add more state objects to the atomic commit if needed. Care must
Daniel Vetter6806cdf2017-01-25 07:26:43 +0100985 * be taken though to ensure that state check and compute functions for
Daniel Vetter11a0ba92015-12-04 09:46:04 +0100986 * these added states are all called, and derived state in other objects
987 * all updated. Again the recommendation is to just call check helpers
988 * until a maximal configuration is reached.
989 *
990 * This callback is used by the atomic modeset helpers and by the
991 * transitional plane helpers, but it is optional.
992 *
993 * NOTE:
994 *
995 * This function is called in the check phase of an atomic update. The
996 * driver is not allowed to change anything outside of the free-standing
997 * state objects passed-in or assembled in the overall &drm_atomic_state
998 * update tracking structure.
999 *
1000 * RETURNS:
1001 *
1002 * 0 on success, -EINVAL if the state or the transition can't be
1003 * supported, -ENOMEM on memory allocation failure and -EDEADLK if an
1004 * attempt to obtain another state object ran into a &drm_modeset_lock
1005 * deadlock.
1006 */
Daniel Vetter092d01d2015-12-04 09:45:44 +01001007 int (*atomic_check)(struct drm_plane *plane,
1008 struct drm_plane_state *state);
Daniel Vetter11a0ba92015-12-04 09:46:04 +01001009
1010 /**
1011 * @atomic_update:
1012 *
1013 * Drivers should use this function to update the plane state. This
Daniel Vetter6806cdf2017-01-25 07:26:43 +01001014 * hook is called in-between the &drm_crtc_helper_funcs.atomic_begin and
1015 * drm_crtc_helper_funcs.atomic_flush callbacks.
Daniel Vetter11a0ba92015-12-04 09:46:04 +01001016 *
1017 * Note that the power state of the display pipe when this function is
1018 * called depends upon the exact helpers and calling sequence the driver
Stefan Agner0dc99672016-10-31 10:36:46 -07001019 * has picked. See drm_atomic_helper_commit_planes() for a discussion of
1020 * the tradeoffs and variants of plane commit helpers.
Daniel Vetter11a0ba92015-12-04 09:46:04 +01001021 *
1022 * This callback is used by the atomic modeset helpers and by the
1023 * transitional plane helpers, but it is optional.
1024 */
Daniel Vetter092d01d2015-12-04 09:45:44 +01001025 void (*atomic_update)(struct drm_plane *plane,
1026 struct drm_plane_state *old_state);
Daniel Vetter11a0ba92015-12-04 09:46:04 +01001027 /**
1028 * @atomic_disable:
1029 *
1030 * Drivers should use this function to unconditionally disable a plane.
Daniel Vetter6806cdf2017-01-25 07:26:43 +01001031 * This hook is called in-between the
1032 * &drm_crtc_helper_funcs.atomic_begin and
1033 * drm_crtc_helper_funcs.atomic_flush callbacks. It is an alternative to
Daniel Vetter11a0ba92015-12-04 09:46:04 +01001034 * @atomic_update, which will be called for disabling planes, too, if
1035 * the @atomic_disable hook isn't implemented.
1036 *
1037 * This hook is also useful to disable planes in preparation of a modeset,
1038 * by calling drm_atomic_helper_disable_planes_on_crtc() from the
Daniel Vetter6806cdf2017-01-25 07:26:43 +01001039 * &drm_crtc_helper_funcs.disable hook.
Daniel Vetter11a0ba92015-12-04 09:46:04 +01001040 *
1041 * Note that the power state of the display pipe when this function is
1042 * called depends upon the exact helpers and calling sequence the driver
Stefan Agner0dc99672016-10-31 10:36:46 -07001043 * has picked. See drm_atomic_helper_commit_planes() for a discussion of
1044 * the tradeoffs and variants of plane commit helpers.
Daniel Vetter11a0ba92015-12-04 09:46:04 +01001045 *
1046 * This callback is used by the atomic modeset helpers and by the
1047 * transitional plane helpers, but it is optional.
1048 */
Daniel Vetter092d01d2015-12-04 09:45:44 +01001049 void (*atomic_disable)(struct drm_plane *plane,
1050 struct drm_plane_state *old_state);
1051};
1052
1053/**
1054 * drm_plane_helper_add - sets the helper vtable for a plane
1055 * @plane: DRM plane
1056 * @funcs: helper vtable to set for @plane
1057 */
1058static inline void drm_plane_helper_add(struct drm_plane *plane,
1059 const struct drm_plane_helper_funcs *funcs)
1060{
1061 plane->helper_private = funcs;
1062}
1063
Daniel Vetter9f2a7952016-06-08 14:19:02 +02001064/**
1065 * struct drm_mode_config_helper_funcs - global modeset helper operations
1066 *
1067 * These helper functions are used by the atomic helpers.
1068 */
1069struct drm_mode_config_helper_funcs {
1070 /**
1071 * @atomic_commit_tail:
1072 *
1073 * This hook is used by the default atomic_commit() hook implemented in
1074 * drm_atomic_helper_commit() together with the nonblocking commit
1075 * helpers (see drm_atomic_helper_setup_commit() for a starting point)
1076 * to implement blocking and nonblocking commits easily. It is not used
1077 * by the atomic helpers
1078 *
Daniel Vetter1ea0c022016-11-21 18:18:02 +01001079 * This function is called when the new atomic state has already been
1080 * swapped into the various state pointers. The passed in state
1081 * therefore contains copies of the old/previous state. This hook should
1082 * commit the new state into hardware. Note that the helpers have
1083 * already waited for preceeding atomic commits and fences, but drivers
1084 * can add more waiting calls at the start of their implementation, e.g.
1085 * to wait for driver-internal request for implicit syncing, before
1086 * starting to commit the update to the hardware.
Daniel Vetter9f2a7952016-06-08 14:19:02 +02001087 *
1088 * After the atomic update is committed to the hardware this hook needs
1089 * to call drm_atomic_helper_commit_hw_done(). Then wait for the upate
1090 * to be executed by the hardware, for example using
1091 * drm_atomic_helper_wait_for_vblanks(), and then clean up the old
1092 * framebuffers using drm_atomic_helper_cleanup_planes().
1093 *
1094 * When disabling a CRTC this hook _must_ stall for the commit to
1095 * complete. Vblank waits don't work on disabled CRTC, hence the core
1096 * can't take care of this. And it also can't rely on the vblank event,
1097 * since that can be signalled already when the screen shows black,
1098 * which can happen much earlier than the last hardware access needed to
1099 * shut off the display pipeline completely.
1100 *
1101 * This hook is optional, the default implementation is
1102 * drm_atomic_helper_commit_tail().
1103 */
1104 void (*atomic_commit_tail)(struct drm_atomic_state *state);
1105};
1106
Daniel Vetter092d01d2015-12-04 09:45:44 +01001107#endif