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