drm: document uAPI page-flip flags

[Sebastian Wick]

On Fri, Aug 26, 2022 at 2:17 PM Simon Ser <contact at emersion.fr> wrote:
>
> On Friday, August 26th, 2022 at 11:49, Sebastian Wick <sebastian.wick at redhat.com> wrote:
>
> > > > +/*
> > > > + * 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.
>
> One would need to read the HDMI spec to see if there's anything in
> there about artifacts on AVI InfoFrame change, then figure out whether
> this is a bug in the physical screen itself or whether the kernel
> driver should require ALLOW_MODESET when updating the HDR metadata.

I'm not even sure if that's the right thing to do. ALLOW_MODESET isn't
really about if a commit can lead to visual artifacts but about
keeping the existing links alive (someone with more knowledge on this
subject probably has a better description for this). An async commit
can also introduce visual artifacts for example and there are probably
more cases.

>