summaryrefslogtreecommitdiff
path: root/include/drm
diff options
context:
space:
mode:
authorDaniel Vetter <daniel.vetter@ffwll.ch>2016-01-04 09:53:36 +0300
committerDaniel Vetter <daniel.vetter@ffwll.ch>2016-01-05 18:21:35 +0300
commitdf7d678bea8ba8904bdb293c8e96aa9488f7dbee (patch)
treea3b9ad6d31b65713b25062e236e8dd2ac24d3fd5 /include/drm
parent4cba68507cf58db99752cf79198beb4a85a9f8ce (diff)
downloadlinux-df7d678bea8ba8904bdb293c8e96aa9488f7dbee.tar.xz
drm/docs: more leftovers from the big vtable documentation pile
Another pile of vfuncs from the old gpu.tmpl xml documentation that I've forgotten to delete. I spotted a few more things to clarify/extend in the new kerneldoc while going through this once more. v2: Spelling fixes (Thierry). v3: More spelling fixes and use Thierry's proposal to clarify why drivers need to validate modes both in ->mode_fixup and ->mode_valid. Cc: Laurent Pinchart <laurent.pinchart@ideasonboard.com> Cc: Thierry Reding <treding@nvidia.com> Acked-by: Thierry Reding <treding@nvidia.com> Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
Diffstat (limited to 'include/drm')
-rw-r--r--include/drm/drm_modeset_helper_vtables.h44
1 files changed, 41 insertions, 3 deletions
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