drm: document uAPI page-flip flags

[Simon Ser]

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.