]>
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 | |
0b20a0f8 | 74 | * @atomic_enable and @atomic_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 | |
0b20a0f8 LP |
88 | * transitions to atomic, but it is deprecated. Instead @atomic_disable |
89 | * should be used. | |
36b66080 | 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 | |
0b20a0f8 LP |
103 | * transitions to atomic, but it is deprecated. Instead @atomic_enable |
104 | * should be used. | |
36b66080 | 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 | |
0b20a0f8 | 225 | * move all their CRTC setup into the @atomic_enable callback. |
36b66080 DV |
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 | * @disable: | |
271 | * | |
272 | * This callback should be used to disable the CRTC. With the atomic | |
273 | * drivers it is called after all encoders connected to this CRTC have | |
6806cdf9 DV |
274 | * been shut off already using their own |
275 | * &drm_encoder_helper_funcs.disable hook. If that sequence is too | |
276 | * simple drivers can just add their own hooks and call it from this | |
277 | * CRTC callback here by looping over all encoders connected to it using | |
278 | * for_each_encoder_on_crtc(). | |
36b66080 DV |
279 | * |
280 | * This hook is used both by legacy CRTC helpers and atomic helpers. | |
281 | * Atomic drivers don't need to implement it if there's no need to | |
282 | * disable anything at the CRTC level. To ensure that runtime PM | |
283 | * handling (using either DPMS or the new "ACTIVE" property) works | |
0b20a0f8 | 284 | * @disable must be the inverse of @atomic_enable for atomic drivers. |
c9ac8b4c LY |
285 | * Atomic drivers should consider to use @atomic_disable instead of |
286 | * this one. | |
36b66080 DV |
287 | * |
288 | * NOTE: | |
289 | * | |
290 | * With legacy CRTC helpers there's a big semantic difference between | |
291 | * @disable and other hooks (like @prepare or @dpms) used to shut down a | |
292 | * CRTC: @disable is only called when also logically disabling the | |
293 | * display pipeline and needs to release any resources acquired in | |
294 | * @mode_set (like shared PLLs, or again release pinned framebuffers). | |
295 | * | |
296 | * Therefore @disable must be the inverse of @mode_set plus @commit for | |
297 | * drivers still using legacy CRTC helpers, which is different from the | |
298 | * rules under atomic. | |
299 | */ | |
092d01da | 300 | void (*disable)(struct drm_crtc *crtc); |
36b66080 | 301 | |
11a0ba97 DV |
302 | /** |
303 | * @atomic_check: | |
304 | * | |
305 | * Drivers should check plane-update related CRTC constraints in this | |
306 | * hook. They can also check mode related limitations but need to be | |
307 | * aware of the calling order, since this hook is used by | |
308 | * drm_atomic_helper_check_planes() whereas the preparations needed to | |
309 | * check output routing and the display mode is done in | |
310 | * drm_atomic_helper_check_modeset(). Therefore drivers that want to | |
311 | * check output routing and display mode constraints in this callback | |
312 | * must ensure that drm_atomic_helper_check_modeset() has been called | |
313 | * beforehand. This is calling order used by the default helper | |
314 | * implementation in drm_atomic_helper_check(). | |
315 | * | |
6806cdf9 | 316 | * When using drm_atomic_helper_check_planes() this hook is called |
2093ea2e | 317 | * after the &drm_plane_helper_funcs.atomic_check hook for planes, which |
6806cdf9 DV |
318 | * allows drivers to assign shared resources requested by planes in this |
319 | * callback here. For more complicated dependencies the driver can call | |
320 | * the provided check helpers multiple times until the computed state | |
321 | * has a final configuration and everything has been checked. | |
11a0ba97 DV |
322 | * |
323 | * This function is also allowed to inspect any other object's state and | |
324 | * can add more state objects to the atomic commit if needed. Care must | |
6806cdf9 | 325 | * be taken though to ensure that state check and compute functions for |
11a0ba97 DV |
326 | * these added states are all called, and derived state in other objects |
327 | * all updated. Again the recommendation is to just call check helpers | |
328 | * until a maximal configuration is reached. | |
329 | * | |
330 | * This callback is used by the atomic modeset helpers and by the | |
331 | * transitional plane helpers, but it is optional. | |
332 | * | |
333 | * NOTE: | |
334 | * | |
335 | * This function is called in the check phase of an atomic update. The | |
336 | * driver is not allowed to change anything outside of the free-standing | |
337 | * state objects passed-in or assembled in the overall &drm_atomic_state | |
338 | * update tracking structure. | |
339 | * | |
3eb220a5 JA |
340 | * Also beware that userspace can request its own custom modes, neither |
341 | * core nor helpers filter modes to the list of probe modes reported by | |
342 | * the GETCONNECTOR IOCTL and stored in &drm_connector.modes. To ensure | |
343 | * that modes are filtered consistently put any CRTC constraints and | |
344 | * limits checks into @mode_valid. | |
345 | * | |
11a0ba97 DV |
346 | * RETURNS: |
347 | * | |
348 | * 0 on success, -EINVAL if the state or the transition can't be | |
349 | * supported, -ENOMEM on memory allocation failure and -EDEADLK if an | |
350 | * attempt to obtain another state object ran into a &drm_modeset_lock | |
351 | * deadlock. | |
352 | */ | |
092d01da DV |
353 | int (*atomic_check)(struct drm_crtc *crtc, |
354 | struct drm_crtc_state *state); | |
11a0ba97 DV |
355 | |
356 | /** | |
357 | * @atomic_begin: | |
358 | * | |
359 | * Drivers should prepare for an atomic update of multiple planes on | |
360 | * a CRTC in this hook. Depending upon hardware this might be vblank | |
361 | * evasion, blocking updates by setting bits or doing preparatory work | |
362 | * for e.g. manual update display. | |
363 | * | |
364 | * This hook is called before any plane commit functions are called. | |
365 | * | |
366 | * Note that the power state of the display pipe when this function is | |
367 | * called depends upon the exact helpers and calling sequence the driver | |
0dc9967d SA |
368 | * has picked. See drm_atomic_helper_commit_planes() for a discussion of |
369 | * the tradeoffs and variants of plane commit helpers. | |
11a0ba97 DV |
370 | * |
371 | * This callback is used by the atomic modeset helpers and by the | |
372 | * transitional plane helpers, but it is optional. | |
373 | */ | |
092d01da DV |
374 | void (*atomic_begin)(struct drm_crtc *crtc, |
375 | struct drm_crtc_state *old_crtc_state); | |
11a0ba97 DV |
376 | /** |
377 | * @atomic_flush: | |
378 | * | |
379 | * Drivers should finalize an atomic update of multiple planes on | |
380 | * a CRTC in this hook. Depending upon hardware this might include | |
381 | * checking that vblank evasion was successful, unblocking updates by | |
382 | * setting bits or setting the GO bit to flush out all updates. | |
383 | * | |
384 | * Simple hardware or hardware with special requirements can commit and | |
385 | * flush out all updates for all planes from this hook and forgo all the | |
386 | * other commit hooks for plane updates. | |
387 | * | |
388 | * This hook is called after any plane commit functions are called. | |
389 | * | |
390 | * Note that the power state of the display pipe when this function is | |
391 | * called depends upon the exact helpers and calling sequence the driver | |
0dc9967d SA |
392 | * has picked. See drm_atomic_helper_commit_planes() for a discussion of |
393 | * the tradeoffs and variants of plane commit helpers. | |
11a0ba97 DV |
394 | * |
395 | * This callback is used by the atomic modeset helpers and by the | |
396 | * transitional plane helpers, but it is optional. | |
397 | */ | |
092d01da DV |
398 | void (*atomic_flush)(struct drm_crtc *crtc, |
399 | struct drm_crtc_state *old_crtc_state); | |
c9ac8b4c | 400 | |
0b20a0f8 LP |
401 | /** |
402 | * @atomic_enable: | |
403 | * | |
404 | * This callback should be used to enable the CRTC. With the atomic | |
405 | * drivers it is called before all encoders connected to this CRTC are | |
406 | * enabled through the encoder's own &drm_encoder_helper_funcs.enable | |
407 | * hook. If that sequence is too simple drivers can just add their own | |
408 | * hooks and call it from this CRTC callback here by looping over all | |
409 | * encoders connected to it using for_each_encoder_on_crtc(). | |
410 | * | |
411 | * This hook is used only by atomic helpers, for symmetry with | |
412 | * @atomic_disable. Atomic drivers don't need to implement it if there's | |
413 | * no need to enable anything at the CRTC level. To ensure that runtime | |
414 | * PM handling (using either DPMS or the new "ACTIVE" property) works | |
415 | * @atomic_enable must be the inverse of @atomic_disable for atomic | |
416 | * drivers. | |
417 | * | |
418 | * Drivers can use the @old_crtc_state input parameter if the operations | |
419 | * needed to enable the CRTC don't depend solely on the new state but | |
420 | * also on the transition between the old state and the new state. | |
421 | */ | |
422 | void (*atomic_enable)(struct drm_crtc *crtc, | |
423 | struct drm_crtc_state *old_crtc_state); | |
424 | ||
c9ac8b4c LY |
425 | /** |
426 | * @atomic_disable: | |
427 | * | |
428 | * This callback should be used to disable the CRTC. With the atomic | |
429 | * drivers it is called after all encoders connected to this CRTC have | |
6806cdf9 DV |
430 | * been shut off already using their own |
431 | * &drm_encoder_helper_funcs.disable hook. If that sequence is too | |
432 | * simple drivers can just add their own hooks and call it from this | |
433 | * CRTC callback here by looping over all encoders connected to it using | |
434 | * for_each_encoder_on_crtc(). | |
c9ac8b4c LY |
435 | * |
436 | * This hook is used only by atomic helpers. Atomic drivers don't | |
437 | * need to implement it if there's no need to disable anything at the | |
438 | * CRTC level. | |
439 | * | |
440 | * Comparing to @disable, this one provides the additional input | |
441 | * parameter @old_crtc_state which could be used to access the old | |
442 | * state. Atomic drivers should consider to use this one instead | |
443 | * of @disable. | |
444 | */ | |
445 | void (*atomic_disable)(struct drm_crtc *crtc, | |
446 | struct drm_crtc_state *old_crtc_state); | |
092d01da DV |
447 | }; |
448 | ||
449 | /** | |
450 | * drm_crtc_helper_add - sets the helper vtable for a crtc | |
451 | * @crtc: DRM CRTC | |
452 | * @funcs: helper vtable to set for @crtc | |
453 | */ | |
454 | static inline void drm_crtc_helper_add(struct drm_crtc *crtc, | |
455 | const struct drm_crtc_helper_funcs *funcs) | |
456 | { | |
457 | crtc->helper_private = funcs; | |
458 | } | |
459 | ||
460 | /** | |
461 | * struct drm_encoder_helper_funcs - helper operations for encoders | |
092d01da | 462 | * |
36b66080 DV |
463 | * These hooks are used by the legacy CRTC helpers, the transitional plane |
464 | * helpers and the new atomic modesetting helpers. | |
092d01da DV |
465 | */ |
466 | struct drm_encoder_helper_funcs { | |
36b66080 DV |
467 | /** |
468 | * @dpms: | |
469 | * | |
470 | * Callback to control power levels on the encoder. If the mode passed in | |
471 | * is unsupported, the provider must use the next lowest power level. | |
472 | * This is used by the legacy encoder helpers to implement DPMS | |
473 | * functionality in drm_helper_connector_dpms(). | |
474 | * | |
475 | * This callback is also used to disable an encoder by calling it with | |
476 | * DRM_MODE_DPMS_OFF if the @disable hook isn't used. | |
477 | * | |
478 | * This callback is used by the legacy CRTC helpers. Atomic helpers | |
479 | * also support using this hook for enabling and disabling an encoder to | |
480 | * facilitate transitions to atomic, but it is deprecated. Instead | |
481 | * @enable and @disable should be used. | |
482 | */ | |
092d01da | 483 | void (*dpms)(struct drm_encoder *encoder, int mode); |
092d01da | 484 | |
3eb220a5 JA |
485 | /** |
486 | * @mode_valid: | |
487 | * | |
488 | * This callback is used to check if a specific mode is valid in this | |
489 | * encoder. This should be implemented if the encoder has some sort | |
490 | * of restriction in the modes it can display. For example, a given | |
491 | * encoder may be responsible to set a clock value. If the clock can | |
492 | * not produce all the values for the available modes then this callback | |
493 | * can be used to restrict the number of modes to only the ones that | |
494 | * can be displayed. | |
495 | * | |
496 | * This hook is used by the probe helpers to filter the mode list in | |
497 | * drm_helper_probe_single_connector_modes(), and it is used by the | |
498 | * atomic helpers to validate modes supplied by userspace in | |
499 | * drm_atomic_helper_check_modeset(). | |
500 | * | |
501 | * This function is optional. | |
502 | * | |
503 | * NOTE: | |
504 | * | |
505 | * Since this function is both called from the check phase of an atomic | |
506 | * commit, and the mode validation in the probe paths it is not allowed | |
507 | * to look at anything else but the passed-in mode, and validate it | |
508 | * against configuration-invariant hardward constraints. Any further | |
509 | * limits which depend upon the configuration can only be checked in | |
510 | * @mode_fixup or @atomic_check. | |
511 | * | |
512 | * RETURNS: | |
513 | * | |
514 | * drm_mode_status Enum | |
515 | */ | |
516 | enum drm_mode_status (*mode_valid)(struct drm_encoder *crtc, | |
517 | const struct drm_display_mode *mode); | |
518 | ||
36b66080 DV |
519 | /** |
520 | * @mode_fixup: | |
521 | * | |
522 | * This callback is used to validate and adjust a mode. The parameter | |
523 | * mode is the display mode that should be fed to the next element in | |
524 | * the display chain, either the final &drm_connector or a &drm_bridge. | |
525 | * The parameter adjusted_mode is the input mode the encoder requires. It | |
9de5d4a6 DV |
526 | * can be modified by this callback and does not need to match mode. See |
527 | * also &drm_crtc_state.adjusted_mode for more details. | |
36b66080 DV |
528 | * |
529 | * This function is used by both legacy CRTC helpers and atomic helpers. | |
3c5b2673 | 530 | * This hook is optional. |
36b66080 DV |
531 | * |
532 | * NOTE: | |
533 | * | |
534 | * This function is called in the check phase of atomic modesets, which | |
535 | * can be aborted for any reason (including on userspace's request to | |
536 | * just check whether a configuration would be possible). Atomic drivers | |
537 | * MUST NOT touch any persistent state (hardware or software) or data | |
538 | * structures except the passed in adjusted_mode parameter. | |
539 | * | |
540 | * This is in contrast to the legacy CRTC helpers where this was | |
541 | * allowed. | |
542 | * | |
543 | * Atomic drivers which need to inspect and adjust more state should | |
9f800214 DV |
544 | * instead use the @atomic_check callback. If @atomic_check is used, |
545 | * this hook isn't called since @atomic_check allows a strict superset | |
546 | * of the functionality of @mode_fixup. | |
36b66080 | 547 | * |
3eb220a5 JA |
548 | * Also beware that userspace can request its own custom modes, neither |
549 | * core nor helpers filter modes to the list of probe modes reported by | |
550 | * the GETCONNECTOR IOCTL and stored in &drm_connector.modes. To ensure | |
551 | * that modes are filtered consistently put any encoder constraints and | |
552 | * limits checks into @mode_valid. | |
df7d678b | 553 | * |
36b66080 DV |
554 | * RETURNS: |
555 | * | |
556 | * True if an acceptable configuration is possible, false if the modeset | |
557 | * operation should be rejected. | |
558 | */ | |
092d01da DV |
559 | bool (*mode_fixup)(struct drm_encoder *encoder, |
560 | const struct drm_display_mode *mode, | |
561 | struct drm_display_mode *adjusted_mode); | |
36b66080 DV |
562 | |
563 | /** | |
564 | * @prepare: | |
565 | * | |
566 | * This callback should prepare the encoder for a subsequent modeset, | |
567 | * which in practice means the driver should disable the encoder if it | |
568 | * is running. Most drivers ended up implementing this by calling their | |
569 | * @dpms hook with DRM_MODE_DPMS_OFF. | |
570 | * | |
571 | * This callback is used by the legacy CRTC helpers. Atomic helpers | |
572 | * also support using this hook for disabling an encoder to facilitate | |
573 | * transitions to atomic, but it is deprecated. Instead @disable should | |
574 | * be used. | |
575 | */ | |
092d01da | 576 | void (*prepare)(struct drm_encoder *encoder); |
36b66080 DV |
577 | |
578 | /** | |
579 | * @commit: | |
580 | * | |
581 | * This callback should commit the new mode on the encoder after a modeset, | |
582 | * which in practice means the driver should enable the encoder. Most | |
583 | * drivers ended up implementing this by calling their @dpms hook with | |
584 | * DRM_MODE_DPMS_ON. | |
585 | * | |
586 | * This callback is used by the legacy CRTC helpers. Atomic helpers | |
587 | * also support using this hook for enabling an encoder to facilitate | |
588 | * transitions to atomic, but it is deprecated. Instead @enable should | |
589 | * be used. | |
590 | */ | |
092d01da | 591 | void (*commit)(struct drm_encoder *encoder); |
36b66080 DV |
592 | |
593 | /** | |
594 | * @mode_set: | |
595 | * | |
596 | * This callback is used to update the display mode of an encoder. | |
597 | * | |
598 | * Note that the display pipe is completely off when this function is | |
599 | * called. Drivers which need hardware to be running before they program | |
600 | * the new display mode (because they implement runtime PM) should not | |
601 | * use this hook, because the helper library calls it only once and not | |
602 | * every time the display pipeline is suspend using either DPMS or the | |
603 | * new "ACTIVE" property. Such drivers should instead move all their | |
6806cdf9 | 604 | * encoder setup into the @enable callback. |
36b66080 DV |
605 | * |
606 | * This callback is used both by the legacy CRTC helpers and the atomic | |
607 | * modeset helpers. It is optional in the atomic helpers. | |
fe4a11c9 PZ |
608 | * |
609 | * NOTE: | |
610 | * | |
611 | * If the driver uses the atomic modeset helpers and needs to inspect | |
612 | * the connector state or connector display info during mode setting, | |
613 | * @atomic_mode_set can be used instead. | |
36b66080 | 614 | */ |
092d01da DV |
615 | void (*mode_set)(struct drm_encoder *encoder, |
616 | struct drm_display_mode *mode, | |
617 | struct drm_display_mode *adjusted_mode); | |
36b66080 | 618 | |
fe4a11c9 PZ |
619 | /** |
620 | * @atomic_mode_set: | |
621 | * | |
622 | * This callback is used to update the display mode of an encoder. | |
623 | * | |
624 | * Note that the display pipe is completely off when this function is | |
625 | * called. Drivers which need hardware to be running before they program | |
626 | * the new display mode (because they implement runtime PM) should not | |
627 | * use this hook, because the helper library calls it only once and not | |
628 | * every time the display pipeline is suspended using either DPMS or the | |
629 | * new "ACTIVE" property. Such drivers should instead move all their | |
6806cdf9 | 630 | * encoder setup into the @enable callback. |
fe4a11c9 PZ |
631 | * |
632 | * This callback is used by the atomic modeset helpers in place of the | |
633 | * @mode_set callback, if set by the driver. It is optional and should | |
634 | * be used instead of @mode_set if the driver needs to inspect the | |
635 | * connector state or display info, since there is no direct way to | |
636 | * go from the encoder to the current connector. | |
637 | */ | |
638 | void (*atomic_mode_set)(struct drm_encoder *encoder, | |
639 | struct drm_crtc_state *crtc_state, | |
640 | struct drm_connector_state *conn_state); | |
641 | ||
36b66080 DV |
642 | /** |
643 | * @get_crtc: | |
644 | * | |
645 | * This callback is used by the legacy CRTC helpers to work around | |
646 | * deficiencies in its own book-keeping. | |
647 | * | |
648 | * Do not use, use atomic helpers instead, which get the book keeping | |
649 | * right. | |
650 | * | |
651 | * FIXME: | |
652 | * | |
653 | * Currently only nouveau is using this, and as soon as nouveau is | |
654 | * atomic we can ditch this hook. | |
655 | */ | |
092d01da | 656 | struct drm_crtc *(*get_crtc)(struct drm_encoder *encoder); |
36b66080 DV |
657 | |
658 | /** | |
659 | * @detect: | |
660 | * | |
661 | * This callback can be used by drivers who want to do detection on the | |
662 | * encoder object instead of in connector functions. | |
663 | * | |
664 | * It is not used by any helper and therefore has purely driver-specific | |
665 | * semantics. New drivers shouldn't use this and instead just implement | |
666 | * their own private callbacks. | |
667 | * | |
668 | * FIXME: | |
669 | * | |
670 | * This should just be converted into a pile of driver vfuncs. | |
671 | * Currently radeon, amdgpu and nouveau are using it. | |
672 | */ | |
092d01da DV |
673 | enum drm_connector_status (*detect)(struct drm_encoder *encoder, |
674 | struct drm_connector *connector); | |
36b66080 DV |
675 | |
676 | /** | |
677 | * @disable: | |
678 | * | |
679 | * This callback should be used to disable the encoder. With the atomic | |
680 | * drivers it is called before this encoder's CRTC has been shut off | |
6806cdf9 DV |
681 | * using their own &drm_crtc_helper_funcs.disable hook. If that |
682 | * sequence is too simple drivers can just add their own driver private | |
683 | * encoder hooks and call them from CRTC's callback by looping over all | |
684 | * encoders connected to it using for_each_encoder_on_crtc(). | |
36b66080 DV |
685 | * |
686 | * This hook is used both by legacy CRTC helpers and atomic helpers. | |
687 | * Atomic drivers don't need to implement it if there's no need to | |
688 | * disable anything at the encoder level. To ensure that runtime PM | |
689 | * handling (using either DPMS or the new "ACTIVE" property) works | |
690 | * @disable must be the inverse of @enable for atomic drivers. | |
691 | * | |
692 | * NOTE: | |
693 | * | |
694 | * With legacy CRTC helpers there's a big semantic difference between | |
695 | * @disable and other hooks (like @prepare or @dpms) used to shut down a | |
696 | * encoder: @disable is only called when also logically disabling the | |
697 | * display pipeline and needs to release any resources acquired in | |
698 | * @mode_set (like shared PLLs, or again release pinned framebuffers). | |
699 | * | |
700 | * Therefore @disable must be the inverse of @mode_set plus @commit for | |
701 | * drivers still using legacy CRTC helpers, which is different from the | |
702 | * rules under atomic. | |
703 | */ | |
092d01da DV |
704 | void (*disable)(struct drm_encoder *encoder); |
705 | ||
36b66080 DV |
706 | /** |
707 | * @enable: | |
708 | * | |
709 | * This callback should be used to enable the encoder. With the atomic | |
710 | * drivers it is called after this encoder's CRTC has been enabled using | |
6806cdf9 DV |
711 | * their own &drm_crtc_helper_funcs.enable hook. If that sequence is |
712 | * too simple drivers can just add their own driver private encoder | |
713 | * hooks and call them from CRTC's callback by looping over all encoders | |
714 | * connected to it using for_each_encoder_on_crtc(). | |
36b66080 DV |
715 | * |
716 | * This hook is used only by atomic helpers, for symmetry with @disable. | |
717 | * Atomic drivers don't need to implement it if there's no need to | |
718 | * enable anything at the encoder level. To ensure that runtime PM handling | |
719 | * (using either DPMS or the new "ACTIVE" property) works | |
720 | * @enable must be the inverse of @disable for atomic drivers. | |
721 | */ | |
092d01da DV |
722 | void (*enable)(struct drm_encoder *encoder); |
723 | ||
36b66080 DV |
724 | /** |
725 | * @atomic_check: | |
726 | * | |
727 | * This callback is used to validate encoder state for atomic drivers. | |
728 | * Since the encoder is the object connecting the CRTC and connector it | |
729 | * gets passed both states, to be able to validate interactions and | |
730 | * update the CRTC to match what the encoder needs for the requested | |
731 | * connector. | |
732 | * | |
9f800214 DV |
733 | * Since this provides a strict superset of the functionality of |
734 | * @mode_fixup (the requested and adjusted modes are both available | |
735 | * through the passed in &struct drm_crtc_state) @mode_fixup is not | |
736 | * called when @atomic_check is implemented. | |
737 | * | |
36b66080 DV |
738 | * This function is used by the atomic helpers, but it is optional. |
739 | * | |
740 | * NOTE: | |
741 | * | |
742 | * This function is called in the check phase of an atomic update. The | |
743 | * driver is not allowed to change anything outside of the free-standing | |
744 | * state objects passed-in or assembled in the overall &drm_atomic_state | |
745 | * update tracking structure. | |
746 | * | |
3eb220a5 JA |
747 | * Also beware that userspace can request its own custom modes, neither |
748 | * core nor helpers filter modes to the list of probe modes reported by | |
749 | * the GETCONNECTOR IOCTL and stored in &drm_connector.modes. To ensure | |
750 | * that modes are filtered consistently put any encoder constraints and | |
751 | * limits checks into @mode_valid. | |
752 | * | |
36b66080 DV |
753 | * RETURNS: |
754 | * | |
755 | * 0 on success, -EINVAL if the state or the transition can't be | |
756 | * supported, -ENOMEM on memory allocation failure and -EDEADLK if an | |
757 | * attempt to obtain another state object ran into a &drm_modeset_lock | |
758 | * deadlock. | |
759 | */ | |
092d01da DV |
760 | int (*atomic_check)(struct drm_encoder *encoder, |
761 | struct drm_crtc_state *crtc_state, | |
762 | struct drm_connector_state *conn_state); | |
763 | }; | |
764 | ||
765 | /** | |
36b66080 | 766 | * drm_encoder_helper_add - sets the helper vtable for an encoder |
092d01da DV |
767 | * @encoder: DRM encoder |
768 | * @funcs: helper vtable to set for @encoder | |
769 | */ | |
770 | static inline void drm_encoder_helper_add(struct drm_encoder *encoder, | |
771 | const struct drm_encoder_helper_funcs *funcs) | |
772 | { | |
773 | encoder->helper_private = funcs; | |
774 | } | |
775 | ||
776 | /** | |
777 | * struct drm_connector_helper_funcs - helper operations for connectors | |
092d01da | 778 | * |
4ee6034c DV |
779 | * These functions are used by the atomic and legacy modeset helpers and by the |
780 | * probe helpers. | |
092d01da DV |
781 | */ |
782 | struct drm_connector_helper_funcs { | |
4ee6034c DV |
783 | /** |
784 | * @get_modes: | |
785 | * | |
786 | * This function should fill in all modes currently valid for the sink | |
6806cdf9 | 787 | * into the &drm_connector.probed_modes list. It should also update the |
4ee6034c DV |
788 | * EDID property by calling drm_mode_connector_update_edid_property(). |
789 | * | |
790 | * The usual way to implement this is to cache the EDID retrieved in the | |
791 | * probe callback somewhere in the driver-private connector structure. | |
792 | * In this function drivers then parse the modes in the EDID and add | |
793 | * them by calling drm_add_edid_modes(). But connectors that driver a | |
794 | * fixed panel can also manually add specific modes using | |
df7d678b | 795 | * drm_mode_probed_add(). Drivers which manually add modes should also |
6806cdf9 DV |
796 | * make sure that the &drm_connector.display_info, |
797 | * &drm_connector.width_mm and &drm_connector.height_mm fields are | |
798 | * filled in. | |
df7d678b DV |
799 | * |
800 | * Virtual drivers that just want some standard VESA mode with a given | |
801 | * resolution can call drm_add_modes_noedid(), and mark the preferred | |
802 | * one using drm_set_preferred_mode(). | |
803 | * | |
804 | * Finally drivers that support audio probably want to update the ELD | |
805 | * data, too, using drm_edid_to_eld(). | |
4ee6034c | 806 | * |
6806cdf9 | 807 | * This function is only called after the @detect hook has indicated |
4ee6034c DV |
808 | * that a sink is connected and when the EDID isn't overridden through |
809 | * sysfs or the kernel commandline. | |
810 | * | |
811 | * This callback is used by the probe helpers in e.g. | |
812 | * drm_helper_probe_single_connector_modes(). | |
813 | * | |
6c5ed5ae ML |
814 | * To avoid races with concurrent connector state updates, the helper |
815 | * libraries always call this with the &drm_mode_config.connection_mutex | |
816 | * held. Because of this it's safe to inspect &drm_connector->state. | |
817 | * | |
4ee6034c DV |
818 | * RETURNS: |
819 | * | |
820 | * The number of modes added by calling drm_mode_probed_add(). | |
821 | */ | |
092d01da | 822 | int (*get_modes)(struct drm_connector *connector); |
4ee6034c | 823 | |
6c5ed5ae ML |
824 | /** |
825 | * @detect_ctx: | |
826 | * | |
827 | * Check to see if anything is attached to the connector. The parameter | |
828 | * force is set to false whilst polling, true when checking the | |
829 | * connector due to a user request. force can be used by the driver to | |
830 | * avoid expensive, destructive operations during automated probing. | |
831 | * | |
832 | * This callback is optional, if not implemented the connector will be | |
833 | * considered as always being attached. | |
834 | * | |
835 | * This is the atomic version of &drm_connector_funcs.detect. | |
836 | * | |
837 | * To avoid races against concurrent connector state updates, the | |
838 | * helper libraries always call this with ctx set to a valid context, | |
839 | * and &drm_mode_config.connection_mutex will always be locked with | |
840 | * the ctx parameter set to this ctx. This allows taking additional | |
841 | * locks as required. | |
842 | * | |
843 | * RETURNS: | |
844 | * | |
845 | * &drm_connector_status indicating the connector's status, | |
846 | * or the error code returned by drm_modeset_lock(), -EDEADLK. | |
847 | */ | |
848 | int (*detect_ctx)(struct drm_connector *connector, | |
849 | struct drm_modeset_acquire_ctx *ctx, | |
850 | bool force); | |
851 | ||
4ee6034c DV |
852 | /** |
853 | * @mode_valid: | |
854 | * | |
855 | * Callback to validate a mode for a connector, irrespective of the | |
856 | * specific display configuration. | |
857 | * | |
858 | * This callback is used by the probe helpers to filter the mode list | |
859 | * (which is usually derived from the EDID data block from the sink). | |
860 | * See e.g. drm_helper_probe_single_connector_modes(). | |
861 | * | |
3eb220a5 JA |
862 | * This function is optional. |
863 | * | |
4ee6034c DV |
864 | * NOTE: |
865 | * | |
866 | * This only filters the mode list supplied to userspace in the | |
3eb220a5 JA |
867 | * GETCONNECTOR IOCTL. Compared to &drm_encoder_helper_funcs.mode_valid, |
868 | * &drm_crtc_helper_funcs.mode_valid and &drm_bridge_funcs.mode_valid, | |
869 | * which are also called by the atomic helpers from | |
870 | * drm_atomic_helper_check_modeset(). This allows userspace to force and | |
871 | * ignore sink constraint (like the pixel clock limits in the screen's | |
872 | * EDID), which is useful for e.g. testing, or working around a broken | |
873 | * EDID. Any source hardware constraint (which always need to be | |
874 | * enforced) therefore should be checked in one of the above callbacks, | |
875 | * and not this one here. | |
4ee6034c | 876 | * |
6c5ed5ae ML |
877 | * To avoid races with concurrent connector state updates, the helper |
878 | * libraries always call this with the &drm_mode_config.connection_mutex | |
879 | * held. Because of this it's safe to inspect &drm_connector->state. | |
880 | * | |
4ee6034c DV |
881 | * RETURNS: |
882 | * | |
6806cdf9 DV |
883 | * Either &drm_mode_status.MODE_OK or one of the failure reasons in &enum |
884 | * drm_mode_status. | |
4ee6034c | 885 | */ |
092d01da DV |
886 | enum drm_mode_status (*mode_valid)(struct drm_connector *connector, |
887 | struct drm_display_mode *mode); | |
4ee6034c DV |
888 | /** |
889 | * @best_encoder: | |
890 | * | |
891 | * This function should select the best encoder for the given connector. | |
892 | * | |
893 | * This function is used by both the atomic helpers (in the | |
894 | * drm_atomic_helper_check_modeset() function) and in the legacy CRTC | |
895 | * helpers. | |
896 | * | |
897 | * NOTE: | |
898 | * | |
899 | * In atomic drivers this function is called in the check phase of an | |
900 | * atomic update. The driver is not allowed to change or inspect | |
901 | * anything outside of arguments passed-in. Atomic drivers which need to | |
902 | * inspect dynamic configuration state should instead use | |
903 | * @atomic_best_encoder. | |
904 | * | |
c61b93fe BB |
905 | * You can leave this function to NULL if the connector is only |
906 | * attached to a single encoder and you are using the atomic helpers. | |
907 | * In this case, the core will call drm_atomic_helper_best_encoder() | |
908 | * for you. | |
909 | * | |
4ee6034c DV |
910 | * RETURNS: |
911 | * | |
912 | * Encoder that should be used for the given connector and connector | |
913 | * state, or NULL if no suitable encoder exists. Note that the helpers | |
914 | * will ensure that encoders aren't used twice, drivers should not check | |
915 | * for this. | |
916 | */ | |
092d01da | 917 | struct drm_encoder *(*best_encoder)(struct drm_connector *connector); |
4ee6034c DV |
918 | |
919 | /** | |
920 | * @atomic_best_encoder: | |
921 | * | |
922 | * This is the atomic version of @best_encoder for atomic drivers which | |
923 | * need to select the best encoder depending upon the desired | |
924 | * configuration and can't select it statically. | |
925 | * | |
c61b93fe BB |
926 | * This function is used by drm_atomic_helper_check_modeset(). |
927 | * If it is not implemented, the core will fallback to @best_encoder | |
928 | * (or drm_atomic_helper_best_encoder() if @best_encoder is NULL). | |
4ee6034c DV |
929 | * |
930 | * NOTE: | |
931 | * | |
932 | * This function is called in the check phase of an atomic update. The | |
933 | * driver is not allowed to change anything outside of the free-standing | |
934 | * state objects passed-in or assembled in the overall &drm_atomic_state | |
935 | * update tracking structure. | |
936 | * | |
937 | * RETURNS: | |
938 | * | |
939 | * Encoder that should be used for the given connector and connector | |
940 | * state, or NULL if no suitable encoder exists. Note that the helpers | |
941 | * will ensure that encoders aren't used twice, drivers should not check | |
942 | * for this. | |
943 | */ | |
092d01da DV |
944 | struct drm_encoder *(*atomic_best_encoder)(struct drm_connector *connector, |
945 | struct drm_connector_state *connector_state); | |
ce09d766 ML |
946 | |
947 | /** | |
948 | * @atomic_check: | |
949 | * | |
950 | * This hook is used to validate connector state. This function is | |
951 | * called from &drm_atomic_helper_check_modeset, and is called when | |
952 | * a connector property is set, or a modeset on the crtc is forced. | |
953 | * | |
954 | * Because &drm_atomic_helper_check_modeset may be called multiple times, | |
955 | * this function should handle being called multiple times as well. | |
956 | * | |
957 | * This function is also allowed to inspect any other object's state and | |
958 | * can add more state objects to the atomic commit if needed. Care must | |
959 | * be taken though to ensure that state check and compute functions for | |
960 | * these added states are all called, and derived state in other objects | |
961 | * all updated. Again the recommendation is to just call check helpers | |
962 | * until a maximal configuration is reached. | |
963 | * | |
964 | * NOTE: | |
965 | * | |
966 | * This function is called in the check phase of an atomic update. The | |
967 | * driver is not allowed to change anything outside of the free-standing | |
968 | * state objects passed-in or assembled in the overall &drm_atomic_state | |
969 | * update tracking structure. | |
970 | * | |
971 | * RETURNS: | |
972 | * | |
973 | * 0 on success, -EINVAL if the state or the transition can't be | |
974 | * supported, -ENOMEM on memory allocation failure and -EDEADLK if an | |
975 | * attempt to obtain another state object ran into a &drm_modeset_lock | |
976 | * deadlock. | |
977 | */ | |
978 | int (*atomic_check)(struct drm_connector *connector, | |
979 | struct drm_connector_state *state); | |
092d01da DV |
980 | }; |
981 | ||
982 | /** | |
983 | * drm_connector_helper_add - sets the helper vtable for a connector | |
984 | * @connector: DRM connector | |
985 | * @funcs: helper vtable to set for @connector | |
986 | */ | |
987 | static inline void drm_connector_helper_add(struct drm_connector *connector, | |
988 | const struct drm_connector_helper_funcs *funcs) | |
989 | { | |
990 | connector->helper_private = funcs; | |
991 | } | |
992 | ||
993 | /** | |
11a0ba97 | 994 | * struct drm_plane_helper_funcs - helper operations for planes |
092d01da | 995 | * |
11a0ba97 DV |
996 | * These functions are used by the atomic helpers and by the transitional plane |
997 | * helpers. | |
092d01da DV |
998 | */ |
999 | struct drm_plane_helper_funcs { | |
11a0ba97 DV |
1000 | /** |
1001 | * @prepare_fb: | |
1002 | * | |
1003 | * This hook is to prepare a framebuffer for scanout by e.g. pinning | |
1004 | * it's backing storage or relocating it into a contiguous block of | |
1005 | * VRAM. Other possible preparatory work includes flushing caches. | |
1006 | * | |
1007 | * This function must not block for outstanding rendering, since it is | |
1008 | * called in the context of the atomic IOCTL even for async commits to | |
1009 | * be able to return any errors to userspace. Instead the recommended | |
1010 | * way is to fill out the fence member of the passed-in | |
1011 | * &drm_plane_state. If the driver doesn't support native fences then | |
1012 | * equivalent functionality should be implemented through private | |
1013 | * members in the plane structure. | |
1014 | * | |
1015 | * The helpers will call @cleanup_fb with matching arguments for every | |
1016 | * successful call to this hook. | |
1017 | * | |
1018 | * This callback is used by the atomic modeset helpers and by the | |
1019 | * transitional plane helpers, but it is optional. | |
1020 | * | |
1021 | * RETURNS: | |
1022 | * | |
1023 | * 0 on success or one of the following negative error codes allowed by | |
6806cdf9 | 1024 | * the &drm_mode_config_funcs.atomic_commit vfunc. When using helpers |
11a0ba97 DV |
1025 | * this callback is the only one which can fail an atomic commit, |
1026 | * everything else must complete successfully. | |
1027 | */ | |
092d01da | 1028 | int (*prepare_fb)(struct drm_plane *plane, |
1832040d | 1029 | struct drm_plane_state *new_state); |
11a0ba97 DV |
1030 | /** |
1031 | * @cleanup_fb: | |
1032 | * | |
1033 | * This hook is called to clean up any resources allocated for the given | |
1034 | * framebuffer and plane configuration in @prepare_fb. | |
1035 | * | |
1036 | * This callback is used by the atomic modeset helpers and by the | |
1037 | * transitional plane helpers, but it is optional. | |
1038 | */ | |
092d01da | 1039 | void (*cleanup_fb)(struct drm_plane *plane, |
1832040d | 1040 | struct drm_plane_state *old_state); |
092d01da | 1041 | |
11a0ba97 DV |
1042 | /** |
1043 | * @atomic_check: | |
1044 | * | |
1045 | * Drivers should check plane specific constraints in this hook. | |
1046 | * | |
6806cdf9 | 1047 | * When using drm_atomic_helper_check_planes() plane's @atomic_check |
11a0ba97 DV |
1048 | * hooks are called before the ones for CRTCs, which allows drivers to |
1049 | * request shared resources that the CRTC controls here. For more | |
1050 | * complicated dependencies the driver can call the provided check helpers | |
1051 | * multiple times until the computed state has a final configuration and | |
1052 | * everything has been checked. | |
1053 | * | |
1054 | * This function is also allowed to inspect any other object's state and | |
1055 | * can add more state objects to the atomic commit if needed. Care must | |
6806cdf9 | 1056 | * be taken though to ensure that state check and compute functions for |
11a0ba97 DV |
1057 | * these added states are all called, and derived state in other objects |
1058 | * all updated. Again the recommendation is to just call check helpers | |
1059 | * until a maximal configuration is reached. | |
1060 | * | |
1061 | * This callback is used by the atomic modeset helpers and by the | |
1062 | * transitional plane helpers, but it is optional. | |
1063 | * | |
1064 | * NOTE: | |
1065 | * | |
1066 | * This function is called in the check phase of an atomic update. The | |
1067 | * driver is not allowed to change anything outside of the free-standing | |
1068 | * state objects passed-in or assembled in the overall &drm_atomic_state | |
1069 | * update tracking structure. | |
1070 | * | |
1071 | * RETURNS: | |
1072 | * | |
1073 | * 0 on success, -EINVAL if the state or the transition can't be | |
1074 | * supported, -ENOMEM on memory allocation failure and -EDEADLK if an | |
1075 | * attempt to obtain another state object ran into a &drm_modeset_lock | |
1076 | * deadlock. | |
1077 | */ | |
092d01da DV |
1078 | int (*atomic_check)(struct drm_plane *plane, |
1079 | struct drm_plane_state *state); | |
11a0ba97 DV |
1080 | |
1081 | /** | |
1082 | * @atomic_update: | |
1083 | * | |
1084 | * Drivers should use this function to update the plane state. This | |
6806cdf9 DV |
1085 | * hook is called in-between the &drm_crtc_helper_funcs.atomic_begin and |
1086 | * drm_crtc_helper_funcs.atomic_flush callbacks. | |
11a0ba97 DV |
1087 | * |
1088 | * Note that the power state of the display pipe when this function is | |
1089 | * called depends upon the exact helpers and calling sequence the driver | |
0dc9967d SA |
1090 | * has picked. See drm_atomic_helper_commit_planes() for a discussion of |
1091 | * the tradeoffs and variants of plane commit helpers. | |
11a0ba97 DV |
1092 | * |
1093 | * This callback is used by the atomic modeset helpers and by the | |
1094 | * transitional plane helpers, but it is optional. | |
1095 | */ | |
092d01da DV |
1096 | void (*atomic_update)(struct drm_plane *plane, |
1097 | struct drm_plane_state *old_state); | |
11a0ba97 DV |
1098 | /** |
1099 | * @atomic_disable: | |
1100 | * | |
1101 | * Drivers should use this function to unconditionally disable a plane. | |
6806cdf9 DV |
1102 | * This hook is called in-between the |
1103 | * &drm_crtc_helper_funcs.atomic_begin and | |
1104 | * drm_crtc_helper_funcs.atomic_flush callbacks. It is an alternative to | |
11a0ba97 DV |
1105 | * @atomic_update, which will be called for disabling planes, too, if |
1106 | * the @atomic_disable hook isn't implemented. | |
1107 | * | |
1108 | * This hook is also useful to disable planes in preparation of a modeset, | |
1109 | * by calling drm_atomic_helper_disable_planes_on_crtc() from the | |
6806cdf9 | 1110 | * &drm_crtc_helper_funcs.disable hook. |
11a0ba97 DV |
1111 | * |
1112 | * Note that the power state of the display pipe when this function is | |
1113 | * called depends upon the exact helpers and calling sequence the driver | |
0dc9967d SA |
1114 | * has picked. See drm_atomic_helper_commit_planes() for a discussion of |
1115 | * the tradeoffs and variants of plane commit helpers. | |
11a0ba97 DV |
1116 | * |
1117 | * This callback is used by the atomic modeset helpers and by the | |
1118 | * transitional plane helpers, but it is optional. | |
1119 | */ | |
092d01da DV |
1120 | void (*atomic_disable)(struct drm_plane *plane, |
1121 | struct drm_plane_state *old_state); | |
fef9df8b GP |
1122 | |
1123 | /** | |
1124 | * @atomic_async_check: | |
1125 | * | |
1126 | * Drivers should set this function pointer to check if the plane state | |
1127 | * can be updated in a async fashion. Here async means "not vblank | |
1128 | * synchronized". | |
1129 | * | |
1130 | * This hook is called by drm_atomic_async_check() to establish if a | |
1131 | * given update can be committed asynchronously, that is, if it can | |
1132 | * jump ahead of the state currently queued for update. | |
1133 | * | |
1134 | * RETURNS: | |
1135 | * | |
1136 | * Return 0 on success and any error returned indicates that the update | |
1137 | * can not be applied in asynchronous manner. | |
1138 | */ | |
1139 | int (*atomic_async_check)(struct drm_plane *plane, | |
1140 | struct drm_plane_state *state); | |
1141 | ||
1142 | /** | |
1143 | * @atomic_async_update: | |
1144 | * | |
1145 | * Drivers should set this function pointer to perform asynchronous | |
1146 | * updates of planes, that is, jump ahead of the currently queued | |
1147 | * state and update the plane. Here async means "not vblank | |
1148 | * synchronized". | |
1149 | * | |
1150 | * This hook is called by drm_atomic_helper_async_commit(). | |
1151 | * | |
1152 | * An async update will happen on legacy cursor updates. An async | |
1153 | * update won't happen if there is an outstanding commit modifying | |
1154 | * the same plane. | |
1155 | * | |
1156 | * Note that unlike &drm_plane_helper_funcs.atomic_update this hook | |
1157 | * takes the new &drm_plane_state as parameter. When doing async_update | |
1158 | * drivers shouldn't replace the &drm_plane_state but update the | |
1159 | * current one with the new plane configurations in the new | |
1160 | * plane_state. | |
1161 | * | |
1162 | * FIXME: | |
1163 | * - It only works for single plane updates | |
1164 | * - Async Pageflips are not supported yet | |
1165 | * - Some hw might still scan out the old buffer until the next | |
c92883a6 DV |
1166 | * vblank, however we let go of the fb references as soon as |
1167 | * we run this hook. For now drivers must implement their own workers | |
1168 | * for deferring if needed, until a common solution is created. | |
fef9df8b GP |
1169 | */ |
1170 | void (*atomic_async_update)(struct drm_plane *plane, | |
1171 | struct drm_plane_state *new_state); | |
092d01da DV |
1172 | }; |
1173 | ||
1174 | /** | |
1175 | * drm_plane_helper_add - sets the helper vtable for a plane | |
1176 | * @plane: DRM plane | |
1177 | * @funcs: helper vtable to set for @plane | |
1178 | */ | |
1179 | static inline void drm_plane_helper_add(struct drm_plane *plane, | |
1180 | const struct drm_plane_helper_funcs *funcs) | |
1181 | { | |
1182 | plane->helper_private = funcs; | |
1183 | } | |
1184 | ||
9f2a7950 DV |
1185 | /** |
1186 | * struct drm_mode_config_helper_funcs - global modeset helper operations | |
1187 | * | |
1188 | * These helper functions are used by the atomic helpers. | |
1189 | */ | |
1190 | struct drm_mode_config_helper_funcs { | |
1191 | /** | |
1192 | * @atomic_commit_tail: | |
1193 | * | |
1194 | * This hook is used by the default atomic_commit() hook implemented in | |
1195 | * drm_atomic_helper_commit() together with the nonblocking commit | |
1196 | * helpers (see drm_atomic_helper_setup_commit() for a starting point) | |
1197 | * to implement blocking and nonblocking commits easily. It is not used | |
1198 | * by the atomic helpers | |
1199 | * | |
1ea0c02e DV |
1200 | * This function is called when the new atomic state has already been |
1201 | * swapped into the various state pointers. The passed in state | |
1202 | * therefore contains copies of the old/previous state. This hook should | |
1203 | * commit the new state into hardware. Note that the helpers have | |
1204 | * already waited for preceeding atomic commits and fences, but drivers | |
1205 | * can add more waiting calls at the start of their implementation, e.g. | |
1206 | * to wait for driver-internal request for implicit syncing, before | |
1207 | * starting to commit the update to the hardware. | |
9f2a7950 DV |
1208 | * |
1209 | * After the atomic update is committed to the hardware this hook needs | |
1210 | * to call drm_atomic_helper_commit_hw_done(). Then wait for the upate | |
1211 | * to be executed by the hardware, for example using | |
01086487 BB |
1212 | * drm_atomic_helper_wait_for_vblanks() or |
1213 | * drm_atomic_helper_wait_for_flip_done(), and then clean up the old | |
9f2a7950 DV |
1214 | * framebuffers using drm_atomic_helper_cleanup_planes(). |
1215 | * | |
1216 | * When disabling a CRTC this hook _must_ stall for the commit to | |
1217 | * complete. Vblank waits don't work on disabled CRTC, hence the core | |
1218 | * can't take care of this. And it also can't rely on the vblank event, | |
1219 | * since that can be signalled already when the screen shows black, | |
1220 | * which can happen much earlier than the last hardware access needed to | |
1221 | * shut off the display pipeline completely. | |
1222 | * | |
1223 | * This hook is optional, the default implementation is | |
1224 | * drm_atomic_helper_commit_tail(). | |
1225 | */ | |
1226 | void (*atomic_commit_tail)(struct drm_atomic_state *state); | |
1227 | }; | |
1228 | ||
092d01da | 1229 | #endif |