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>
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:
17 * The above copyright notice and this permission notice shall be included in
18 * all copies or substantial portions of the Software.
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.
29 #ifndef __DRM_MODESET_HELPER_VTABLES_H__
30 #define __DRM_MODESET_HELPER_VTABLES_H__
32 #include <drm/drm_crtc.h>
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.
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
47 * To make this clear all the helper vtables are pulled together in this location here.
53 * struct drm_crtc_helper_funcs - helper operations for CRTCs
54 * @dpms: set power state
55 * @prepare: prepare the CRTC, called before @mode_set
56 * @commit: commit changes to CRTC, called after @mode_set
57 * @mode_fixup: try to fixup proposed mode for this CRTC
58 * @mode_set: set this mode
59 * @mode_set_nofb: set mode only (no scanout buffer attached)
60 * @mode_set_base: update the scanout buffer
61 * @mode_set_base_atomic: non-blocking mode set (used for kgdb support)
62 * @load_lut: load color palette
63 * @disable: disable CRTC when no longer in use
64 * @enable: enable CRTC
66 * The helper operations are called by the mid-layer CRTC helper.
68 * Note that with atomic helpers @dpms, @prepare and @commit hooks are
69 * deprecated. Used @enable and @disable instead exclusively.
71 * With legacy crtc helpers there's a big semantic difference between @disable
72 * and the other hooks: @disable also needs to release any resources acquired in
73 * @mode_set (like shared PLLs).
75 struct drm_crtc_helper_funcs
{
77 * Control power levels on the CRTC. If the mode passed in is
78 * unsupported, the provider must use the next lowest power level.
80 void (*dpms
)(struct drm_crtc
*crtc
, int mode
);
81 void (*prepare
)(struct drm_crtc
*crtc
);
82 void (*commit
)(struct drm_crtc
*crtc
);
84 /* Provider can fixup or change mode timings before modeset occurs */
85 bool (*mode_fixup
)(struct drm_crtc
*crtc
,
86 const struct drm_display_mode
*mode
,
87 struct drm_display_mode
*adjusted_mode
);
88 /* Actually set the mode */
89 int (*mode_set
)(struct drm_crtc
*crtc
, struct drm_display_mode
*mode
,
90 struct drm_display_mode
*adjusted_mode
, int x
, int y
,
91 struct drm_framebuffer
*old_fb
);
92 /* Actually set the mode for atomic helpers, optional */
93 void (*mode_set_nofb
)(struct drm_crtc
*crtc
);
95 /* Move the crtc on the current fb to the given position *optional* */
96 int (*mode_set_base
)(struct drm_crtc
*crtc
, int x
, int y
,
97 struct drm_framebuffer
*old_fb
);
98 int (*mode_set_base_atomic
)(struct drm_crtc
*crtc
,
99 struct drm_framebuffer
*fb
, int x
, int y
,
100 enum mode_set_atomic
);
102 /* reload the current crtc LUT */
103 void (*load_lut
)(struct drm_crtc
*crtc
);
105 void (*disable
)(struct drm_crtc
*crtc
);
106 void (*enable
)(struct drm_crtc
*crtc
);
111 * Drivers should check plane-update related CRTC constraints in this
112 * hook. They can also check mode related limitations but need to be
113 * aware of the calling order, since this hook is used by
114 * drm_atomic_helper_check_planes() whereas the preparations needed to
115 * check output routing and the display mode is done in
116 * drm_atomic_helper_check_modeset(). Therefore drivers that want to
117 * check output routing and display mode constraints in this callback
118 * must ensure that drm_atomic_helper_check_modeset() has been called
119 * beforehand. This is calling order used by the default helper
120 * implementation in drm_atomic_helper_check().
122 * When using drm_atomic_helper_check_planes() CRTCs' ->atomic_check()
123 * hooks are called after the ones for planes, which allows drivers to
124 * assign shared resources requested by planes in the CRTC callback
125 * here. For more complicated dependencies the driver can call the provided
126 * check helpers multiple times until the computed state has a final
127 * configuration and everything has been checked.
129 * This function is also allowed to inspect any other object's state and
130 * can add more state objects to the atomic commit if needed. Care must
131 * be taken though to ensure that state check&compute functions for
132 * these added states are all called, and derived state in other objects
133 * all updated. Again the recommendation is to just call check helpers
134 * until a maximal configuration is reached.
136 * This callback is used by the atomic modeset helpers and by the
137 * transitional plane helpers, but it is optional.
141 * This function is called in the check phase of an atomic update. The
142 * driver is not allowed to change anything outside of the free-standing
143 * state objects passed-in or assembled in the overall &drm_atomic_state
144 * update tracking structure.
148 * 0 on success, -EINVAL if the state or the transition can't be
149 * supported, -ENOMEM on memory allocation failure and -EDEADLK if an
150 * attempt to obtain another state object ran into a &drm_modeset_lock
153 int (*atomic_check
)(struct drm_crtc
*crtc
,
154 struct drm_crtc_state
*state
);
159 * Drivers should prepare for an atomic update of multiple planes on
160 * a CRTC in this hook. Depending upon hardware this might be vblank
161 * evasion, blocking updates by setting bits or doing preparatory work
162 * for e.g. manual update display.
164 * This hook is called before any plane commit functions are called.
166 * Note that the power state of the display pipe when this function is
167 * called depends upon the exact helpers and calling sequence the driver
168 * has picked. See drm_atomic_commit_planes() for a discussion of the
169 * tradeoffs and variants of plane commit helpers.
171 * This callback is used by the atomic modeset helpers and by the
172 * transitional plane helpers, but it is optional.
174 void (*atomic_begin
)(struct drm_crtc
*crtc
,
175 struct drm_crtc_state
*old_crtc_state
);
179 * Drivers should finalize an atomic update of multiple planes on
180 * a CRTC in this hook. Depending upon hardware this might include
181 * checking that vblank evasion was successful, unblocking updates by
182 * setting bits or setting the GO bit to flush out all updates.
184 * Simple hardware or hardware with special requirements can commit and
185 * flush out all updates for all planes from this hook and forgo all the
186 * other commit hooks for plane updates.
188 * This hook is called after any plane commit functions are called.
190 * Note that the power state of the display pipe when this function is
191 * called depends upon the exact helpers and calling sequence the driver
192 * has picked. See drm_atomic_commit_planes() for a discussion of the
193 * tradeoffs and variants of plane commit helpers.
195 * This callback is used by the atomic modeset helpers and by the
196 * transitional plane helpers, but it is optional.
198 void (*atomic_flush
)(struct drm_crtc
*crtc
,
199 struct drm_crtc_state
*old_crtc_state
);
203 * drm_crtc_helper_add - sets the helper vtable for a crtc
205 * @funcs: helper vtable to set for @crtc
207 static inline void drm_crtc_helper_add(struct drm_crtc
*crtc
,
208 const struct drm_crtc_helper_funcs
*funcs
)
210 crtc
->helper_private
= funcs
;
214 * struct drm_encoder_helper_funcs - helper operations for encoders
215 * @dpms: set power state
216 * @mode_fixup: try to fixup proposed mode for this connector
217 * @prepare: part of the disable sequence, called before the CRTC modeset
218 * @commit: called after the CRTC modeset
219 * @mode_set: set this mode, optional for atomic helpers
220 * @get_crtc: return CRTC that the encoder is currently attached to
221 * @detect: connection status detection
222 * @disable: disable encoder when not in use (overrides DPMS off)
223 * @enable: enable encoder
224 * @atomic_check: check for validity of an atomic update
226 * The helper operations are called by the mid-layer CRTC helper.
228 * Note that with atomic helpers @dpms, @prepare and @commit hooks are
229 * deprecated. Used @enable and @disable instead exclusively.
231 * With legacy crtc helpers there's a big semantic difference between @disable
232 * and the other hooks: @disable also needs to release any resources acquired in
233 * @mode_set (like shared PLLs).
235 struct drm_encoder_helper_funcs
{
236 void (*dpms
)(struct drm_encoder
*encoder
, int mode
);
238 bool (*mode_fixup
)(struct drm_encoder
*encoder
,
239 const struct drm_display_mode
*mode
,
240 struct drm_display_mode
*adjusted_mode
);
241 void (*prepare
)(struct drm_encoder
*encoder
);
242 void (*commit
)(struct drm_encoder
*encoder
);
243 void (*mode_set
)(struct drm_encoder
*encoder
,
244 struct drm_display_mode
*mode
,
245 struct drm_display_mode
*adjusted_mode
);
246 struct drm_crtc
*(*get_crtc
)(struct drm_encoder
*encoder
);
247 /* detect for DAC style encoders */
248 enum drm_connector_status (*detect
)(struct drm_encoder
*encoder
,
249 struct drm_connector
*connector
);
250 void (*disable
)(struct drm_encoder
*encoder
);
252 void (*enable
)(struct drm_encoder
*encoder
);
255 int (*atomic_check
)(struct drm_encoder
*encoder
,
256 struct drm_crtc_state
*crtc_state
,
257 struct drm_connector_state
*conn_state
);
261 * drm_encoder_helper_add - sets the helper vtable for a encoder
262 * @encoder: DRM encoder
263 * @funcs: helper vtable to set for @encoder
265 static inline void drm_encoder_helper_add(struct drm_encoder
*encoder
,
266 const struct drm_encoder_helper_funcs
*funcs
)
268 encoder
->helper_private
= funcs
;
272 * struct drm_connector_helper_funcs - helper operations for connectors
273 * @get_modes: get mode list for this connector
274 * @mode_valid: is this mode valid on the given connector? (optional)
275 * @best_encoder: return the preferred encoder for this connector
276 * @atomic_best_encoder: atomic version of @best_encoder
278 * The helper operations are called by the mid-layer CRTC helper.
280 struct drm_connector_helper_funcs
{
281 int (*get_modes
)(struct drm_connector
*connector
);
282 enum drm_mode_status (*mode_valid
)(struct drm_connector
*connector
,
283 struct drm_display_mode
*mode
);
284 struct drm_encoder
*(*best_encoder
)(struct drm_connector
*connector
);
285 struct drm_encoder
*(*atomic_best_encoder
)(struct drm_connector
*connector
,
286 struct drm_connector_state
*connector_state
);
290 * drm_connector_helper_add - sets the helper vtable for a connector
291 * @connector: DRM connector
292 * @funcs: helper vtable to set for @connector
294 static inline void drm_connector_helper_add(struct drm_connector
*connector
,
295 const struct drm_connector_helper_funcs
*funcs
)
297 connector
->helper_private
= funcs
;
301 * struct drm_plane_helper_funcs - helper operations for planes
303 * These functions are used by the atomic helpers and by the transitional plane
306 struct drm_plane_helper_funcs
{
310 * This hook is to prepare a framebuffer for scanout by e.g. pinning
311 * it's backing storage or relocating it into a contiguous block of
312 * VRAM. Other possible preparatory work includes flushing caches.
314 * This function must not block for outstanding rendering, since it is
315 * called in the context of the atomic IOCTL even for async commits to
316 * be able to return any errors to userspace. Instead the recommended
317 * way is to fill out the fence member of the passed-in
318 * &drm_plane_state. If the driver doesn't support native fences then
319 * equivalent functionality should be implemented through private
320 * members in the plane structure.
322 * The helpers will call @cleanup_fb with matching arguments for every
323 * successful call to this hook.
325 * This callback is used by the atomic modeset helpers and by the
326 * transitional plane helpers, but it is optional.
330 * 0 on success or one of the following negative error codes allowed by
331 * the atomic_commit hook in &drm_mode_config_funcs. When using helpers
332 * this callback is the only one which can fail an atomic commit,
333 * everything else must complete successfully.
335 int (*prepare_fb
)(struct drm_plane
*plane
,
336 const struct drm_plane_state
*new_state
);
340 * This hook is called to clean up any resources allocated for the given
341 * framebuffer and plane configuration in @prepare_fb.
343 * This callback is used by the atomic modeset helpers and by the
344 * transitional plane helpers, but it is optional.
346 void (*cleanup_fb
)(struct drm_plane
*plane
,
347 const struct drm_plane_state
*old_state
);
352 * Drivers should check plane specific constraints in this hook.
354 * When using drm_atomic_helper_check_planes() plane's ->atomic_check()
355 * hooks are called before the ones for CRTCs, which allows drivers to
356 * request shared resources that the CRTC controls here. For more
357 * complicated dependencies the driver can call the provided check helpers
358 * multiple times until the computed state has a final configuration and
359 * everything has been checked.
361 * This function is also allowed to inspect any other object's state and
362 * can add more state objects to the atomic commit if needed. Care must
363 * be taken though to ensure that state check&compute functions for
364 * these added states are all called, and derived state in other objects
365 * all updated. Again the recommendation is to just call check helpers
366 * until a maximal configuration is reached.
368 * This callback is used by the atomic modeset helpers and by the
369 * transitional plane helpers, but it is optional.
373 * This function is called in the check phase of an atomic update. The
374 * driver is not allowed to change anything outside of the free-standing
375 * state objects passed-in or assembled in the overall &drm_atomic_state
376 * update tracking structure.
380 * 0 on success, -EINVAL if the state or the transition can't be
381 * supported, -ENOMEM on memory allocation failure and -EDEADLK if an
382 * attempt to obtain another state object ran into a &drm_modeset_lock
385 int (*atomic_check
)(struct drm_plane
*plane
,
386 struct drm_plane_state
*state
);
391 * Drivers should use this function to update the plane state. This
392 * hook is called in-between the ->atomic_begin() and
393 * ->atomic_flush() of &drm_crtc_helper_funcs.
395 * Note that the power state of the display pipe when this function is
396 * called depends upon the exact helpers and calling sequence the driver
397 * has picked. See drm_atomic_commit_planes() for a discussion of the
398 * tradeoffs and variants of plane commit helpers.
400 * This callback is used by the atomic modeset helpers and by the
401 * transitional plane helpers, but it is optional.
403 void (*atomic_update
)(struct drm_plane
*plane
,
404 struct drm_plane_state
*old_state
);
408 * Drivers should use this function to unconditionally disable a plane.
409 * This hook is called in-between the ->atomic_begin() and
410 * ->atomic_flush() of &drm_crtc_helper_funcs. It is an alternative to
411 * @atomic_update, which will be called for disabling planes, too, if
412 * the @atomic_disable hook isn't implemented.
414 * This hook is also useful to disable planes in preparation of a modeset,
415 * by calling drm_atomic_helper_disable_planes_on_crtc() from the
416 * ->disable() hook in &drm_crtc_helper_funcs.
418 * Note that the power state of the display pipe when this function is
419 * called depends upon the exact helpers and calling sequence the driver
420 * has picked. See drm_atomic_commit_planes() for a discussion of the
421 * tradeoffs and variants of plane commit helpers.
423 * This callback is used by the atomic modeset helpers and by the
424 * transitional plane helpers, but it is optional.
426 void (*atomic_disable
)(struct drm_plane
*plane
,
427 struct drm_plane_state
*old_state
);
431 * drm_plane_helper_add - sets the helper vtable for a plane
433 * @funcs: helper vtable to set for @plane
435 static inline void drm_plane_helper_add(struct drm_plane
*plane
,
436 const struct drm_plane_helper_funcs
*funcs
)
438 plane
->helper_private
= funcs
;