drm: Introduce drm_bridge_mode_valid()

[sfrench/cifs-2.6.git] / include / drm / drm_bridge.h

diff --git a/include/drm/drm_bridge.h b/include/drm/drm_bridge.h
index fdd82fcbf1686482bbc3ea8bede6a8da688cea2e..5b106eca6d573a96138274eb38941089401fe4b0 100644 (file)
--- a/include/drm/drm_bridge.h
+++ b/include/drm/drm_bridge.h
@@ -58,6 +58,40 @@ struct drm_bridge_funcs {
         */
        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:
         *
@@ -66,7 +100,7 @@ struct drm_bridge_funcs {
         * the display chain, either the final &drm_connector or the next
         * &drm_bridge. The parameter adjusted_mode is the input mode the bridge
         * requires. It can be modified by this callback and does not need to
-        * match mode.
+        * match mode. See also &drm_crtc_state.adjusted_mode for more details.
         *
         * This is the only hook that allows a bridge to reject a modeset. If
         * this function passes all other callbacks must succeed for this
@@ -82,6 +116,12 @@ struct drm_bridge_funcs {
         * 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
@@ -213,6 +253,8 @@ int drm_bridge_attach(struct drm_encoder *encoder, struct drm_bridge *bridge,
 bool drm_bridge_mode_fixup(struct drm_bridge *bridge,
                        const struct drm_display_mode *mode,
                        struct drm_display_mode *adjusted_mode);
+enum drm_mode_status drm_bridge_mode_valid(struct drm_bridge *bridge,
+                                          const struct drm_display_mode *mode);
 void drm_bridge_disable(struct drm_bridge *bridge);
 void drm_bridge_post_disable(struct drm_bridge *bridge);
 void drm_bridge_mode_set(struct drm_bridge *bridge,