[PATCH xextproto 1/4] Document changes in XSync version 3.1

[James Jones]

On Tuesday 17 August 2010 15:01:53 Aaron Plattner wrote:
> On Tue, Aug 17, 2010 at 02:49:41PM -0700, Adam Jackson wrote:
> > Apologies for the slow review here...

No worries.  Thanks for taking the time.

> > On Thu, 2010-08-12 at 16:40 -0700, James Jones wrote:
> > >  <para>
> > > 
> > > -The extension adds <function>Counter</function> and
> > > -<function>Alarm</function> to the set of resources managed by the
> > > +The extension adds <function>Counter</function>,
> > > <function>Alarm</function>, +and <function>Fence</function> to the set
> > > of resources managed by the
> > > 
> > >  server. A counter has a 64-bit integer value that may be increased or
> > >  decreased by client requests or by the server internally. A client can
> > >  block by sending an Await request that waits until one of a set of
> > >  synchronization
> > > 
> > > -conditions, called TRIGGERs, becomes TRUE.
> > > +conditions, called TRIGGERs, becomes TRUE.  A fence has two possible
> > > states: +triggered and not triggered. Client requests can put the
> > > fence in either of +these states. A client can block until one of a
> > > set of fences becomes +triggered by sending an AwaitFence request.
> > > 
> > >  </para>
> > 
> > I feel like this whole section wants a rewrite, since Alarms aren't
> > discussed until much later.  Would be worthwhile if doing so to note
> > that Fences are explicitly bound to a screen (though I wouldn't insist
> > on it to get this merged).  And on that subject...
> > 
> > > +<para>
> > > +The <function>CreateFence</function> request allows a client to create
> > > a +<function>Fence</function> that can be triggered and reset using
> > > +<function>TriggerFence</function> and <function>ResetFence</function>
> > > +requests, respectively.  The <function>TriggerFence</function>
> > > request changes +the fence's state only after all previous rendering
> > > commands affecting objects +owned by the given fence's screen have
> > > completed.
> > > +</para>
> > 
> > I'm a little unclear on _why_ they're bound to screens.  What semantics
> > does that imply?  The only reason I can imagine wanting to do so in the
> > protocol is if the server itself would ever trigger a Fence on a
> > Drawable, because then you'd need to wire the Fence to the right
> > ScreenRec.  But it seems like that should never happen for
> > client-created Fences, only for server-created Fences.
> 
> James, correct me if I'm wrong, but I don't think the server ever creates
> fences on its own; they're *all* client-created.  Fences trigger when the
> rendering for the corresponding X screen is done, for requests that were
> processed before the triggering request.  Rendering could still be pending
> on other screens, and there could be later rendering queued on the same
> screen for later requests.

Aaron's correct.  I chose to give the key fence operations a defined ordering 
with respect to rendering operations from all clients on a given screen.  To 
do so, I needed to associate a screen with a fence.  That could either be done 
at creation time, or trigger/other operation time.  Creation time is the only 
way to implement these such that they're reasonable to push down to a GPU, 
and/or import to other APIs like OpenGL sync objects.

More background: X requests from one client execute in a defined order only 
with respect to other requests from that client.  The X Sync extension 
provides synchronization across clients, but the existing X sync extension 
mechanisms assume all X operations complete instantaneously, or at least in 
the order in which X processes them.  This assumption breaks down when direct 
rendering clients are rendering out-of-band with respect to X rendering, or 
even if an X driver has multiple rendering backends, say one per client or one 
per screen, that process commands simultaneously or in an undefined order with 
respect to each other.  Specifying that fence triggers complete after all 
previous requests from the triggering client is too fine-grained, and not 
really that useful of an operation anyway since they are meant to be used to 
synchronize multiple clients.  Server-wide seemed too coarse-grained.  The 
operations fence syncs are meant to synchronize are rendering operations.  All 
X rendering operations (I'm sure someone is going to correct me with an 
exception here) operate on per-screen objects.  The wrapping mechanisms the 
DDX uses to expose driver hooks are mostly per-screen.  Hence, it made sense 
to make the fence objects screen-specific as well.

I'll make another pass and try to capture more of the above in the spec, in 
addition to making more intrusive updates to the sections you reference above.  
I'll send those out when I send out the xserver changes.  I tried a few 
directions with the server code, and feel the current spec/implementation fell 
out most naturally from the existing architecture, so having the code to look 
at side-by-side with the proto patches might help.  If anyone wants to get 
ahead of me, the latest xserver changes are available on my github repos at

http://github.com/cubanismo/xserver/tree/fence_sync

> The idea is that a client creates a Fence on a given X screen, binds it to
> an OpenGL sync object using a to-be-created GLX extension, then in response
> to an XDamageNotify, sends DamageSubtractAndTrigger, tells OpenGL to wait
> for the corresponding OpenGL side of the fence, and then performs the
> rendering using OpenGL.  This makes the GL wait (on the GPU, ideally) for
> the X rendering on that screen to finish without making the client itself
> wait on the CPU.

See the damageproto changes for a bit more background, but they basically just 
say what Aaron said above.

Thanks,
-James