[PATCH 2/4] drm/doc: document interactions between PAGE_FLIP_EVENT and atomic

[Pekka Paalanen]

On Wed, 12 Jul 2023 13:57:28 +0000
Simon Ser <contact at emersion.fr> wrote:

> Explain which CRTCs get an event, and uAPI requirements.
> 
> Signed-off-by: Simon Ser <contact at emersion.fr>
> Cc: Pekka Paalanen <pekka.paalanen at collabora.com>
> Cc: Daniel Vetter <daniel.vetter at ffwll.ch>
> ---
>  include/uapi/drm/drm_mode.h | 4 ++++
>  1 file changed, 4 insertions(+)
> 
> diff --git a/include/uapi/drm/drm_mode.h b/include/uapi/drm/drm_mode.h
> index 92d96a2b6763..c32b171c0ba7 100644
> --- a/include/uapi/drm/drm_mode.h
> +++ b/include/uapi/drm/drm_mode.h
> @@ -946,6 +946,10 @@ 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 the atomic uAPI, vblank events will be sent for every CRTC
> + * included in the commit. At least one CRTC must be included, and all included
> + * CRTCs must be turned on.
>   */
>  #define DRM_MODE_PAGE_FLIP_EVENT 0x01
>  /**

What about interactions with DRM_CAP_CRTC_IN_VBLANK_EVENT?

Is there one event per CRTC even without the cap? And in that case
userspace cannot see which CRTC an event is for, but it must wait for
the correct number of events to be sure each one completed? Which is
horribly fragile, so maybe we should recommend to not even try without
the cap?

FWIW, Weston does not use atomic without the cap, so I can't peek there.

What does "including a CRTC in a commit" mean? I think a CRTC is
included if the commit touches any plane on the CRTC, but there is no
need to touch any CRTC property to have the CRTC included, right?
Touching connector properties pulls in the CRTC as well?


Thanks,
pq