drm: document uAPI page-flip flags

[Ville Syrjälä]

On Tue, Aug 30, 2022 at 11:16:26AM +0300, Pekka Paalanen wrote:
> 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.

For i915 we emit the event when the hardware has indicated the
flip has completed (ie. it has really started scanout from the
new fb). After that you can safely reuse the old fb without
accidentally doing frontbuffer rendering. It takes a bit of
time (some smallish number of scanlines) for the hardware to
flush the FIFOs/TLBs/whatever.

And IIRC we just send the last sampled vblank timestamp for
the event. That is, the timestamp should look the same as
for a sync flip submitted during the previous frame. I was
thinking of making it more or less show the current time
of the flip done indication as that's when the scanout
from the new fb starts, but pretty much everyone else was
of the opinion that there is no point in doing that.

-- 
Ville Syrjälä
Intel