drm: document uAPI page-flip flags

Tue Aug 30 08:16:26 UTC 2022

On Mon, 29 Aug 2022 15:37:52 +0000
Simon Ser <contact at emersion.fr> wrote:

> 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?

Good idea, but definition is not quite that AFAIU. I would understand
"displayed" as "turned into light" or at least fully sent to the cable,
when we are talking at this level of detail.

Hence, "has been displayed" is not it because the flip-done event is
emitted before the new FB contents have been scanned out. That scanout
cycle is only starting when the flip is done. The flip timestamp should
correspond to the time when the first real pixel of the new FB hits the
monitor cable.

A flip is done, when it is guaranteed that the next (or on-going, in
case of tearing) scanout cycle will use the new FB, IOW the hardware
programming has been done I believe.

If the flip is sync'd to vblank, the timestamp is as above, but the
actual event might be emitted somewhat before or after the instant of
the timestamp. Some drivers can predict the timestamp so can send the
event early, others don't.

If the flip is tearing, then I'm not sure what the timestamp is or when
the event is emitted.

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

So atomic commit ioctl will fail with EINVAL because userspace is
giving it an unrecognized flag?

[1] is interesting. Apparently the atomic async flag will only be a
hint, "make it tear if possible". That seems fine to me.

> 
> 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.

Nice.

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

Yeah, but swick has a good point: should we be talking about literal
visual artifacts or do we only guarantee that the video signal on the
cable is uninterrupted?

HDR_OUTPUT_METADATA is the prime example where that matters. It is
infoframe data, which means changing it will never cause any
interruption in the video signal. However, changing certain fields (and
not with other fields) in the infoframe is likely to cause the monitor
to glitch or blank for a moment.

Thanks,
pq
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 833 bytes
Desc: OpenPGP digital signature
URL: <https://lists.freedesktop.org/archives/dri-devel/attachments/20220830/50a63568/attachment.sig>