include/drm/drm_modeset_helper_vtables.h

3  * Copyright © 2007-2008 Dave Airlie
4  * Copyright © 2007-2008 Intel Corporation
6  * Copyright © 2011-2013 Intel Corporation
60  * struct drm_crtc_helper_funcs - helper operations for CRTCs
74 	 * This callback is also used to disable a CRTC by calling it with
75 	 * DRM_MODE_DPMS_OFF if the @disable hook isn't used.
88 	 * in practice means the driver should disable the CRTC if it is
119 	 * restriction in the modes it can display. For example, a given crtc
120 	 * may be responsible to set a clock value. If the clock can not
122 	 * can be used to restrict the number of modes to only the ones that
123 	 * can be displayed.
136 	 * to look at anything else but the passed-in mode, and validate it
137 	 * against configuration-invariant hardward constraints. Any further
138 	 * limits which depend upon the configuration can only be checked in
165 	 * can be aborted for any reason (including on userspace's request to
180 	 * Also beware that userspace can request its own custom modes, neither
201 	 * since it can't update other planes it's incompatible with atomic
240 	 * optimized fast-path instead of a full mode set operation with all the
243 	 * the @mode_set callback. Since it can't update other planes it's
274 	 * @disable:
276 	 * This callback should be used to disable the CRTC. With the atomic
279 	 * &drm_encoder_helper_funcs.disable hook. If that sequence is too
280 	 * simple drivers can just add their own hooks and call it from this
286 	 * disable anything at the CRTC level. To ensure that runtime PM
288 	 * @disable must be the inverse of @atomic_enable for atomic drivers.
295 	 * @disable and other hooks (like @prepare or @dpms) used to shut down a
296 	 * CRTC: @disable is only called when also logically disabling the
300 	 * Therefore @disable must be the inverse of @mode_set plus @commit for
304 	void (*disable)(struct drm_crtc *crtc);  member
309 	 * Drivers should check plane-update related CRTC constraints in this
310 	 * hook. They can also check mode related limitations but need to be
323 	 * callback here. For more complicated dependencies the driver can call
328 	 * can add more state objects to the atomic commit if needed. Care must
340 	 * driver is not allowed to change anything outside of the free-standing
341 	 * state object passed-in.
343 	 * Also beware that userspace can request its own custom modes, neither
351 	 * 0 on success, -EINVAL if the state or the transition can't be
352 	 * supported, -ENOMEM on memory allocation failure and -EDEADLK if an
387 	 * Simple hardware or hardware with special requirements can commit and
410 	 * hook.  If that sequence is too simple drivers can just add their own
429 	 * This callback should be used to disable the CRTC. With the atomic
432 	 * &drm_encoder_helper_funcs.disable hook. If that sequence is too
433 	 * simple drivers can just add their own hooks and call it from this
438 	 * need to implement it if there's no need to disable anything at the
463 	 *     need to apply some workarounds for gpu-specific vblank irq
471 	 *     scanout position query. Can be NULL to skip timestamp.
474 	 *     scanout position query. Can be NULL to skip timestamp.
480 	 * of scanlines to go until end of vblank, e.g., -1 means "one scanline
495  * drm_crtc_helper_add - sets the helper vtable for a crtc
502 	crtc->helper_private = funcs;  in drm_crtc_helper_add()
506  * struct drm_encoder_helper_funcs - helper operations for encoders
520 	 * This callback is also used to disable an encoder by calling it with
521 	 * DRM_MODE_DPMS_OFF if the @disable hook isn't used.
526 	 * @enable and @disable should be used.
535 	 * of restriction in the modes it can display. For example, a given
536 	 * encoder may be responsible to set a clock value. If the clock can
538 	 * can be used to restrict the number of modes to only the ones that
539 	 * can be displayed.
552 	 * to look at anything else but the passed-in mode, and validate it
553 	 * against configuration-invariant hardward constraints. Any further
554 	 * limits which depend upon the configuration can only be checked in
571 	 * can be modified by this callback and does not need to match mode. See
580 	 * can be aborted for any reason (including on userspace's request to
593 	 * Also beware that userspace can request its own custom modes, neither
612 	 * which in practice means the driver should disable the encoder if it
618 	 * transitions to atomic, but it is deprecated. Instead @disable should
658 	 * @atomic_mode_set can be used instead.
690 	 * This callback can be used by drivers who want to do detection on the
693 	 * It is not used by any helper and therefore has purely driver-specific
708 	 * This callback should be used to disable the encoder. With the atomic
711 	 * sequence is too simple drivers can just add their own driver private
715 	 * This callback is a variant of @disable that provides the atomic state
716 	 * to the driver. If @atomic_disable is implemented, @disable is not
720 	 * to implement it if there's no need to disable anything at the encoder
734 	 * too simple drivers can just add their own driver private encoder
752 	 * @disable:
754 	 * This callback should be used to disable the encoder. With the atomic
756 	 * using their own &drm_crtc_helper_funcs.disable hook.  If that
757 	 * sequence is too simple drivers can just add their own driver private
763 	 * disable anything at the encoder level. To ensure that runtime PM
765 	 * @disable must be the inverse of @enable for atomic drivers.
773 	 * @disable and other hooks (like @prepare or @dpms) used to shut down a
774 	 * encoder: @disable is only called when also logically disabling the
778 	 * Therefore @disable must be the inverse of @mode_set plus @commit for
782 	void (*disable)(struct drm_encoder *encoder);  member
790 	 * too simple drivers can just add their own driver private encoder
795 	 * @disable. Atomic drivers don't need to implement it if there's no
798 	 * works @enable must be the inverse of @disable for atomic drivers.
821 	 * driver is not allowed to change anything outside of the free-standing
822 	 * state objects passed-in or assembled in the overall &drm_atomic_state
825 	 * Also beware that userspace can request its own custom modes, neither
833 	 * 0 on success, -EINVAL if the state or the transition can't be
834 	 * supported, -ENOMEM on memory allocation failure and -EDEADLK if an
844  * drm_encoder_helper_add - sets the helper vtable for an encoder
851 	encoder->helper_private = funcs;  in drm_encoder_helper_add()
855  * struct drm_connector_helper_funcs - helper operations for connectors
869 	 * probe callback somewhere in the driver-private connector structure.
872 	 * fixed panel can also manually add specific modes using
885 	 * resolution can call drm_add_modes_noedid(), and mark the preferred
897 	 * held. Because of this it's safe to inspect &drm_connector->state.
911 	 * connector due to a user request. force can be used by the driver to
928 	 * or the error code returned by drm_modeset_lock(), -EDEADLK.
961 	 * held. Because of this it's safe to inspect &drm_connector->state.
992 	 * be influenced by the currently set display state - such constraints
1025 	 * anything outside of arguments passed-in. Atomic drivers which need to
1029 	 * You can leave this function to NULL if the connector is only
1047 	 * configuration and can't select it statically.
1080 	 * can add more state objects to the atomic commit if needed. Care must
1089 	 * driver is not allowed to change anything outside of the free-standing
1090 	 * state objects passed-in or assembled in the overall &drm_atomic_state
1095 	 * 0 on success, -EINVAL if the state or the transition can't be
1096 	 * supported, -ENOMEM on memory allocation failure and -EDEADLK if an
1122 	 * prepare and clean them up the same way they can prepare and
1153 	 * Enable hot-plug detection for the connector.
1164 	 * Disable hot-plug detection for the connector.
1174  * drm_connector_helper_add - sets the helper vtable for a connector
1181 	connector->helper_private = funcs;  in drm_connector_helper_add()
1185  * struct drm_plane_helper_funcs - helper operations for planes
1200 	 * way is to fill out the &drm_plane_state.fence of the passed-in
1208 	 * can call drm_gem_plane_helper_prepare_fb() from their @prepare_fb
1212 	 * the atomic commit. Resources that can be release at the commit's end
1216 	 * shadow-plane helpers belongs into @begin_fb_access, so that atomic
1223 	 * optional. See @begin_fb_access for preparing per-commit resources.
1229 	 * this callback is the only one which can fail an atomic commit,
1253 	 * For example, with shadow-plane helpers, the GEM buffer's vmap
1284 	 * complicated dependencies the driver can call the provided check helpers
1289 	 * can add more state objects to the atomic commit if needed. Care must
1306 	 * 0 on success, -EINVAL if the state or the transition can't be
1307 	 * supported, -ENOMEM on memory allocation failure and -EDEADLK if an
1318 	 * hook is called in-between the &drm_crtc_helper_funcs.atomic_begin and
1335 	 * This hook is called in-between the &drm_crtc_helper_funcs.atomic_begin
1340 	 * enabled before installing the scanout buffer, drivers can still do
1350 	 * @atomic_disable. Drivers that don't want to use either can still
1359 	 * Drivers should use this function to unconditionally disable a plane.
1360 	 * This hook is called in-between the
1366 	 * This hook is also useful to disable planes in preparation of a modeset,
1368 	 * &drm_crtc_helper_funcs.disable hook.
1385 	 * atomic state can be updated in a async fashion. Here async means
1389 	 * given update can be committed asynchronously, that is, if it can
1395 	 * can not be applied in asynchronous manner.
1427 	 *  - It only works for single plane updates
1428 	 *  - Async Pageflips are not supported yet
1429 	 *  - Some hw might still scan out the old buffer until the next
1439  * drm_plane_helper_add - sets the helper vtable for a plane
1446 	plane->helper_private = funcs;  in drm_plane_helper_add()
1450  * struct drm_mode_config_helper_funcs - global modeset helper operations
1469 	 * can add more waiting calls at the start of their implementation, e.g.
1470 	 * to wait for driver-internal request for implicit syncing, before
1482 	 * can't take care of this. And it also can't rely on the vblank event,
1483 	 * since that can be signalled already when the screen shows black,
1484 	 * which can happen much earlier than the last hardware access needed to