drm: document uAPI page-flip flags

[Ville Syrjälä]

On Tue, Aug 30, 2022 at 12:00:50PM +0300, Pekka Paalanen wrote:
> On Tue, 30 Aug 2022 11:41:39 +0300
> Ville Syrjälä <ville.syrjala at linux.intel.com> wrote:
> 
> > On Tue, Aug 30, 2022 at 11:16:26AM +0300, Pekka Paalanen wrote:
> 
> > > 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.
> 
> Ugh. So we have two different meanings for the completion timestamp:
> 
> sync flip: when the first pixel from the new FB is emitted into the
> 	video signal
> 
> async flip: something irrelevant
> 
> *sigh*
> 
> To me it would make sense for both to use the same definition, if
> that's technically possible. The point is to know roughly where the
> tear line is which could then answer the question "did it actually
> tear" which is related to the silent falling back to sync flips.

Yeah, that was pretty much my original thinking as well. Just
no one else was interested in it so I figured it's better to
not deviate from the common behaviour.

At least for i915 it shouldn't be too hard to do it properly.
The biggest complication would be untangling the drm_vblank
midlayer somehow.

-- 
Ville Syrjälä
Intel