drm: Expand the drm_helper_probe_single_connector_modes() docs

Describe the procedure that drm_helper_probe_single_connector_modes()
uses to do it's work in the kernel-doc comment.

Caveat: Looks like crap and trying to reverse engineer the documentation
tools is not something I want to do.

Suggested-by: Daniel Vetter <daniel.vetter@ffwll.ch>
Signed-off-by: Ville Syrjälä <ville.syrjala@linux.intel.com>
Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch>
Link: http://patchwork.freedesktop.org/patch/msgid/1449782037-19722-3-git-send-email-ville.syrjala@linux.intel.com

1 files changed, 37 insertions, 12 deletions

diff --git a/drivers/gpu/drm/drm_probe_helper.c b/drivers/gpu/drm/drm_probe_helper.c
index 13d178e6981b..e714b5a7955f 100644
--- a/drivers/gpu/drm/drm_probe_helper.c
+++ b/drivers/gpu/drm/drm_probe_helper.c
@@ -144,18 +144,43 @@ EXPORT_SYMBOL(drm_kms_helper_poll_enable_locked);
  * @connector vfunc for drivers that use the CRTC helpers for output mode
  * filtering and detection.
  *
- * If the helper operation returns no mode, and if the connector status is
- * connector_status_connected, standard VESA DMT modes up to 1024x768 are
- * automatically added to the modes list by a call to
- * drm_add_modes_noedid().
- *
- * The function then filters out modes larger than @maxX and maxY if specified.
- * It finally calls the optional connector ->mode_valid() helper operation for each
- * mode in the probed list to check whether the mode is valid for the connector.
- *
- * Compared to drm_helper_probe_single_connector_modes_nomerge() this function
- * merged the mode bits for the preferred mode, as a hack to work around some
- * quirky issues on funky hardware.
+ * The basic procedure is as follows
+ *
+ * 1. All modes currently on the connector's modes list are marked as stale
+ *
+ * 2. New modes are added to the connector's probed_modes list with
+ *    drm_mode_probed_add(). New modes start their life with status as OK.
+ *    Modes are added from a single source using the following priority order.
+ *
+ *    - debugfs 'override_edid' (used for testing only)
+ *    - firmware EDID (drm_load_edid_firmware())
+ *    - connector helper ->get_modes() vfunc
+ *    - if the connector status is connector_status_connected, standard
+ *      VESA DMT modes up to 1024x768 are automatically added
+ *      (drm_add_modes_noedid())
+ *
+ *    Finally modes specified via the kernel command line (video=...) are
+ *    added in addition to what the earlier probes produced
+ *    (drm_helper_probe_add_cmdline_mode()). These modes are generated
+ *    using the VESA GTF/CVT formulas.
+ *
+ * 3. Modes are moved from the probed_modes list to the modes list. Potential
+ *    duplicates are merged together (see drm_mode_connector_list_update()).
+ *    After this step the probed_modes list will be empty again.
+ *
+ * 4. Any non-stale mode on the modes list then undergoes validation
+ *
+ *    - drm_mode_validate_basic() performs basic sanity checks
+ *    - drm_mode_validate_size() filters out modes larger than @maxX and @maxY
+ *      (if specified)
+ *    - drm_mode_validate_flag() checks the modes againt basic connector
+ *      capabilites (interlace_allowed,doublescan_allowed,stereo_allowed)
+ *    - the optional connector ->mode_valid() helper can perform driver and/or
+ *      hardware specific checks
+ *
+ * 5. Any mode whose status is not OK is pruned from the connector's modes list,
+ *    accompanied by a debug message indicating the reason for the mode's
+ *    rejection (see drm_mode_prune_invalid()).
  *
  * Returns:
  * The number of modes found on @connector.