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
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
38  * The DRM mode setting helper functions are common code for drivers to use if
45  * for helper libraries they are by necessity shared among the different
61  * struct drm_crtc_helper_funcs - helper operations for CRTCs
79 	 * also support using this hook for enabling and disabling a CRTC to
88 	 * This callback should prepare the CRTC for a subsequent modeset, which
94 	 * also support using this hook for disabling a CRTC to facilitate
109 	 * also support using this hook for enabling a CRTC to facilitate
120 	 * restriction in the modes it can display. For example, a given crtc
122 	 * produce all the values for the available modes then this callback
137 	 * to look at anything else but the passed-in mode, and validate it
138 	 * against configuration-invariant hardware constraints. Any further
155 	 * of the meaning for the &drm_encoder and &drm_bridge_funcs.mode_fixup
158 	 * &drm_crtc_state.adjusted_mode for more details.
166 	 * can be aborted for any reason (including on userspace's request to
168 	 * MUST NOT touch any persistent state (hardware or software) or data
178 	 * drm_atomic_helper_check_planes(), because originally it was meant for
223 	 * called. Atomic drivers which need hardware to be running before they
241 	 * optimized fast-path instead of a full mode set operation with all the
263 	 * This callback is optional and only needed for kgdb support in the fbdev
289 	 * @disable must be the inverse of @atomic_enable for atomic drivers.
301 	 * Therefore @disable must be the inverse of @mode_set plus @commit for
310 	 * Drivers should check plane-update related CRTC constraints in this
322 	 * after the &drm_plane_helper_funcs.atomic_check hook for planes, which
324 	 * callback here. For more complicated dependencies the driver can call
330 	 * be taken though to ensure that state check and compute functions for
341 	 * driver is not allowed to change anything outside of the free-standing
342 	 * state object passed-in.
352 	 * 0 on success, -EINVAL if the state or the transition can't be
353 	 * supported, -ENOMEM on memory allocation failure and -EDEADLK if an
363 	 * Drivers should prepare for an atomic update of multiple planes on
364 	 * a CRTC in this hook. Depending upon hardware this might be vblank
366 	 * for e.g. manual update display.
372 	 * has picked. See drm_atomic_helper_commit_planes() for a discussion of
384 	 * a CRTC in this hook. Depending upon hardware this might include
388 	 * Simple hardware or hardware with special requirements can commit and
389 	 * flush out all updates for all planes from this hook and forgo all the
390 	 * other commit hooks for plane updates.
396 	 * has picked. See drm_atomic_helper_commit_planes() for a discussion of
415 	 * This hook is used only by atomic helpers, for symmetry with
419 	 * @atomic_enable must be the inverse of @atomic_disable for atomic
456 	 * for the @drm_crtc_funcs.get_vblank_timestamp callback.
464 	 *     need to apply some workarounds for gpu-specific vblank irq
467 	 *     Target location for current vertical scanout position.
469 	 *     Target location for current horizontal scanout position.
471 	 *     Target location for timestamp taken immediately before
474 	 *     Target location for timestamp taken immediately after
481 	 * of scanlines to go until end of vblank, e.g., -1 means "one scanline
496  * drm_crtc_helper_add - sets the helper vtable for a crtc
498  * @funcs: helper vtable to set for @crtc
503 	crtc->helper_private = funcs;  in drm_crtc_helper_add()
507  * struct drm_encoder_helper_funcs - helper operations for encoders
525 	 * also support using this hook for enabling and disabling an encoder to
536 	 * of restriction in the modes it can display. For example, a given
538 	 * not produce all the values for the available modes then this callback
553 	 * to look at anything else but the passed-in mode, and validate it
554 	 * against configuration-invariant hardware constraints. Any further
573 	 * also &drm_crtc_state.adjusted_mode for more details.
581 	 * can be aborted for any reason (including on userspace's request to
583 	 * MUST NOT touch any persistent state (hardware or software) or data
612 	 * This callback should prepare the encoder for a subsequent modeset,
618 	 * also support using this hook for disabling an encoder to facilitate
633 	 * also support using this hook for enabling an encoder to facilitate
645 	 * called. Drivers which need hardware to be running before they program
671 	 * called. Drivers which need hardware to be running before they program
694 	 * It is not used by any helper and therefore has purely driver-specific
766 	 * @disable must be the inverse of @enable for atomic drivers.
768 	 * For atomic drivers also consider @atomic_disable and save yourself
779 	 * Therefore @disable must be the inverse of @mode_set plus @commit for
799 	 * works @enable must be the inverse of @disable for atomic drivers.
806 	 * This callback is used to validate encoder state for atomic drivers.
809 	 * update the CRTC to match what the encoder needs for the requested
822 	 * driver is not allowed to change anything outside of the free-standing
823 	 * state objects passed-in or assembled in the overall &drm_atomic_state
834 	 * 0 on success, -EINVAL if the state or the transition can't be
835 	 * supported, -ENOMEM on memory allocation failure and -EDEADLK if an
845  * drm_encoder_helper_add - sets the helper vtable for an encoder
847  * @funcs: helper vtable to set for @encoder
852 	encoder->helper_private = funcs;  in drm_encoder_helper_add()
856  * struct drm_connector_helper_funcs - helper operations for connectors
865 	 * This function should fill in all modes currently valid for the sink
870 	 * probe callback somewhere in the driver-private connector structure.
898 	 * held. Because of this it's safe to inspect &drm_connector->state.
924 	 * locks as required.
929 	 * or the error code returned by drm_modeset_lock(), -EDEADLK.
938 	 * Callback to validate a mode for a connector, irrespective of the
955 	 * EDID), which is useful for e.g. testing, or working around a broken
956 	 * EDID. Any source hardware constraint (which always need to be
962 	 * held. Because of this it's safe to inspect &drm_connector->state.
975 	 * Callback to validate a mode for a connector, irrespective of the
985 	 * To allow for accessing the atomic state of modesetting objects, the
988 	 * the ctx parameter set to @ctx. This allows for taking additional
989 	 * locks as required.
993 	 * be influenced by the currently set display state - such constraints
994 	 * should be handled in the driver's atomic check. For example, if a
1016 	 * This function should select the best encoder for the given connector.
1026 	 * anything outside of arguments passed-in. Atomic drivers which need to
1032 	 * drm_connector_get_single_encoder() for you.
1036 	 * Encoder that should be used for the given connector and connector
1039 	 * for this.
1046 	 * This is the atomic version of @best_encoder for atomic drivers which
1062 	 * Encoder that should be used for the given connector and connector
1065 	 * for this.
1082 	 * be taken though to ensure that state check and compute functions for
1090 	 * driver is not allowed to change anything outside of the free-standing
1091 	 * state objects passed-in or assembled in the overall &drm_atomic_state
1096 	 * 0 on success, -EINVAL if the state or the transition can't be
1097 	 * supported, -ENOMEM on memory allocation failure and -EDEADLK if an
1108 	 * that need a point when to commit the writeback job to the hardware.
1122 	 * As writeback jobs contain a framebuffer, drivers may need to
1124 	 * clean up framebuffers for planes. This optional connector operation
1125 	 * is used to support the preparation of writeback jobs. The job
1127 	 * for struct &drm_writeback_connector connectors only.
1139 	 * cleanup of writeback jobs. The job cleanup operation is called
1154 	 * Enable hot-plug detection for the connector.
1170 	 * Disable hot-plug detection for the connector.
1185  * drm_connector_helper_add - sets the helper vtable for a connector
1187  * @funcs: helper vtable to set for @connector
1192 	connector->helper_private = funcs;  in drm_connector_helper_add()
1196  * struct drm_plane_helper_funcs - helper operations for planes
1204 	 * This hook is to prepare a framebuffer for scanout by e.g. pinning
1208 	 * This function must not block for outstanding rendering, since it is
1209 	 * called in the context of the atomic IOCTL even for async commits to
1211 	 * way is to fill out the &drm_plane_state.fence of the passed-in
1216 	 * For GEM drivers who neither have a @prepare_fb nor @cleanup_fb hook
1225 	 * For example, a GEM buffer's pin operation belongs into @prepare_fb to
1226 	 * keep the buffer pinned after the commit. But a vmap operation for
1227 	 * shadow-plane helpers belongs into @begin_fb_access, so that atomic
1230 	 * The helpers will call @cleanup_fb with matching arguments for every
1234 	 * optional. See @begin_fb_access for preparing per-commit resources.
1248 	 * This hook is called to clean up any resources allocated for the given
1260 	 * This hook prepares the plane for access during an atomic commit.
1264 	 * For example, with shadow-plane helpers, the GEM buffer's vmap
1271 	 * See @end_fb_cleanup for undoing the effects of @begin_fb_access and
1272 	 * @prepare_fb for acquiring resources until the next pageflip.
1283 	 * at the end of a commit for the new plane state.
1293 	 * hooks are called before the ones for CRTCs, which allows drivers to
1294 	 * request shared resources that the CRTC controls here. For more
1301 	 * be taken though to ensure that state check and compute functions for
1317 	 * 0 on success, -EINVAL if the state or the transition can't be
1318 	 * supported, -ENOMEM on memory allocation failure and -EDEADLK if an
1329 	 * hook is called in-between the &drm_crtc_helper_funcs.atomic_begin and
1334 	 * has picked. See drm_atomic_helper_commit_planes() for a discussion of
1346 	 * This hook is called in-between the &drm_crtc_helper_funcs.atomic_begin
1348 	 * @atomic_update, which will be called for all enabled planes. Drivers
1356 	 * has picked. See drm_atomic_helper_commit_planes() for a discussion of
1371 	 * This hook is called in-between the
1374 	 * @atomic_update, which will be called for disabling planes, too, if
1383 	 * has picked. See drm_atomic_helper_commit_planes() for a discussion of
1401 	 * jump ahead of the state currently queued for update.
1405 	 * distinguish if the function is used for just the plane state or for a
1436 	 * This is required since cleanup for async commits is performed on
1437 	 * the new state, rather than old state like for traditional commits.
1443 	 *  - It only works for single plane updates
1444 	 *  - Async Pageflips are not supported yet
1445 	 *  - Some hw might still scan out the old buffer until the next
1447 	 *    we run this hook. For now drivers must implement their own workers
1448 	 *    for deferring if needed, until a common solution is created.
1459 	 * buffers are supported. Non-linear buffer support is on the TODO list.
1463 	 * Please look the documentation at drm_panic_trylock() for an in-depth
1481 	 * can send additional commands to the hardware, to make the scanout
1486 	 * Please look the documentation at drm_panic_trylock() for an in-depth
1493  * drm_plane_helper_add - sets the helper vtable for a plane
1495  * @funcs: helper vtable to set for @plane
1500 	plane->helper_private = funcs;  in drm_plane_helper_add()
1504  * struct drm_mode_config_helper_funcs - global modeset helper operations
1514 	 * helpers (see drm_atomic_helper_setup_commit() for a starting point)
1521 	 * commit the new state into hardware. Note that the helpers have
1522 	 * already waited for preceding atomic commits and fences, but drivers
1524 	 * to wait for driver-internal request for implicit syncing, before
1525 	 * starting to commit the update to the hardware.
1527 	 * After the atomic update is committed to the hardware this hook needs
1528 	 * to call drm_atomic_helper_commit_hw_done(). Then wait for the update
1529 	 * to be executed by the hardware, for example using
1534 	 * When disabling a CRTC this hook _must_ stall for the commit to
1538 	 * which can happen much earlier than the last hardware access needed to