[PATCH] drm: document DRM_MODE_PAGE_FLIP_EVENT interactions with atomic

[Ville Syrjälä]

On Thu, Jan 16, 2025 at 04:25:35PM +0000, Simon Ser wrote:
> It's not obvious off-hand which CRTCs will get a page-flip event
> when using this flag in an atomic commit, because it's all
> implicitly implied based on the contents of the atomic commit.
> Document requirements for using this flag and
> 
> Note, because prepare_signaling() runs right after
> drm_atomic_set_property() calls, page-flip events are not delivered
> for CRTCs pulled in later by DRM core (e.g. on modeset by
> drm_atomic_helper_check_modeset()) or the driver (e.g. other CRTCs
> sharing a DP-MST connector).
> 
> Signed-off-by: Simon Ser <contact at emersion.fr>
> Cc: Simona Vetter <simona.vetter at ffwll.ch>
> Cc: Ville Syrjälä <ville.syrjala at linux.intel.com>
> Cc: Pekka Paalanen <pekka.paalanen at collabora.com>
> Cc: David Turner <david.turner at raspberrypi.com>
> ---
>  include/uapi/drm/drm_mode.h | 8 ++++++++
>  1 file changed, 8 insertions(+)
> 
> diff --git a/include/uapi/drm/drm_mode.h b/include/uapi/drm/drm_mode.h
> index c082810c08a8..a122bea25593 100644
> --- a/include/uapi/drm/drm_mode.h
> +++ b/include/uapi/drm/drm_mode.h
> @@ -962,6 +962,14 @@ struct hdr_output_metadata {
>   * Request that the kernel sends back a vblank event (see
>   * struct drm_event_vblank) with the &DRM_EVENT_FLIP_COMPLETE type when the
>   * page-flip is done.
> + *
> + * When used with atomic uAPI, one event will be delivered per CRTC included in
> + * the atomic commit. A CRTC is included in an atomic commit if one of its
> + * properties is set, or if a property is set on a connector or plane linked
> + * via the CRTC_ID property to the CRTC. At least one CRTC must be included,
> + * and all pulled in CRTCs must be either previously or newly powered on (in
> + * other words, a powered off CRTC which stays off cannot be included in the
> + * atomic commit).

I don't understand all this stuff about powered off crtcs? If 
someone sucks in a powered off thing then things will generally
work just fine.

There is a bit of corner case with the way we internally complete
the commits for disabled things (not just crtcs, but also planes
and connectors) and that can apparently happen a bit later than
the commit completion for the enabled things. That seems to be
causing a bit of grief for sway which insists on adding all kinds
of disabled planes to every commit:
https://gitlab.freedesktop.org/drm/i915/kernel/-/issues/13410

-- 
Ville Syrjälä
Intel