*/
void (*detach)(struct drm_bridge *bridge);
+ /**
+ * @mode_valid:
+ *
+ * This callback is used to check if a specific mode is valid in this
+ * bridge. This should be implemented if the bridge has some sort of
+ * restriction in the modes it can display. For example, a given bridge
+ * may be responsible to set a clock value. If the clock can not
+ * produce all the values for the available modes then this callback
+ * can be used to restrict the number of modes to only the ones that
+ * can be displayed.
+ *
+ * This hook is used by the probe helpers to filter the mode list in
+ * drm_helper_probe_single_connector_modes(), and it is used by the
+ * atomic helpers to validate modes supplied by userspace in
+ * drm_atomic_helper_check_modeset().
+ *
+ * This function is optional.
+ *
+ * NOTE:
+ *
+ * Since this function is both called from the check phase of an atomic
+ * commit, and the mode validation in the probe paths it is not allowed
+ * to look at anything else but the passed-in mode, and validate it
+ * against configuration-invariant hardward constraints. Any further
+ * limits which depend upon the configuration can only be checked in
+ * @mode_fixup.
+ *
+ * RETURNS:
+ *
+ * drm_mode_status Enum
+ */
+ enum drm_mode_status (*mode_valid)(struct drm_bridge *crtc,
+ const struct drm_display_mode *mode);
+
/**
* @mode_fixup:
*
* NOT touch any persistent state (hardware or software) or data
* structures except the passed in @state parameter.
*
+ * Also beware that userspace can request its own custom modes, neither
+ * core nor helpers filter modes to the list of probe modes reported by
+ * the GETCONNECTOR IOCTL and stored in &drm_connector.modes. To ensure
+ * that modes are filtered consistently put any bridge constraints and
+ * limits checks into @mode_valid.
+ *
* RETURNS:
*
* True if an acceptable configuration is possible, false if the modeset
*/
void (*commit)(struct drm_crtc *crtc);
+ /**
+ * @mode_valid:
+ *
+ * This callback is used to check if a specific mode is valid in this
+ * crtc. This should be implemented if the crtc has some sort of
+ * restriction in the modes it can display. For example, a given crtc
+ * may be responsible to set a clock value. If the clock can not
+ * produce all the values for the available modes then this callback
+ * can be used to restrict the number of modes to only the ones that
+ * can be displayed.
+ *
+ * This hook is used by the probe helpers to filter the mode list in
+ * drm_helper_probe_single_connector_modes(), and it is used by the
+ * atomic helpers to validate modes supplied by userspace in
+ * drm_atomic_helper_check_modeset().
+ *
+ * This function is optional.
+ *
+ * NOTE:
+ *
+ * Since this function is both called from the check phase of an atomic
+ * commit, and the mode validation in the probe paths it is not allowed
+ * to look at anything else but the passed-in mode, and validate it
+ * against configuration-invariant hardward constraints. Any further
+ * limits which depend upon the configuration can only be checked in
+ * @mode_fixup or @atomic_check.
+ *
+ * RETURNS:
+ *
+ * drm_mode_status Enum
+ */
+ enum drm_mode_status (*mode_valid)(struct drm_crtc *crtc,
+ const struct drm_display_mode *mode);
+
/**
* @mode_fixup:
*
* Atomic drivers which need to inspect and adjust more state should
* instead use the @atomic_check callback.
*
- * Also beware that neither core nor helpers filter modes before
- * passing them to the driver: While the list of modes that is
- * advertised to userspace is filtered using the
- * &drm_connector.mode_valid callback, neither the core nor the helpers
- * do any filtering on modes passed in from userspace when setting a
- * mode. It is therefore possible for userspace to pass in a mode that
- * was previously filtered out using &drm_connector.mode_valid or add a
- * custom mode that wasn't probed from EDID or similar to begin with.
- * Even though this is an advanced feature and rarely used nowadays,
- * some users rely on being able to specify modes manually so drivers
- * must be prepared to deal with it. Specifically this means that all
- * drivers need not only validate modes in &drm_connector.mode_valid but
- * also in this or in the &drm_encoder_helper_funcs.mode_fixup callback
- * to make sure invalid modes passed in from userspace are rejected.
+ * Also beware that userspace can request its own custom modes, neither
+ * core nor helpers filter modes to the list of probe modes reported by
+ * the GETCONNECTOR IOCTL and stored in &drm_connector.modes. To ensure
+ * that modes are filtered consistently put any CRTC constraints and
+ * limits checks into @mode_valid.
*
* RETURNS:
*
* state objects passed-in or assembled in the overall &drm_atomic_state
* update tracking structure.
*
+ * Also beware that userspace can request its own custom modes, neither
+ * core nor helpers filter modes to the list of probe modes reported by
+ * the GETCONNECTOR IOCTL and stored in &drm_connector.modes. To ensure
+ * that modes are filtered consistently put any CRTC constraints and
+ * limits checks into @mode_valid.
+ *
* RETURNS:
*
* 0 on success, -EINVAL if the state or the transition can't be
*/
void (*dpms)(struct drm_encoder *encoder, int mode);
+ /**
+ * @mode_valid:
+ *
+ * This callback is used to check if a specific mode is valid in this
+ * encoder. This should be implemented if the encoder has some sort
+ * of restriction in the modes it can display. For example, a given
+ * encoder may be responsible to set a clock value. If the clock can
+ * not produce all the values for the available modes then this callback
+ * can be used to restrict the number of modes to only the ones that
+ * can be displayed.
+ *
+ * This hook is used by the probe helpers to filter the mode list in
+ * drm_helper_probe_single_connector_modes(), and it is used by the
+ * atomic helpers to validate modes supplied by userspace in
+ * drm_atomic_helper_check_modeset().
+ *
+ * This function is optional.
+ *
+ * NOTE:
+ *
+ * Since this function is both called from the check phase of an atomic
+ * commit, and the mode validation in the probe paths it is not allowed
+ * to look at anything else but the passed-in mode, and validate it
+ * against configuration-invariant hardward constraints. Any further
+ * limits which depend upon the configuration can only be checked in
+ * @mode_fixup or @atomic_check.
+ *
+ * RETURNS:
+ *
+ * drm_mode_status Enum
+ */
+ enum drm_mode_status (*mode_valid)(struct drm_encoder *crtc,
+ const struct drm_display_mode *mode);
+
/**
* @mode_fixup:
*
* Atomic drivers which need to inspect and adjust more state should
* instead use the @atomic_check callback.
*
- * Also beware that neither core nor helpers filter modes before
- * passing them to the driver: While the list of modes that is
- * advertised to userspace is filtered using the connector's
- * &drm_connector_helper_funcs.mode_valid callback, neither the core nor
- * the helpers do any filtering on modes passed in from userspace when
- * setting a mode. It is therefore possible for userspace to pass in a
- * mode that was previously filtered out using
- * &drm_connector_helper_funcs.mode_valid or add a custom mode that
- * wasn't probed from EDID or similar to begin with. Even though this
- * is an advanced feature and rarely used nowadays, some users rely on
- * being able to specify modes manually so drivers must be prepared to
- * deal with it. Specifically this means that all drivers need not only
- * validate modes in &drm_connector.mode_valid but also in this or in
- * the &drm_crtc_helper_funcs.mode_fixup callback to make sure
- * invalid modes passed in from userspace are rejected.
+ * Also beware that userspace can request its own custom modes, neither
+ * core nor helpers filter modes to the list of probe modes reported by
+ * the GETCONNECTOR IOCTL and stored in &drm_connector.modes. To ensure
+ * that modes are filtered consistently put any encoder constraints and
+ * limits checks into @mode_valid.
*
* RETURNS:
*
* state objects passed-in or assembled in the overall &drm_atomic_state
* update tracking structure.
*
+ * Also beware that userspace can request its own custom modes, neither
+ * core nor helpers filter modes to the list of probe modes reported by
+ * the GETCONNECTOR IOCTL and stored in &drm_connector.modes. To ensure
+ * that modes are filtered consistently put any encoder constraints and
+ * limits checks into @mode_valid.
+ *
* RETURNS:
*
* 0 on success, -EINVAL if the state or the transition can't be
* (which is usually derived from the EDID data block from the sink).
* See e.g. drm_helper_probe_single_connector_modes().
*
+ * This function is optional.
+ *
* NOTE:
*
* This only filters the mode list supplied to userspace in the
- * GETCONNECOTR IOCTL. Userspace is free to create modes of its own and
- * ask the kernel to use them. It this case the atomic helpers or legacy
- * CRTC helpers will not call this function. Drivers therefore must
- * still fully validate any mode passed in in a modeset request.
+ * GETCONNECTOR IOCTL. Compared to &drm_encoder_helper_funcs.mode_valid,
+ * &drm_crtc_helper_funcs.mode_valid and &drm_bridge_funcs.mode_valid,
+ * which are also called by the atomic helpers from
+ * drm_atomic_helper_check_modeset(). This allows userspace to force and
+ * ignore sink constraint (like the pixel clock limits in the screen's
+ * EDID), which is useful for e.g. testing, or working around a broken
+ * EDID. Any source hardware constraint (which always need to be
+ * enforced) therefore should be checked in one of the above callbacks,
+ * and not this one here.
*
* To avoid races with concurrent connector state updates, the helper
* libraries always call this with the &drm_mode_config.connection_mutex
projects / GitHub / moto-9609 / android_kernel_motorola_exynos9610.git / commitdiff