diff --git a/Documentation/DocBook/gpu.tmpl b/Documentation/DocBook/gpu.tmpl
index 225a246c5f53..faa5e0d4208d 100644
--- a/Documentation/DocBook/gpu.tmpl
+++ b/Documentation/DocBook/gpu.tmpl
@@ -1578,194 +1578,6 @@ void intel_crt_init(struct drm_device *dev)
To use it, a driver must provide bottom functions for all of the three KMS
entities.
-
- Legacy CRTC Helper Operations
-
-
- bool (*mode_fixup)(struct drm_crtc *crtc,
- const struct drm_display_mode *mode,
- struct drm_display_mode *adjusted_mode);
-
- Let CRTCs adjust the requested mode or reject it completely. This
- operation returns true if the mode is accepted (possibly after being
- adjusted) or false if it is rejected.
-
-
- The mode_fixup operation should reject the
- mode if it can't reasonably use it. The definition of "reasonable"
- is currently fuzzy in this context. One possible behaviour would be
- to set the adjusted mode to the panel timings when a fixed-mode
- panel is used with hardware capable of scaling. Another behaviour
- would be to accept any input mode and adjust it to the closest mode
- supported by the hardware (FIXME: This needs to be clarified).
-
-
-
- int (*mode_set_base)(struct drm_crtc *crtc, int x, int y,
- struct drm_framebuffer *old_fb)
-
- Move the CRTC on the current frame buffer (stored in
- crtc->fb) to position (x,y). Any of the frame
- buffer, x position or y position may have been modified.
-
-
- This helper operation is optional. If not provided, the
- drm_crtc_helper_set_config function will fall
- back to the mode_set helper operation.
-
-
- FIXME: Why are x and y passed as arguments, as they can be accessed
- through crtc->x and
- crtc->y?
-
-
-
- void (*prepare)(struct drm_crtc *crtc);
-
- Prepare the CRTC for mode setting. This operation is called after
- validating the requested mode. Drivers use it to perform
- device-specific operations required before setting the new mode.
-
-
-
- int (*mode_set)(struct drm_crtc *crtc, struct drm_display_mode *mode,
- struct drm_display_mode *adjusted_mode, int x, int y,
- struct drm_framebuffer *old_fb);
-
- Set a new mode, position and frame buffer. Depending on the device
- requirements, the mode can be stored internally by the driver and
- applied in the commit operation, or
- programmed to the hardware immediately.
-
-
- The mode_set operation returns 0 on success
- or a negative error code if an error occurs.
-
-
-
- void (*commit)(struct drm_crtc *crtc);
-
- Commit a mode. This operation is called after setting the new mode.
- Upon return the device must use the new mode and be fully
- operational.
-
-
-
-
-
- Encoder Helper Operations
-
-
- bool (*mode_fixup)(struct drm_encoder *encoder,
- const struct drm_display_mode *mode,
- struct drm_display_mode *adjusted_mode);
-
- Let encoders adjust the requested mode or reject it completely. This
- operation returns true if the mode is accepted (possibly after being
- adjusted) or false if it is rejected. See the
- mode_fixup CRTC helper
- operation for an explanation of the allowed adjustments.
-
-
-
- void (*prepare)(struct drm_encoder *encoder);
-
- Prepare the encoder for mode setting. This operation is called after
- validating the requested mode. Drivers use it to perform
- device-specific operations required before setting the new mode.
-
-
-
- void (*mode_set)(struct drm_encoder *encoder,
- struct drm_display_mode *mode,
- struct drm_display_mode *adjusted_mode);
-
- Set a new mode. Depending on the device requirements, the mode can
- be stored internally by the driver and applied in the
- commit operation, or programmed to the
- hardware immediately.
-
-
-
- void (*commit)(struct drm_encoder *encoder);
-
- Commit a mode. This operation is called after setting the new mode.
- Upon return the device must use the new mode and be fully
- operational.
-
-
-
-
-
- Connector Helper Operations
-
-
- struct drm_encoder *(*best_encoder)(struct drm_connector *connector);
-
- Return a pointer to the best encoder for the connecter. Device that
- map connectors to encoders 1:1 simply return the pointer to the
- associated encoder. This operation is mandatory.
-
-
-
- int (*get_modes)(struct drm_connector *connector);
-
- Fill the connector's probed_modes list
- by parsing EDID data with drm_add_edid_modes,
- adding standard VESA DMT modes with drm_add_modes_noedid,
- or calling drm_mode_probed_add directly for every
- supported mode and return the number of modes it has detected. This
- operation is mandatory.
-
-
- Note that the caller function will automatically add standard VESA
- DMT modes up to 1024x768 if the get_modes
- helper operation returns no mode and if the connector status is
- connector_status_connected. There is no need to call
- drm_add_edid_modes manually in that case.
-
-
- The vrefresh value is computed by
- drm_helper_probe_single_connector_modes.
-
-
- When parsing EDID data, drm_add_edid_modes fills the
- connector display_info
- width_mm and
- height_mm fields. When creating modes
- manually the get_modes helper operation must
- set the display_info
- width_mm and
- height_mm fields if they haven't been set
- already (for instance at initialization time when a fixed-size panel is
- attached to the connector). The mode width_mm
- and height_mm fields are only used internally
- during EDID parsing and should not be set when creating modes manually.
-
-
-
- int (*mode_valid)(struct drm_connector *connector,
- struct drm_display_mode *mode);
-
- Verify whether a mode is valid for the connector. Return MODE_OK for
- supported modes and one of the enum drm_mode_status values (MODE_*)
- for unsupported modes. This operation is optional.
-
-
- As the mode rejection reason is currently not used beside for
- immediately removing the unsupported mode, an implementation can
- return MODE_BAD regardless of the exact reason why the mode is not
- valid.
-
-
- Note that the mode_valid helper operation is
- only called for modes detected by the device, and
- not for modes set by the user through the CRTC
- set_config operation.
-
-
-
- Atomic Modeset Helper Functions Reference
diff --git a/include/drm/drm_modeset_helper_vtables.h b/include/drm/drm_modeset_helper_vtables.h
index 29e0dc50031d..a126a0d7aed4 100644
--- a/include/drm/drm_modeset_helper_vtables.h
+++ b/include/drm/drm_modeset_helper_vtables.h
@@ -131,6 +131,20 @@ struct drm_crtc_helper_funcs {
* 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
+ * ->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 ->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 ->mode_valid() but also in ->mode_fixup() to
+ * make sure invalid modes passed in from userspace are rejected.
+ *
* RETURNS:
*
* True if an acceptable configuration is possible, false if the modeset
@@ -188,7 +202,9 @@ struct drm_crtc_helper_funcs {
* This callback is used by the legacy CRTC helpers to set a new
* framebuffer and scanout position. It is optional and used as an
* optimized fast-path instead of a full mode set operation with all the
- * resulting flickering. Since it can't update other planes it's
+ * resulting flickering. If it is not present
+ * drm_crtc_helper_set_config() will fall back to a full modeset, using
+ * the ->mode_set() callback. Since it can't update other planes it's
* incompatible with atomic modeset support.
*
* This callback is only used by the CRTC helpers and deprecated.
@@ -439,6 +455,20 @@ struct drm_encoder_helper_funcs {
* 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
+ * ->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 ->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 ->mode_valid() but also in ->mode_fixup() to
+ * make sure invalid modes passed in from userspace are rejected.
+ *
* RETURNS:
*
* True if an acceptable configuration is possible, false if the modeset
@@ -640,8 +670,16 @@ struct drm_connector_helper_funcs {
* In this function drivers then parse the modes in the EDID and add
* them by calling drm_add_edid_modes(). But connectors that driver a
* fixed panel can also manually add specific modes using
- * drm_mode_probed_add(). Finally drivers that support audio probably
- * want to update the ELD data, too, using drm_edid_to_eld().
+ * drm_mode_probed_add(). Drivers which manually add modes should also
+ * make sure that the @display_info, @width_mm and @height_mm fields of the
+ * struct #drm_connector are filled in.
+ *
+ * Virtual drivers that just want some standard VESA mode with a given
+ * resolution can call drm_add_modes_noedid(), and mark the preferred
+ * one using drm_set_preferred_mode().
+ *
+ * Finally drivers that support audio probably want to update the ELD
+ * data, too, using drm_edid_to_eld().
*
* This function is only called after the ->detect() hook has indicated
* that a sink is connected and when the EDID isn't overridden through