Document the Timer routines in the ddx interface, which are used by various

    facilities, and have not been documented before.
Lots more work is needed to flesh out new facilities; this document hasn't
    been touched in 10 years!!!

1 files changed, 118 insertions, 18 deletions

diff --git a/specs/Xserver/ddx.tbl.ms b/specs/Xserver/ddx.tbl.ms
index 53bc80c..4db72b1 100644
--- a/specs/Xserver/ddx.tbl.ms
+++ b/specs/Xserver/ddx.tbl.ms
@@ -1,6 +1,6 @@
 .\" $Xorg: ddx.tbl.ms,v 1.3 2000/08/17 19:42:41 cpqbld Exp $
-.EF 'Porting Layer Definition'- % -'April 8, 1994'
-.OF 'Porting Layer Definition'- % -'April 8, 1994'
+.EF 'Porting Layer Definition'- % -'October 27, 2004'
+.OF 'Porting Layer Definition'- % -'October 27, 2004'
 .EH '''
 .OH '''
 .TL
@@ -34,11 +34,17 @@ Revised for Release 6 by
 David P. Wiggins
 .AI
 X Consortium
+.sp
+Minor Revisions for Release 6.8.2 by
+.AU
+Jim Gettys
+.AI
+X.org Foundation and Hewlett Packard
 .LP
 .bp
 \&
 .sp 15
-Copyright \(co 1994 X Consortium
+Copyright \(co 1994 X Consortium, Inc., 2004 X.org Foundation, Inc.
 .LP
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the ``Software''), to deal
@@ -58,6 +64,24 @@ AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
 CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 .bp
 .LP
+Note to the 2004 edition: at this time this document must be considered incomplete.
+In particular, the new Render extension is still lacking good documentation,
+and has become vital to high performance X implementations.
+A new "fb" portable frame buffer graphics library (replacing "cfb") 
+is used by most implementations
+to implement software rendering for most operations. Accelerating only a few
+of the old "core" graphics functions is now needed,
+as performance in software is "good enough" for most operations.
+Modern applications 
+and desktop environments are now
+much more sensitive to good implementation of the Render extension than in
+most operations of the old X graphics model. 
+The shadow frame buffer implementation is also very useful in many circumstances,
+and also needs documentation.
+We hope to rectify these shortcomings in our documentation
+in the future.
+Help would be greatly appreciated.
+.LP
 The following document explains the
 structure of the X Window System display server and the interfaces among the larger pieces.
 It is intended as a reference for programmers who are implementing an X Display Server
@@ -65,21 +89,17 @@ on their workstation hardware.
 It is included with the X Window System source tape,
 along with the document "Strategies for Porting the X v11 Sample Server."
 The order in which you should read these documents is:
-
 .IP 1) 
 Read the first section 
 of the "Strategies for Porting" document (Overview of Porting Process).
-
 .IP 2) 
 Skim over this document (the Definition document).
-
 .IP 3) 
 Skim over the remainder of the Strategies document.
-
 .IP 4) 
 Start planning and working, referring to the Strategies
 and Definition documents.
