| blob | e410906f9a94f6384ca0dbcad1daf3b927c2eb74 |
2 README for XFree86 OS-support Layer
3 -----------------------------------
5 Contents
6 --------
7 1) Overview
8 2) Directory Layout
9 3) Adding a new OS
10 4) OS Support API
12 1 - Overview
13 ------------
14 This directory contains the OS support layer functions for the XFree86
15 servers. In addition, some miscellaneous server support functions (not
16 OS-dependent) are included here, to take advantage of the fact that this
17 library comes last in the linking order.
19 Most of the functionality required to support a new OS is encapsulated in
20 this library. It is hoped that all OS-specific details can be encapsulated,
21 but that is not likely ever to be completely possible. Hence some minor
22 changes will wind up being made in other parts of the server. The major
23 design principles for this library are maintainability, readability, and
24 portability. Sometimes these goals conflict; some somewhat arbitrary choices
25 have been made in implementation.
27 2 - Directory Layout
28 --------------------
29 os-support/ Contains headers and documentation; no code
30 misc/ Non-OS-specific miscellaneous functions that
31 fit best into the link architecture this way.
32 shared/ Contains files with functions used by more than one
33 OS. These are symlinked into the OS subdirectories
34 at build time via Imakefile rules. This is alway
35 preferable to reproducing functions in more than one
36 OS library.
37 bsd/ OS support for the 386BSD/NetBSD/FreeBSD operating
38 systems.
39 bsdi/ OS support for the BSD/386 operating system.
40 linux/ OS support for the Linux operating system.
41 sco/ OS support for the SCO SVR3.x operating system.
42 solx86/ OS support for the Solaris x86 operating system.
43 sysv/ OS support for all SVR4.0 and SVR4.2, and for
44 ISC and AT&T SVR3.2 operating systems.
46 3 - Adding A New OS
47 -------------------
48 Adding a support for a new operating system entails implementing all of
49 the functions described in the API below. Many of these functions are no-ops
50 for many operating systems, and appropriate files with dummy declarations are
51 available in the 'shared' subdirectory.
53 If your OS is sufficiently similar to an existing OS, you can make use of
54 the existing subdirectory. One of the reasons for implementing this OS
55 library was the unmaintainability of the spagetti-#ifdef code that existed
56 before. You should try to avoid cluttering the code with #ifdef's. If
57 you find that the subdirectory is getting cluttered, split off into a
58 seperate subdirectory (e.g. as was done for SCO, rather than cluttering
59 the 'sysv' subdirectory). You can split functions out of an existing
60 subdirectory into the 'shared' subdirectory, if that is appropriate. Just
61 remember to update the Imakefile for the old subdirectory.
63 You will still likely have to make some small changes to other parts of
64 the server. You should not put OS-specific #define's or #include's anywhere
65 else in the server. These should all go in the "xf86_OSlib.h" header file
66 in this directory.
68 4 - OS Support API
69 -----------------
70 void xf86OpenConsole(void)
71 {
72 /*
73 * Open console device, activate VTs, etc, etc. Fill in requisite
74 * pieces of xf86Info. Most of this code comes from xf86Init.c
75 */
76 }
78 void xf86CloseConsole(void)
79 {
80 /*
81 * Close console at server exit.
82 */
83 }
85 Bool xf86VTSwitchPending(void)
86 {
87 /*
88 * Returns TRUE iff there is a VT switch operation pending for
89 * the server. In the USL VT model, this is indicated via a
90 * signal handler. Should return FALSE always for OSs without
91 * VTs.
92 */
93 }
95 Bool xf86VTSwitchAway(void)
96 {
97 /*
98 * Handles the OS-specific action for switching away from the active
99 * VT. Returns FALSE if the switch away fails. Should return
100 * FALSE always for OSs without VTs (then again, this function
101 * should never be called in that case).
102 */
103 }
105 Bool xf86VTSwitchTo(void)
106 {
107 /*
108 * Handles the OS-specific action for switching to the active VT.
109 * Returns FALSE if the switch to fails. Should return TRUE
110 * always for OSs without VTs (then again, this function should
111 * never be called in that case).
112 */
113 }
115 Bool xf86LinearVidMem(void)
116 {
117 /*
118 * Returns TRUE if the OS supports mapping linear frame buffers
119 * (ie memory at addresses above physical memory).
120 */
121 }
123 pointer xf86MapVidMem(int ScreenNum, pointer Base, unsigned long Size)
124 {
125 /*
126 * Handle mapping the video memory. Returns (pointer *)0 for
127 * failure; causes server exit. It is allowable to call FatalError()
128 * from inside this function and exit directly.
129 */
130 }
132 void xf86UnMapVidMem(int ScreenNum, pointer Base, unsigned long Size)
133 {
134 /*
135 * Handle unmapping the video memory. This should undo what
136 * xf86MapVidMem() does. Base is a pointer obtained from
137 * a previous call to xf86MapVidMem().
138 */
139 }
141 void xf86MapDisplay(int ScreenNum, int Region)
142 {
143 /*
144 * For OSs that require the screen be mapped when entering a VT.
145 * A dummy function will be defined for OSs that don't require
146 * this (or don't have VTs at all).
147 */
148 }
150 void xf86UnMapDisplay(int ScreenNum, int Region)
151 {
152 /*
153 * For Os that require that the screen be unmapped when leaving a
154 * VT. A dummy function will be defined for OSs that don't require
155 * this (or don't have VTs at all).
156 */
157 }
159 int xf86ReadBIOS(unsigned long Base, unsigned long Offset,
160 unsigned char *Buf, int Len)
161 {
162 /*
163 * Read Len bytes from the BIOS at address Base, offset Offset,
164 * into buffer Buf. Returns -1 for failure or if the OS does
165 * not support reading the BIOS. This causes a driver probe
166 * to fail, but does not cause the server to abort.
167 */
168 }
171 void xf86EnableIOPorts(int ScreenNum)
172 {
173 /*
174 * Enables I/O permissions. The OS layer should
175 * enable all I/O port access.
176 */
177 }
179 void xf86DisableIOPorts(int ScreenNum)
180 {
181 /*
182 * Disables I/O permissions.
183 */
184 }
186 Bool xf86DisableInterrupts(void)
187 {
188 /*
189 * Disable interrupts if allowed for this OS. Returns FALSE if
190 * this is not allowed or if the attempt fails for some reason.
191 */
192 }
194 void xf86EnableInterrupts(void)
195 {
196 /*
197 * Reenable interrupts
198 */
199 }
201 int xf86ProcessArgument(int argc, char *argv[], int i)
202 {
203 /*
204 * Process OS-specific command-line arguments. See
205 * ddxProcessArgument() for more info.
206 */
207 }
209 void xf86UseMsg(void)
210 {
211 /*
212 * Print list of OS-specific command-line arguments. See
213 * ddxUseMsg() for more info.
214 */
215 }
217 void xf86SoundKbdBell(int loudness, int pitch, int duration)
218 {
219 /*
220 * Sound the keyboard bell. pitch is in Hz, duration in ms,
221 * loudness is in the range 0-100 (0 -> off). For systems
222 * where the loudness can't be controlled, scale the duration
223 * by loudness/50.
224 */
225 }
227 void xf86SetKbdLeds(int leds)
228 {
229 /*
230 * Set the keyboard LEDs to the state indicated in leds
231 */
232 }
234 int xf86GetKbdLeds(void)
235 {
236 /*
237 * Return the state of the keyboard LEDs. If the OS doesn't
238 * support this, return 0.
239 */
240 }
242 void xf86SetKbdRepeat(char rad)
243 {
244 /*
245 * Set the keyboard repeat rate and delay according the
246 * the rad value. The lower 5 bits determine the repeat
247 * rate (lower value -> higher rate). The next 2 bits
248 * determine the delay.
249 * This should possibly be changed to take separate rate and
250 * delay parameters.
251 */
252 }
254 void xf86KbdInit(void)
255 {
256 /*
257 * Save initial keyboard state. This is called at the start of
258 * each server generation.
259 */
260 }
262 int xf86KbdOn(void)
263 {
264 /*
265 * Set the keyboard up for use with X. This is called whenever
266 * the server becomes active (ie at the start of each generation and
267 * whenever its VT becomes active). Return the file descriptor
268 * for keyboard input. Return -1 if there is no file descriptor
269 * to add as an input device. If there are errors encountered,
270 * call FatalError(). A return value of -1 is not considered an
271 * error condition.
272 */
273 }
275 int xf86KbdOff(void)
276 {
277 /*
278 * Return the keyboard to the state saved by xf86KbdInit(). This is
279 * called at the end of a server generation, and also when the
280 * server's VT ceases being active. Returns the keyboard file
281 * descriptor. Returns -1 if there is no file descriptor to be
282 * removed as an input device. Errors should be handled the same
283 * way as in xf86KbdOn().
284 */
285 }
287 void xf86KbdEvents(void)
288 {
289 /*
290 * Read characters from the keyboard device, and post the events
291 * by calling xf86PostKbdEvent(). Read as much as is available
292 * without waiting.
293 */
294 }
296 void xf86SetMouseSpeed(int old, int new, unsigned cflag)
297 {
298 /*
299 * Set the speed of the mouse port. old is the previous speed,
300 * new is the new speed, and cflag is the value of the termio[s]
301 * c_cflag field. For mice that have programmable speed operation,
302 * this should send the appropriate commands to the mouse.
303 */
304 }
306 void xf86MouseInit(void)
307 {
308 /*
309 * This is called at the start of each server generation. In most
310 * cases this is a noop. If the mouse must not be opened/closed
311 * when VT switching, the open should be done here.
312 */
313 }
315 int xf86MousedOn(void)
316 {
317 /*
318 * Set the mouse up for use with X. This is called whenever
319 * the server becomes active (ie at the start of each generation and
320 * whenever its VT becomes active). This function normally opens
321 * the mouse device, and may call xf86SetupMouse() to initialise
322 * the mouse parameters. Return the file descriptor for mouse input.
323 * Return -1 if there is no file descriptor to add as an input
324 * device. If there are errors encountered, call FatalError().
325 * A return value of -1 is not considered an error condition.
326 */
327 }
329 int xf86MouseOff(Bool doclose)
330 {
331 /*
332 * Release the mouse from use with X. This is called at the end
333 * of a server generation (with doclose==TRUE), and also when the
334 * server's VT ceases being active (with doclose==FALSE). If the
335 * mouse should not be opened/closed when VT switching, the close
336 * should be done here when doclose==TRUE. For other systems, the
337 * mouse device should be closed regardless of the doclose value.
338 * Returns the mouse file descriptor. Returns -1 if there is no
339 * file descriptor to be removed as an input device. Errors
340 * should be handled the same way as in xf86MouseOn().
341 */
342 }
344 void xf86MouseEvents(void)
345 {
346 /*
347 * Read characters from the mouse device, and post the events
348 * by calling xf86PostMseEvent(). Read as much as is available
349 * without waiting. If the OS doesn't handle the mouse protocol
350 * translation, xf86MouseProtocol() may be called to do the
351 * translation and event posting. If the OS does handle the protocol
352 * translation, MOUSE_PROTOCOL_IN_KERNEL should be #define'd in
353 * xf86_OSlib.h.
354 */
355 }
357 int xf86OsMouseProc(DevicePtr pPointer, int what)
358 {
359 /*
360 * Implements the device-proc for the pointer device when an
361 * OS-based mouse driver is being used (as opposed to the
362 * server's internal mouse driver). Implemented as any other
363 * device-proc in the server.
364 *
365 * This function only needs to be implemented if USE_OSMOUSE is
366 * defined for the OS.
367 */
368 }
370 int xf86OsMouseEvents(void)
371 {
372 /*
373 * When supporting an OS-based mouse driver (as opposed to the
374 * server's internal mouse driver), read some events from the device
375 * and post them to the DIX layer through xf86PostMseEvent().
376 *
377 * This function only needs to be implemented if USE_OSMOUSE is
378 * defined for the OS.
379 */
380 }
382 void xf86OsMouseOption(int token, pointer lex_ptr)
383 {
384 /*
385 * Used in parsing an OsMouse keyword from the Xconfig file.
386 * Passed the token type and a pointer to the token value.
387 * The function should do whatever is appropriate for the OS's
388 * mouse driver.
389 *
390 * This function only needs to be implemented if USE_OSMOUSE is
391 * defined for the OS.
392 */
393 }
395 /*
396 * The following functions are simply wrappers around the OS specific
397 * libc functions
398 */
400 void *
401 xf86memmove(void * dest, const void * src, INT32 n)
402 {
403 return(memmove(dest,src,n));
404 }
406 void *
407 xf86memset(void * s, int c, INT32 n)
408 {
409 return(memset(s,c,n));
410 }
412 void *
413 xf86memcpy(void * dest, const void * src, INT32 n)
414 {
415 return(memcpy(dest,src,n));
416 }
418 int
419 xf86memcmp(const void * s1, const void * s2, INT32 n)
420 {
421 return(memcmp(s1,s2,n));
422 }
424 char *
425 xf86strcat(char * dest, const char * src)
426 {
427 return(strcat(dest,src));
428 }
430 char *
431 xf86strcpy(char * dest, const char * src)
432 {
433 return(strcpy(dest,src));
434 }
436 int
437 xf86strcmp(const char * s1, const char * s2)
438 {
439 return(strcmp(s1,s2));
440 }
442 int
443 xf86strncmp(const char * s1, const char * s2, INT32 n)
444 {
445 return(strncmp(s1,s2,n));
446 }
448 size_t
449 xf86strlen(const char * s)
450 {
451 return(strlen(s));
452 }
454 void
455 xf86getsecs(INT32 * secs, INT32 * usecs)
456 {
457 struct timeval tv;
459 gettimeofday(&tv, NULL);
460 *secs = tv.tv_sec;
461 *usecs= tv.tv_usec;
463 return;
464 }
466 double
467 xf86exp(double x)
468 {
469 return(exp(x));
470 }
472 double
473 xf86log(double x)
474 {
475 return(log(x));
476 }
478 double
479 xf86pow(double x, double y)
480 {
481 return(pow(x,y));
482 }
484 double
485 xf86sqrt(double x)
486 {
487 return(sqrt(x));
488 }
490 double
491 xf86cos(double x)
492 {
493 return(cos(x));
494 }
499 $XFree86: xc/programs/Xserver/hw/xfree86/os-support/README.OS-lib,v 3.10 2001/12/17 20:00:45 dawes Exp $
505 $XConsortium: README.OS-lib /main/5 1996/02/21 17:50:28 kaleb $