[PATCH] drm: document DRM_MODE_PAGE_FLIP_EVENT interactions with atomic

[Simon Ser]

On Friday, January 17th, 2025 at 12:32, Ville Syrjälä <ville.syrjala at linux.intel.com> wrote:

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

Not with the page-flip event flag:

	/*
	 * Reject event generation for when a CRTC is off and stays off.
	 * It wouldn't be hard to implement this, but userspace has a track
	 * record of happily burning through 100% cpu (or worse, crash) when the
	 * display pipe is suspended. To avoid all that fun just reject updates
	 * that ask for events since likely that indicates a bug in the
	 * compositor's drawing loop. This is consistent with the vblank IOCTL
	 * and legacy page_flip IOCTL which also reject service on a disabled
	 * pipe.
	 */
	if (new_crtc_state->event &&
	    !new_crtc_state->active && !old_crtc_state->active) {
		drm_dbg_atomic(crtc->dev,
			       "[CRTC:%d:%s] requesting event but off\n",
			       crtc->base.id, crtc->name);
		return -EINVAL;
	}

> 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

Hm, interesting. So including an already-disabled cursor plane in a
commit may fail the next commit with EBUY? I expect a lot of user-space
to do this as well, e.g. Weston.