From 9ba2065b63ea0e61a17b8221ad454c02a1755373 Mon Sep 17 00:00:00 2001 From: James Jones Date: Wed, 11 Aug 2010 15:03:59 -0700 Subject: Document changes in XSync version 3.1 Signed-off-by: James Jones Reviewed-by: Pierre-Loup Griffais Reviewed-by: Aaron Plattner Reviewed-by: Robert Morell Acked-by: Alan Coopersmith --- specs/sync.xml | 229 ++++++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 220 insertions(+), 9 deletions(-) diff --git a/specs/sync.xml b/specs/sync.xml index a8064a9..e61dc17 100644 --- a/specs/sync.xml +++ b/specs/sync.xml @@ -32,6 +32,11 @@ by TeX4ht (http://www.cse.ohio-state.edu/~gurari/TeX4ht/) xhtml,docbook,html,ref Wiggins X Consortium, Inc. + + James + Jones + NVIDIA Corporation + X Consortium Standard @@ -43,8 +48,9 @@ Digital Equipment Corporation, Maynard, Massachusetts 1991X Consortium + 2010NVIDIA Corporation - Version 3.0 + Version 3.1 X Consortium X Version 11, Release 6.8 @@ -52,10 +58,10 @@ Digital Equipment Corporation, Maynard, Massachusetts Permission to use, copy, modify, and distribute this documentation for any purpose and without fee is hereby granted, provided that the above -copyright notice appear in all copies. Olivetti, Digital, MIT, and the -X Consortium make no representations about the suitability for any purpose -of the information in this document. This documentation is provided as -is without express or implied warranty. +copyright notice appear in all copies. Olivetti, Digital, MIT, the +X Consortium, and NVIDIA make no representations about the suitability for +any purpose of the information in this document. This documentation is +provided as is without express or implied warranty. @@ -133,12 +139,17 @@ frame marker. -The extension adds Counter and -Alarm to the set of resources managed by the +The extension adds Counter, Alarm, +and Fence 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. Alarms generate events when +counter values go through a specified transition. 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. Fences are bound to a +particular screen at creation time. @@ -168,6 +179,21 @@ clients to receive an event on a regular basis when a particular counter is changed. + +The CreateFence request allows a client to create a +Fence that can be triggered and reset using +TriggerFence and ResetFence +requests, respectively. CreateFence takes a drawable +argument that implies which screen the fence should be created on. The +TriggerFence request changes the fence's state only +after all previous rendering commands affecting objects owned by the given +fence's screen have completed. Note that while fence objects are bound +to a screen and the simple trigger operation provided by this extension +operates at screen granularity, other extensions may add more fine-grained +trigger operations based on any number of events. The screen binding +merely establishes an upper bound for the scope of fence operations. + + Types @@ -201,6 +227,7 @@ SYSTEMCOUNTER: [ ] ALARM: XID ALARMSTATE: {Active,Inactive,Destroyed} +FENCE: XID @@ -283,6 +310,14 @@ registry of system counter names to avoid collisions in the name space. An ALARM is the client-side handle on an Alarm resource. + + +The FENCE type defines the client-side handle on a server +Fence. A fence can only be in one of two states, +represented by a BOOL. If the value is TRUE, the fence is in the triggered +state. Otherwise, the fence is in the not triggered state. + + @@ -307,6 +342,15 @@ does not name a defined ALARM. + + Fence + + +This error is generated if the value for a FENCE argument in a request +does not name a defined FENCE. + + + @@ -341,7 +385,7 @@ and v1.version_minor <= v2.version_minor. Compatible means that the functionality is fully supported in an identical fashion in the two versions. -This document describes major version 3, minor version 0 of the SYNC protocol. +This document describes major version 3, minor version 1 of the SYNC protocol. @@ -740,6 +784,118 @@ server. + + CreateFence + + +drawable: DRAWABLE +id: FENCE +initially-triggered: BOOL +Errors: IDChoice,Alloc + + +This request creates a fence on the screen associated with drawable and +assigns the specified id to it. The fence is in the triggered state iff +initially-triggered is TRUE. There are no clients waiting on the fence. + + + + + TriggerFence + + +fence: FENCE +Errors: Fence + + +This request puts the given fence in the triggered state after all rendering +from previous requests that affects resources owned by the fence's screen has +completed. This includes requests from other clients if those requests have +been dispatched. This request has no visible effects if the fence was already +in the triggered state. A Fence error is generated if +fence does not name a valid fence. + + +Note that the given fence's state is not necessarily directly modified by this +request. The state change need only be queued to occur after the required +rendering has completed. Clients should take care to not assume the fence will +be in the triggered state in subsequent requests, such as those that operate +on the given fence immediately. AwaitFence should first +be issued if subsequent requests require the fence to be in the triggered +state. + + + + + ResetFence + + +fence: FENCE +Errors: Fence,Match + + +This request immediately puts the given fence in the not triggered state. +A Match error is generated if the fence is not in the +triggered state. A Fence error is generated if fence +does not name a valid fence. + + +See the warnings above regarding TriggerFence's delayed +effect. In particular, a TriggerFence request +immediately followed by a ResetFence request is likely +to result in a Match error. An +AwaitFence request should be issued between the two. + + + + + DestroyFence + + +fence: FENCE +Errors: Fence + + +This request destroys the given fence. All clients waiting on this fence are +released. A fence is destroyed automatically when the connection to the client +that created the fence is closed if the close-down mode is +DestroyAll. A Fence error is +generated if fence does not name a valid fence. + + + + + QueryFence + + +fence: FENCE +=> +triggered: BOOL +Errors: Fence + + +This request returns TRUE if the given fence is triggered, or FALSE if it +is not triggered. A Fence error is generated if +fence does not name a valid fence. + + + + + AwaitFence + + +fence-list: LISTofFENCE +Errors: Fence,Alloc + + +When this request is executed, the processing of further requests for the +client is blocked until one or more of the fences in fence-list reaches the +triggered state. If any of the fences are already in the triggered state, +request processing resumes immediately. A Fence error +is generated if any member of fence-list does not name a valid fence. + + + @@ -844,6 +1000,7 @@ TRIGGER: WAITCONDITION: 20 TRIGGER trigger 8 INT64 event threshold +FENCE: CARD32 @@ -872,6 +1029,14 @@ groups, the byte ordering determined during connection setup is used. 2 CARD16 minor opcode 1 CARD8 major opcode 21 unused +Fence + 1 0 Error + 1 Base + 2 code + 2 CARD16 sequence number + 4 CARD32 bad fence + 2 CARD16 minor opcode + 1 CARD8 major opcode + 21 unused @@ -1026,6 +1191,52 @@ GetPriority 4 INT32 priority 20 unused +CreateFence + 1 CARD8 major opcode + 1 14 minor opcode + 2 4 request length + 4 DRAWABLE drawable + 4 FENCE id + 1 BOOL initially triggered + 3 unused + +TriggerFence + 1 CARD8 major opcode + 1 15 minor opcode + 2 2 request length + 4 FENCE id + +ResetFence + 1 CARD8 major opcode + 1 16 minor opcode + 2 2 request length + 4 FENCE id + +DestroyFence + 1 CARD8 major opcode + 1 17 minor opcode + 2 2 request length + 4 FENCE id + +QueryFence + 1 CARD8 major opcode + 1 18 minor opcode + 2 2 request length + 4 FENCE id +=> + 1 1 Reply + 1 unused + 2 CARD16 sequence number + 4 0 reply length + 1 BOOL triggered + 23 unused + +AwaitFence + 1 CARD8 major opcode + 1 19 minor opcode + 2 1 + n request length + 4*n LISTofFENCE wait conditions + -- cgit v1.2.1