[PATCH] drm_mode: document that pageflip events must always be sent

[Xaver Hugl]

There's no way to signal failure to userspace, so if the ioctl requesting
the event succeeds, the kernel must *always* send the event, or userspace
will be stuck, forever waiting for the event that never comes.

Signed-off-by: Xaver Hugl <xaver.hugl at kde.org>
---
 include/uapi/drm/drm_mode.h | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/include/uapi/drm/drm_mode.h b/include/uapi/drm/drm_mode.h
index c082810c08a8..30611d561c5a 100644
--- a/include/uapi/drm/drm_mode.h
+++ b/include/uapi/drm/drm_mode.h
@@ -962,6 +962,12 @@ 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.
+ *
+ * It's the responsibility of the kernel to ensure that, if the ioctl
+ * requesting the page-flip event succeeds, the event is actually sent.
+ * Because there's no way to signal failure to userspace after the ioctl
+ * returns, this must be upheld even if the page-flip never actually
+ * happens (because of a GPU reset, hotunplug or driver bug).
  */
 #define DRM_MODE_PAGE_FLIP_EVENT 0x01
 /**
-- 
2.48.0