-
+.LP
 You may also want to look at the following documents:
 .IP \(bu 5
 "The X Window System"
@@ -96,7 +116,7 @@ LK201 and DEC are trademarks of Digital Equipment Corporation.
 Macintosh and Apple are trademarks of Apple Computer, Inc.
 PostScript is a trademark of Adobe Systems, Inc.
 Ethernet is a trademark of Xerox Corporation.
-X Window System is a trademark of X Consortium, Inc.
+X Window System is a trademark of the X.org Foundation, Inc.
 Cray is a trademark of Cray Research, Inc.
 
 .LP
@@ -114,14 +134,15 @@ and (possibly) its networking and multitasking facilities.
 This document depends a lot on the source code,
 so you should have a listing of the code handy.
 .LP
-Some source on the distribution tape is directly compilable
+Some source in the distribution is directly compilable
 on your machine.
 Some of it will require
 modification.
 Other parts may have to be completely written from scratch.
 .LP
-The tape also includes source for a sample implementation of a display
-server which runs on a variety of color and monochrome displays which you
+The distribution also includes source for a sample implementation of a display
+server which runs on a very wide variety of color and monochrome displays on
+Linux and *BSD which you
 will find useful for implementing any type of X server.
 
 
@@ -142,6 +163,8 @@ per pixel with a special graphics processor doing the work.  (In this
 document, monochrome means a black and white display with one bit per pixel.
 Even though the usual meaning of monochrome is more general, this special
 case is so common that we decided to reserve the word for this purpose.)
+In practice, monochrome displays are now almost unheard of, with 4 bit
+gray scale displays being the low end.
 
 X is designed for a networking environment where 
 users can run applications on machines other than their own workstations.
@@ -370,7 +393,7 @@ Some parts are events delivered to the client, such as keystrokes from the user.
 The processing of events and requests for different
 clients can be interleaved with one another so true multitasking
 is not needed in the server.
-
+.LP
 You must supply some of the pieces for proper scheduling between clients.
 .nf
 
@@ -391,7 +414,8 @@ you should return a count of clients stored in pClientReady
 A new client tries to connect, in which case you should create the
 client and  then continue waiting
 .LP
-Before WaitForSomething() computes the masks to pass to select, it needs to
+Before WaitForSomething() computes the masks to pass to select, poll or 
+similar operating system interface, it needs to
 see if there is anything to do on the work queue; if so, it must call a DIX
 routine called ProcessWorkQueue.
 .nf
@@ -402,7 +426,7 @@ routine called ProcessWorkQueue.
 .fi
 .LP
 If WaitForSomething() decides it is about to do something that might block
-(in the sample server,  before it calls select()) it must call a DIX
+(in the sample server,  before it calls select() or poll) it must call a DIX
 routine called BlockHandler().
 .nf
 
@@ -445,7 +469,8 @@ WakeupHandler().
 Once again,  the types are not specified by DIX.  The result is the
 success indicator for the thing that (may have) blocked,
 and the pReadmask is a mask of the descriptors that came active.
-In the sample server,  result is the result from select(),  and pReadmask is
+In the sample server,  result is the result from select() (or equivalent
+operating system function),  and pReadmask is
 the address of the select() mask for reading.
 .LP
 The DIX WakeupHandler() calls each Screen's
@@ -492,6 +517,19 @@ These registered block handlers are called after the per-screen handlers:
 		pointer	pReadmask;
 .fi
 .LP
+Sometimes block handlers need to adjust the time in a OSTimePtr structure,
+which on UNIX family systems is generally represented by a struct timeval
+consisting of seconds and microseconds in 32 bit values.
+As a convenience to reduce error prone struct timeval computations which
+require modulus arithmetic and correct overflow behavior in the face of
+millisecond wrapping throrugh 32 bits,
+.nf
+
+	void AdjustWaitForDelay(pointer /*waitTime*, unsigned long /* newdelay */)
+
+.fi
+has been provided.
+.LP
 Any wakeup handlers registered with RegisterBlockAndWakeupHandlers will
 be called before the Screen handlers:
 .nf
@@ -522,6 +560,8 @@ For instance, if your implementation always checks for client data first and doe
 report any input events until there is no client data left,
 your mouse and keyboard might get locked out by an application that constantly
 barrages the server with graphics drawing requests.
+Therefore, as a general rule, input devices should always have priority over graphics
+devices.
 .LP
 A list of indexes (client->index) for clients with data ready to be read or
 processed should be returned in pClientReady, and the count of indexes
@@ -572,6 +612,59 @@ Input Procedures that are stored in the DeviceRec (the
 routine passed to AddInputDevice()).
 The sample server implementation of AddEnabledDevice
 and RemoveEnabledDevice are in Xserver/os/connection.c.
+.NH 3
+Timer Facilities
+.XS
+Timer Facilities
+.XE
+.LP
+Similarly, the X server or an extension may need to wait for some timeout. 
+Early X releases implemented this functionality using block and wakeup handlers,
+but this has been rewritten to use a general timer facilty, and the
+internal screen saver facilties reimplemented to use Timers.
+These functions are TimerInit, TimerForce, TimerSet, TimerCheck, TimerCancel, 
+and TimerFree, as defined in Xserver/include/os.h. A callback function will be called
+when the timer fires, along with the current time, and a user provided argument.
+.nf
+	typedef	struct _OsTimerRec *OsTimerPtr;
+
+	typedef CARD32 (*OsTimerCallback)(
+		OsTimerPtr /* timer */,
+		CARD32 /* time */,
+		pointer /* arg */);
+
+	 OsTimerPtr TimerSet( OsTimerPtr /* timer */,
+		int /* flags */,
+		CARD32 /* millis */,
+		OsTimerCallback /* func */,
+		pointer /* arg */);
+
+.fi
+.LP
+TimerSet returns a pointer to a timer structure and sets a timer to the specified time
+with the specified argument.  The flags can be TimerAbsolute and TimerForceOld.
+The TimerSetOld flag controls whether if the timer is reset and the timer is pending, the
+whether the callback function will get called.
+The TimerAbsolute flag sets the callback time to an absolute time in the future rather
+than a time relative to when TimerSet is called.
+TimerFree should be called to free the memory allocated
+for the timer entry.
+.nf
+	void TimerInit(void)
+
+	Bool TimerForce(OsTimerPtr /* pTimer */)
+
+	void TimerCheck(void);
+
+	void TimerCancel(OsTimerPtr /* pTimer */)
+
+	void TimerFree(OSTimerPtr /* pTimer */)
+.fi
+TimerInit frees any exisiting timer entries. TimerForce forces a call to the timer's
+callback function and returns true if the timer entry existed, else it returns false and
+does not call the callback function. TimerCancel will cancel the specified timer.
+TimerFree calls TimerCancel and frees the specified timer.
+Calling TimerCheck will force the server to see if any timer callbacks should be called.
 .NH 2
 New Client Connections
 .XS
@@ -5039,6 +5132,7 @@ AddCallback	dix
 AddEnabledDevice	os
 AddInputDevice	dix
 AddScreen	dix
+AdjustWaitForDelay	os
 Bell	hd	Device
 ChangeClip	mi	GC func
 ChangeGC		GC func
@@ -5072,7 +5166,6 @@ DestroyPixmap	ddx	Screen
 DestroyWindow	ddx	Screen
 DisplayCursor	hd	Screen
 Error	os
-ErrorF	os
 .TE
 .bp
 .TS
@@ -5081,6 +5174,7 @@ c c c
 l c l.
 Procedure	Port	Struct
 _
+ErrorF	os
 FatalError	os
 FillPolygon	mi	GC op
 FillSpans	ddx	GC op
@@ -5131,7 +5225,6 @@ PushPixels	mi	GC op
 PutImage	mi	GC op
 QueryBestSize	hd	Screen
 ReadRequestFromClient	os	
-RealizeCursor	hd	Screen
 .TE
 .bp
 .TS
@@ -5140,6 +5233,7 @@ c c c
 l c l.
 Procedure	Port	Struct
 _
+RealizeCursor	hd	Screen
 RealizeFont	ddx	Screen
 RealizeWindow	ddx	Screen
 RecolorCursor	hd	Screen
@@ -5165,6 +5259,12 @@ SetInputCheck	dix
 SetSpans	ddx	GC op
 StoreColors	ddx	Screen
 Subtract	mi	Screen
+TimerCancel	os
+TimerCheck	os
+TimerForce	os
+TimerFree	os
+TimerInit	os
+TimerSet	os
 TimeSinceLastInputEvent	hd
 TranslateBackingStore	none	BackingStore
 TranslateRegion	mi	Screen