drm: document uAPI page-flip flags

[Sebastian Wick]

On Fri, Aug 26, 2022 at 10:58 AM Pekka Paalanen <ppaalanen at gmail.com> wrote:
>
> On Wed, 24 Aug 2022 17:45:06 +0000
> Simon Ser <contact at emersion.fr> wrote:
>
> > Document flags accepted by the page-flip and atomic IOCTLs.
> >
> > Signed-off-by: Simon Ser <contact at emersion.fr>
> > Cc: Daniel Vetter <daniel.vetter at ffwll.ch>
> > ---
> >  include/uapi/drm/drm_mode.h | 44 ++++++++++++++++++++++++++++++++++++-
> >  1 file changed, 43 insertions(+), 1 deletion(-)
> >
> > diff --git a/include/uapi/drm/drm_mode.h b/include/uapi/drm/drm_mode.h
> > index fa953309d9ce..e1b04ffd54c3 100644
> > --- a/include/uapi/drm/drm_mode.h
> > +++ b/include/uapi/drm/drm_mode.h
> > @@ -935,12 +935,30 @@ struct hdr_output_metadata {
> >       };
> >  };
> >
> > +/**
> > + * DRM_MODE_PAGE_FLIP_EVENT
> > + *
> > + * Request that the kernel sends back a vblank event (see
> > + * struct drm_event_vblank) when the page-flip is done.
>
> ...with type = DRM_EVENT_FLIP_COMPLETE?
>
> This was a bit new to me, because libdrm abstracts vblank and pageflip
> events into different APIs.
>
> > + */
> >  #define DRM_MODE_PAGE_FLIP_EVENT 0x01
> > +/**
> > + * DRM_MODE_PAGE_FLIP_ASYNC
> > + *
> > + * Request that the page-flip is performed as soon as possible, ie. with no
> > + * delay due to waiting for vblank. This may cause tearing to be visible on
> > + * the screen.
>
> Btw. does the kernel fail the flip if the driver does not support async?
> Or does it silently fall back to sync flip?
> Asking for both legacy and atomic APIs.
>
> > + */
> >  #define DRM_MODE_PAGE_FLIP_ASYNC 0x02
> >  #define DRM_MODE_PAGE_FLIP_TARGET_ABSOLUTE 0x4
> >  #define DRM_MODE_PAGE_FLIP_TARGET_RELATIVE 0x8
> >  #define DRM_MODE_PAGE_FLIP_TARGET (DRM_MODE_PAGE_FLIP_TARGET_ABSOLUTE | \
> >                                  DRM_MODE_PAGE_FLIP_TARGET_RELATIVE)
> > +/**
> > + * DRM_MODE_PAGE_FLIP_FLAGS
> > + *
> > + * Bitmask of flags suitable for &drm_mode_crtc_page_flip_target.flags.
> > + */
> >  #define DRM_MODE_PAGE_FLIP_FLAGS (DRM_MODE_PAGE_FLIP_EVENT | \
> >                                 DRM_MODE_PAGE_FLIP_ASYNC | \
> >                                 DRM_MODE_PAGE_FLIP_TARGET)
> > @@ -1034,11 +1052,35 @@ struct drm_mode_destroy_dumb {
> >       __u32 handle;
> >  };
> >
> > -/* page-flip flags are valid, plus: */
> > +/**
> > + * DRM_MODE_ATOMIC_TEST_ONLY
> > + *
> > + * Do not apply the atomic commit, instead check whether the hardware supports
> > + * this configuration.
> > + *
> > + * See drm_mode_config_funcs.atomic_check for more details on test-only
> > + * commits.
> > + */
> >  #define DRM_MODE_ATOMIC_TEST_ONLY 0x0100
> > +/**
> > + * DRM_MODE_ATOMIC_NONBLOCK
> > + *
> > + * Do not block while applying the atomic commit.
>
> Maybe add something like:
>
>         The atomic commit ioctl returns immediately instead of waiting
>         for the changes to be applied in hardware.
>
> > + */
> >  #define DRM_MODE_ATOMIC_NONBLOCK  0x0200
> > +/**
> > + * DRM_MODE_ATOMIC_ALLOW_MODESET
> > + *
> > + * Allow the update to result in visible artifacts such as a black screen.
>
> Maybe add:
>
>         ...temporary or transient visible artifacts while the update is
>         being applied. Applying the update may also take significantly
>         more time than a page flip. The visual artifacts will not
>         appear after the update is completed.
>
>         This flag must be set when the KMS update might cause visible
>         artifacts. Without this flag such KMS update will return EINVAL
>         error. What kind of updates may cause visible artifacts depends
>         on the driver and the hardware. Userspace that needs to know
>         beforehand if an update might cause visible artifacts can use
>         DRM_MODE_ATOMIC_TEST_ONLY without DRM_MODE_ATOMIC_ALLOW_MODESET
>         to see if it fails.
>
>         Visual artifacts are guaranteed to not appear when this flag is
>         not set.

That doesn't seem to be true, though. For example setting
HDR_OUTPUT_METADATA for example does result in visual artifacts on my
display no matter if the flag is specified or not because the
artifacts are not the result of a mode set but of the display reacting
to some AVI InfoFrame.

>
> That "artifacts will not appear after the update is completed" is a bit
> awkward, because when this commit completes and triggers the completion
> event (if requested), the visual artifacts might still be on screen, but
> as soon as the scanout cycle that just started finishes, all artifacts
> are gone for good. Isn't that how it works?
>
> Or does the kernel wait with the completion event until a good picture
> has been fully scanned out at least once? I'd expect not.
>
> > + */
> >  #define DRM_MODE_ATOMIC_ALLOW_MODESET 0x0400
> >
> > +/**
> > + * DRM_MODE_ATOMIC_FLAGS
> > + *
> > + * Bitfield of flags accepted by the &DRM_IOCTL_MODE_ATOMIC IOCTL in
> > + * &drm_mode_atomic.flags.
> > + */
> >  #define DRM_MODE_ATOMIC_FLAGS (\
> >               DRM_MODE_PAGE_FLIP_EVENT |\
> >               DRM_MODE_PAGE_FLIP_ASYNC |\
>
>
> Thanks,
> pq