From 5b5fb962b3df6ccb093c0245a70f97dd1bfaf2ba Mon Sep 17 00:00:00 2001
From: Simon Ser <contact@emersion.fr>
Date: Thu, 4 Jun 2020 09:20:23 +0000
Subject: drm: document how user-space should use link-status
Git-commit: a66da873c424fd9a695ae945d6e0160bb467dcf9
Patch-mainline: v5.9-rc1
References: jsc#SLE-12680, jsc#SLE-12880, jsc#SLE-12882, jsc#SLE-12883, jsc#SLE-13496, jsc#SLE-15322
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)
v3:
- Fix description of what happens when link-status isn't reset to
"GOOD", and when link-status is reset without ALLOW_MODESET (Daniel,
Ville)
- Changing link-status to "BAD" is a no-op
- Clearly state that "BAD" means black screen (Manasi)
[1]: https://gitlab.freedesktop.org/drm/igt-gpu-tools/-/commit/fbe61f529737191d0920521946a575bd55f00fbe
Signed-off-by: Simon Ser <contact@emersion.fr>
Cc: Daniel Vetter <daniel@ffwll.ch>
Cc: Manasi Navare <manasi.d.navare@intel.com>
Cc: Ville Syrjala <ville.syrjala@linux.intel.com>
Cc: Pekka Paalanen <ppaalanen@gmail.com>
Reviewed-by: Daniel Vetter <daniel@ffwll.ch>
Acked-by: Pekka Paalanen <ppaalanen@gmail.com>
Link: https://patchwork.freedesktop.org/patch/msgid/kFylMmeRMGJk-oi8f-Td8A7GNa1C-GsK23-vjKg77VhWfwpkLJg7QxFlQ_g9KdVxZiyWl9eJWpUGa5PYasR9YcyvIbuBmHVfKeHb4rH0yTM=@emersion.fr
Signed-off-by: Patrik Jakobsson <pjakobsson@suse.de>
---
drivers/gpu/drm/drm_connector.c | 26 ++++++++++++++++++++++++++
1 file changed, 26 insertions(+)
diff --git a/drivers/gpu/drm/drm_connector.c b/drivers/gpu/drm/drm_connector.c
index 1063fa020475..b7bd46033807 100644
--- a/drivers/gpu/drm/drm_connector.c
+++ b/drivers/gpu/drm/drm_connector.c
@@ -999,6 +999,32 @@ 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 (e.g. the screen
+ * becomes completely black). 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", the sink may
+ * still not receive pixels. When user-space performs an atomic commit
+ * which resets the link-status property to "GOOD" without the
+ * ALLOW_MODESET flag set, it might fail because a modeset is required.
+ *
+ * User-space can only change link-status to "GOOD", changing it to "BAD"
+ * is a no-op.
+ *
+ * For backwards compatibility with non-atomic userspace the kernel
+ * tries to automatically set the link-status back to "GOOD" in the
+ * SETCRTC IOCTL. This might fail if the mode is no longer valid, similar
+ * to how it might fail if a different screen has been connected in the
+ * interim.
* non_desktop:
* Indicates the output should be ignored for purposes of displaying a
* standard desktop environment or console. This is most likely because
--
2.29.2