[PATCH] drm: document DRM_MODE_PAGE_FLIP_EVENT interactions with atomic

[Simon Ser]

On Friday, January 17th, 2025 at 12:15, Pekka Paalanen <pekka.paalanen at haloniitty.fi> wrote:

> On Thu, 16 Jan 2025 16:25:35 +0000
> Simon Ser contact at emersion.fr 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
> 
> and?

Oops, sounds like I stopped here to write the next paragraph and forgot
to go back and finish the sentence…

> > 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).
> 
> Sounds right. I imagine this doc needs to be extended when drm_colorop
> lands, as yet another way to pull in a CRTC.

Yeah, I suppose so.

> Wasn't this also conditional on the DRM_CAP_CRTC_IN_VBLANK_EVENT or did
> userspace really need to count the events even without it?

DRM_CAP_CRTC_IN_VBLANK_EVENT is unconditionally set to 1. It doesn't seem
like there is any interaction between these two. So yeah, I suppose
user-space needs to count if they are on kernel < v4.12.

> Nevertheless, should there be a "see also DRM_CAP_CRTC_IN_VBLANK_EVENT"?

This sounds a bit out-of-place to me TBH. It's orthogonal to event delivery
and it's linked from struct drm_event_vblank already.