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