[PATCH 026/108] drm/i915/dp_link_training: Document DP link recovery logic

[Imre Deak <imre.deak@intel.com>]

Add kernel-doc documentation describing the Intel DP link training
recovery state machine and the sequence of automatic retraining,
fallback selection, and userspace notification.

Signed-off-by: Imre Deak <imre.deak@intel.com>
---
 Documentation/gpu/i915.rst                    |   9 +
 .../drm/i915/display/intel_dp_link_training.c | 241 ++++++++++++++++++
 2 files changed, 250 insertions(+)

diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst
index eba09c3ddce42..34556b2104aa5 100644
--- a/Documentation/gpu/i915.rst
+++ b/Documentation/gpu/i915.rst
@@ -141,6 +141,15 @@ Hotplug
 .. kernel-doc:: drivers/gpu/drm/i915/display/intel_hotplug.c
    :internal:
 
+DisplayPort Link Training
+-------------------------
+
+.. kernel-doc:: drivers/gpu/drm/i915/display/intel_dp_link_training.c
+   :doc: DisplayPort link training
+
+.. kernel-doc:: drivers/gpu/drm/i915/display/intel_dp_link_training.c
+   :internal:
+
 High Definition Audio
 ---------------------
 
diff --git a/drivers/gpu/drm/i915/display/intel_dp_link_training.c b/drivers/gpu/drm/i915/display/intel_dp_link_training.c
index 35f160761e182..810227328d002 100644
--- a/drivers/gpu/drm/i915/display/intel_dp_link_training.c
+++ b/drivers/gpu/drm/i915/display/intel_dp_link_training.c
@@ -41,6 +41,246 @@
 #include "intel_panel.h"
 #include "intel_psr.h"
 
