drm: document DRM_MODE_PAGE_FLIP_EVENT interactions with atomic

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 how to request an
event for a CRTC.

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

v2: fix cut off sentence in commit message (Pekka)

Signed-off-by: Simon Ser <contact@emersion.fr>
Reviewed-by: Simona Vetter <simona@ffwll.ch>
Cc: Ville Syrjälä <ville.syrjala@linux.intel.com>
Cc: Pekka Paalanen <pekka.paalanen@collabora.com>
Cc: David Turner <david.turner@raspberrypi.com>
Cc: Daniel Stone <daniel@fooishbar.org>
Link: https://lore.kernel.org/r/20250501112945.6448-1-contact@emersion.fr

diff --git a/include/uapi/drm/drm_mode.h b/include/uapi/drm/drm_mode.h
index c082810c08a8b234ef2672ecf54fc8c05ddc2bd3..a122bea2559387576150236e3a88f99c24ad3138 100644 (file)
--- 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).
  */
 #define DRM_MODE_PAGE_FLIP_EVENT 0x01
 /**