drm: document uAPI page-flip flags

[Simon Ser]

CC Ville for the ASYNC bits, see below.

On Friday, August 26th, 2022 at 10:53, Pekka Paalanen <ppaalanen at gmail.com> wrote:

> > +/**
> > + * 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.

Indeed.

Maybe should clarify what "done" means here? Would "when the page-flip has been
displayed on-screen" be correct?

> > + */
> >  #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.

Atomic doesn't support this yet, so it's pretty much TBD (see Ville's reply [1]).

For legacy, it seems like drivers do what they want. AFAIU, i915 will reject
(see intel_async_flip_check_uapi etc), and amdgpu will silently fall back to
vsync (see the `acrtc_state->update_type == UPDATE_TYPE_FAST` check in
amdgpu_dm_commit_planes).

Maybe one of the drivers is wrong here and should be fixed?

[1]: https://lore.kernel.org/dri-devel/YwiB%2FxQf6Z6ScU+Z@intel.com/

> > +/**
> > + * 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.

Good idea. Also added:

    Note, the driver will still check that the update can be applied before
    retuning.

> > + */
> >  #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 "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.

That generally looks like a good description to me, and AFAIK is how things
work indeed.