+/**
+ * DOC: DisplayPort link training
+ *
+ * This documents the Intel DisplayPort link training implementation and
+ * its internal interfaces, with a current focus on link recovery.
+ *
+ * Documentation of the full link training procedure is not yet included.
+ *
+ * The Intel DP link recovery logic governs how the driver reacts to link
+ * training (LT) failures and to links that degrade asynchronously after a
+ * previously successful training. Recovery is first attempted via
+ * automatic retraining (autoretrain) and, when that is no longer possible,
+ * by selecting fallback link configurations and notifying userspace to
+ * recover the link via a modeset.
+ *
+ * Recovery sequence and userspace notification:
+ *   After the first link training failure following initialization or a
+ *   previously successful training, recovery is first attempted by the
+ *   driver via automatic retraining, without userspace involvement. During
+ *   this phase, a given link configuration is attempted twice before being
+ *   abandoned: after the initial link training failure, an automatic
+ *   retraining modeset is performed with the same link parameters,
+ *   constituting the second attempt.
+ *
+ *   Once automatic retraining is no longer possible, recovery is delegated
+ *   to userspace, which must select a new modeset configuration, as the
+ *   kernel must not do so. From this point onwards, each link configuration
+ *   may be attempted only once as userspace iterates through alternative
+ *   configurations. A successful link training restores the automatic
+ *   retraining model for subsequent failures.
+ *
+ *   The failure of the last automatic retraining attempt is reported to
+ *   userspace, and from that point onward the driver notifies userspace of
+ *   each subsequent failure. This allows userspace to both initiate
+ *   recovery via modesets and observe the outcome of those recovery
+ *   attempts, even when no further fallback configurations remain.
+ *
+ *   Link training failures are always reported to userspace, even when they
+ *   result from a kernel-internal modeset. Such modesets only re-apply the
+ *   existing userspace-provided state and must not modify it. A failure
+ *   triggered by such a modeset is therefore treated the same as a link
+ *   degradation after a previously successful training, and recovery is
+ *   handled by userspace in place of the kernel caller.
+ *
+ * Contexts:
+ *   The following execution contexts (A/B/C) describe how the different
+ *   recovery states are reached but are not themselves implementation
+ *   states. The actual state machine is defined by &enum
+ *   intel_dp_link_training_recovery_state.
+ *
+ *   A. Modeset-triggered link training:
+ *
+ *     Triggered by:
+ *       - link training during a modeset, or
+ *       - via the "i915_dp_force_link_training_failure" debugfs entry,
+ *         forcing this path by emulating a link training failure.
+ *
+ *     Transitions:
+ *       - A1 Link training succeeds.
+ *
+ *         State -> %INTEL_DP_LINK_RECOVERY_IDLE.
+ *
+ *       - A2 First link training fails after initialization or a previously
+ *         successful training.
+ *
+ *         An automatic retraining attempt is scheduled with the same link
+ *         parameters with which the link training failed.
+ *
+ *         State -> %INTEL_DP_LINK_RECOVERY_AUTORETRAIN_PENDING.
+ *
+ *       - A3 Link training fails again after A2, or fails when automatic
+ *         retraining is already disabled.
+ *
+ *         Through fallback selection, the driver attempts to restrict the
+ *         allowed link configurations for subsequent modesets. This may
+ *         be done either by lowering global limits (rate/lane caps), or by
+ *         disabling only the currently failing configuration while leaving
+ *         all other configurations allowed, even if they use higher rate or
+ *         lane count.
+ *
+ *         (The current implementation may still apply parameter capping as
+ *         a coarse fallback selection mechanism. This is transitional and is
+ *         expected to be replaced by a scheme that disables only the failing
+ *         configuration, rather than removing configurations that have not
+ *         been observed to fail and may still train successfully.)
+ *
+ *         This case may repeat in a loop:
+ *             %INTEL_DP_LINK_RECOVERY_AUTORETRAIN_DISABLED ->
+ *             %INTEL_DP_LINK_RECOVERY_AUTORETRAIN_DISABLED
+ *
+ *         via repeated A3a -> A3a transitions until the configuration fallback
+ *         space is exhausted, reaching the A3b terminal case.
+ *
+ *         - A3a Fallback selection succeeds.
+ *
+ *           Userspace is notified to retry the modeset.
+ *
+ *           State -> %INTEL_DP_LINK_RECOVERY_AUTORETRAIN_DISABLED.
+ *
+ *         - A3b Fallback selection fails.
+ *
+ *           Userspace is notified of the failure and may continue recovery
+ *           by retrying the modeset with the remaining allowed link
+ *           configuration.
+ *
+ *           State -> %INTEL_DP_LINK_RECOVERY_NO_FALLBACK.
+ *
+ *   B. Automatic retraining:
+ *
+ *     Triggered by:
+ *       - after a failed link training attempt, or
+ *       - after a successful link training followed by asynchronous link
+ *         degradation, or
+ *       - via the "i915_dp_force_link_retrain" debugfs entry, which may
+ *         bypass normal gating and force this path.
+ *
+ *     Transitions:
+ *       - B1 Autoretrain modeset succeeds and link training succeeds.
+ *
+ *         State -> %INTEL_DP_LINK_RECOVERY_IDLE.
+ *
+ *       - B2 Autoretrain modeset succeeds but link training fails.
+ *
+ *         - B2a The current state is %INTEL_DP_LINK_RECOVERY_IDLE.
+ *
+ *           This corresponds to a first failure in a new failure
+ *           sequence and is handled as in A2: an automatic retraining
+ *           attempt is scheduled with the same link parameters.
+ *
+ *           State -> %INTEL_DP_LINK_RECOVERY_AUTORETRAIN_PENDING.
+ *
+ *         - B2b The current state is %INTEL_DP_LINK_RECOVERY_AUTORETRAIN_PENDING.
+ *
+ *           In non-regular (debug-forced) scenarios this may also be
+ *           reached from
+ *           %INTEL_DP_LINK_RECOVERY_AUTORETRAIN_DISABLED or
+ *           %INTEL_DP_LINK_RECOVERY_NO_FALLBACK, effectively behaving
+ *           like a userspace-driven recovery attempt.
+ *
+ *           The failure is handled as in A3, performing fallback
+ *           selection and transitioning according to A3a or A3b.
+ *
+ *       - B3 Link retraining cannot be started because its modeset atomic
+ *         check fails.
+ *
+ *         The modeset may fail, for example, due to external conditions such
+ *         as changed shared link bandwidth, which can make previously valid
+ *         modeset parameters no longer acceptable.
+ *
+ *         In this case, automatic retraining is disabled without selecting
+ *         a fallback configuration. The driver hands recovery over to
+ *         userspace without modifying the allowed configuration set, so a
+ *         subsequent userspace modeset will retry with the current link
+ *         configuration. Userspace is in a better position to select new
+ *         modeset parameters (e.g. video mode or enabled outputs) that
+ *         satisfy the updated constraints, as the driver is only allowed
+ *         to retry the modeset with the existing userspace-provided modeset
+ *         configuration.
+ *
+ *         This policy preserves the normal retry model, where a given link
+ *         configuration is attempted twice in the automatic retraining
+ *         flow before being abandoned: after a first link training failure,
+ *         an automatic retraining modeset is performed with the same link
+ *         parameters, and if its atomic check passes, the link training
+ *         itself may either succeed or fail, constituting the second
+ *         attempt. In this case, however, the retry modeset's atomic check
+ *         failed, so no second link training attempt with those parameters
+ *         was performed, and selecting a fallback would cause that
+ *         configuration to be tried only once rather than twice.
+ *
+ *   C. State reset:
+ *
+ *     Triggered by:
+ *       - sink capability changes,
+ *       - sink disconnect/reconnect,
+ *       - system suspend/resume or power transitions where HPD
+ *         handling may have been suppressed, or
+ *       - successful link training.
+ *
+ *     Transitions:
+ *       - The recovery state is reset from any of the recovery states
+ *
+ *         State -> %INTEL_DP_LINK_RECOVERY_IDLE.
+ *
+ *         After reset, the driver may re-check link status and schedule
+ *         retraining if the link is found to remain degraded.
+ *
+ * State transition summary:
+ *   - From %INTEL_DP_LINK_RECOVERY_IDLE
+ *
+ *     - To %INTEL_DP_LINK_RECOVERY_AUTORETRAIN_PENDING
+ *
+ *       - In contexts: A2, B2a
+ *       - Action: queue autoretrain work
+ *
+ *     - To %INTEL_DP_LINK_RECOVERY_AUTORETRAIN_DISABLED
+ *
+ *       - In context: B3
+ *       - Action: disable automatic retraining, notify userspace
+ *
+ *   - From %INTEL_DP_LINK_RECOVERY_AUTORETRAIN_PENDING
+ *
+ *     - To %INTEL_DP_LINK_RECOVERY_AUTORETRAIN_DISABLED
+ *
+ *       - In contexts: A3a, B2b
+ *       - Action: disable automatic retraining, select fallback
+ *         configurations, notify userspace
+ *
+ *     - To %INTEL_DP_LINK_RECOVERY_NO_FALLBACK
+ *
+ *       - In contexts: A3b, B2b
+ *       - Action: disable automatic retraining, notify userspace
+ *
+ *   - From %INTEL_DP_LINK_RECOVERY_AUTORETRAIN_DISABLED
+ *
+ *     - To %INTEL_DP_LINK_RECOVERY_AUTORETRAIN_DISABLED
+ *
+ *       - In contexts: A3a, B2b
+ *       - Action: select fallback configurations, notify userspace
+ *
+ *     - To %INTEL_DP_LINK_RECOVERY_NO_FALLBACK
+ *
+ *       - In contexts: A3b, B2b
+ *       - Action: notify userspace
+ *
+ *   - From %INTEL_DP_LINK_RECOVERY_NO_FALLBACK
+ *
+ *     - To %INTEL_DP_LINK_RECOVERY_NO_FALLBACK
+ *
+ *       - In contexts: A3b
+ *       - Action: notify userspace
+ *
+ *   - From any state
+ *
+ *     - To %INTEL_DP_LINK_RECOVERY_IDLE
+ *
+ *       - In contexts: C
+ *       - Action: no action
+ */
+
 #define LT_MSG_PREFIX			"[CONNECTOR:%d:%s][ENCODER:%d:%s][%s] "
 #define LT_MSG_ARGS(_intel_dp, _dp_phy)	(_intel_dp)->attached_connector->base.base.id, \
 					(_intel_dp)->attached_connector->base.name, \
@@ -95,6 +335,7 @@
  * logic.
  *
  * See also:
+ *   - DOC: DisplayPort link training
  *   - link_recovery_autoretrain_pending()
  *   - link_recovery_autoretrain_allowed()
  *   - link_recovery_has_no_fallback()
-- 
2.49.1