[PATCH v2] drm: document how user-space should use link-status

[Simon Ser]

Describe what a "BAD" link-status means for user-space and how it should
handle it. The logic described has been implemented in igt [1].

v2:

- Change wording to avoid "enabled" (Daniel)
- Add paragraph about multiple connectors sharing the same CRTC (Pekka)
- Add paragraph about performing an atomic commit on a connector without
  updating the link-status property (Daniel)

[1]: https://gitlab.freedesktop.org/drm/igt-gpu-tools/-/commit/fbe61f529737191d0920521946a575bd55f00fbe

Signed-off-by: Simon Ser <contact at emersion.fr>
Cc: Daniel Vetter <daniel at ffwll.ch>
Cc: Manasi Navare <manasi.d.navare at intel.com>
Cc: Pekka Paalanen <ppaalanen at gmail.com>
---
 drivers/gpu/drm/drm_connector.c | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/drivers/gpu/drm/drm_connector.c b/drivers/gpu/drm/drm_connector.c
index f2b20fd66319..829b21124048 100644
--- a/drivers/gpu/drm/drm_connector.c
+++ b/drivers/gpu/drm/drm_connector.c
@@ -994,6 +994,21 @@ static const struct drm_prop_enum_list dp_colorspaces[] = {
  *      after modeset, the kernel driver may set this to "BAD" and issue a
  *      hotplug uevent. Drivers should update this value using
  *      drm_connector_set_link_status_property().
+ *
+ *      When user-space receives the hotplug uevent and detects a "BAD"
+ *      link-status, the sink doesn't receive pixels anymore. The list of
+ *      available modes may have changed. User-space is expected to pick a new
+ *      mode if the current one has disappeared and perform a new modeset with
+ *      link-status set to "GOOD" to re-enable the connector.
+ *
+ *      If multiple connectors share the same CRTC and one of them gets a "BAD"
+ *      link-status, the other are unaffected (ie. the sinks still continue to
+ *      receive pixels).
+ *
+ *      When user-space performs an atomic commit on a connector with a "BAD"
+ *      link-status without resetting the property to "GOOD", it gets
+ *      implicitly reset. This might make the atomic commit fail if the modeset
+ *      is unsuccessful.
  * non_desktop:
  * 	Indicates the output should be ignored for purposes of displaying a
  * 	standard desktop environment or console. This is most likely because
-- 
2.26.2