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

[Daniel Vetter]

On Thu, Jun 4, 2020 at 11:20 AM Simon Ser <contact at emersion.fr> wrote:
>
> 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 at emersion.fr>
> Cc: Daniel Vetter <daniel at ffwll.ch>
> Cc: Manasi Navare <manasi.d.navare at intel.com>
> Cc: Ville Syrjala <ville.syrjala at linux.intel.com>
> Cc: Pekka Paalanen <ppaalanen at gmail.com>
> ---
>
> I'm not 100% sure the paragraph about not resetting link-status or not
> using ALLOW_MODESET is accurate. Just like the previous version, this
> is just an attempt at documenting the current kernel behaviour.
>
>  drivers/gpu/drm/drm_connector.c | 20 ++++++++++++++++++++
>  1 file changed, 20 insertions(+)
>
> diff --git a/drivers/gpu/drm/drm_connector.c b/drivers/gpu/drm/drm_connector.c
> index f2b20fd66319..1df036b3353b 100644
> --- a/drivers/gpu/drm/drm_connector.c
> +++ b/drivers/gpu/drm/drm_connector.c
> @@ -994,6 +994,26 @@ 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.

Above reads well and is accurate I think. I think we should add
another paragraph about the backwards compatibility hack in SETCRTC
ioctl:

"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."

With that or similar this has my r-b.
-Daniel

>   * 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
>
>


-- 
Daniel Vetter
Software Engineer, Intel Corporation
+41 (0) 79 365 57 48 - http://blog.ffwll.ch