R6.6 is the Xorg base-lineXORG-MAIN

1 files changed, 437 insertions, 0 deletions

diff --git a/hw/xfree86/os-support/README.OS-lib b/hw/xfree86/os-support/README.OS-lib
new file mode 100644
index 000000000..cf3a0cc7e
--- /dev/null
+++ b/hw/xfree86/os-support/README.OS-lib
@@ -0,0 +1,437 @@
+
+			README for XFree86 OS-support Layer
+			-----------------------------------
+
+Contents
+--------
+    1) Overview
+    2) Directory Layout
+    3) Adding a new OS
+    4) OS Support API
+
+1 - Overview
+------------
+  This directory contains the OS support layer functions for the XFree86
+servers.  In addition, some miscellaneous server support functions (not
+OS-dependent) are included here, to take advantage of the fact that this
+library comes last in the linking order.
+
+Most of the functionality required to support a new OS is encapsulated in
+this library.  It is hoped that all OS-specific details can be encapsulated,
+but that is not likely ever to be completely possible.  Hence some minor
+changes will wind up being made in other parts of the server.  The major
+design principles for this library are maintainability, readability, and
+portability.  Sometimes these goals conflict; some somewhat arbitrary choices
+have been made in implementation.
+
+2 - Directory Layout
+--------------------
+	os-support/	Contains headers and documentation; no code
+		misc/	Non-OS-specific miscellaneous functions that
+			fit best into the link architecture this way.
+		shared/	Contains files with functions used by more than one
+			OS.  These are symlinked into the OS subdirectories
+			at build time via Imakefile rules.  This is alway
+			preferable to reproducing functions in more than one
+			OS library.
+		amoeba/	OS support for the Amoeba operating system.
+		bsd/	OS support for the 386BSD/NetBSD/FreeBSD operating 
+			systems.
+		bsdi/	OS support for the BSD/386 operating system.
+		linux/	OS support for the Linux operating system.
+		mach/	OS support for the Mach and OSF/1 operating systems.
+		minix/	OS support for the Minix operating system.
+		os2/	OS support for OS/2 2.11 and OS/2 Warp
+		sco/	OS support for the SCO SVR3.x operating system.
+		solx86/	OS support for the Solaris x86 operating system.
+		sysv/	OS support for all SVR4.0 and SVR4.2, and for
+			ISC and AT&T SVR3.2 operating systems.
+
+3 - Adding A New OS
+-------------------
+  Adding a support for a new operating system entails implementing all of
+the functions described in the API below.  Many of these functions are no-ops
+for many operating systems, and appropriate files with dummy declarations are
+available in the 'shared' subdirectory.
+
+If your OS is sufficiently similar to an existing OS, you can make use of
+the existing subdirectory.  One of the reasons for implementing this OS
+library was the unmaintainability of the spagetti-#ifdef code that existed
+before.  You should try to avoid cluttering the code with #ifdef's.  If
+you find that the subdirectory is getting cluttered, split off into a
+seperate subdirectory (e.g. as was done for SCO, rather than cluttering
+the 'sysv' subdirectory).  You can split functions out of an existing
+subdirectory into the 'shared' subdirectory, if that is appropriate.  Just
+remember to update the Imakefile for the old subdirectory.
+
+You will still likely have to make some small changes to other parts of
+the server.  You should not put OS-specific #define's or #include's anywhere
+else in the server.  These should all go in the "xf86_OSlib.h" header file
+in this directory.
+
+4 - OS Support API
+-----------------
+void xf86OpenConsole(void)
+{
+	/*
+	 * Open console device, activate VTs, etc, etc.  Fill in requisite
+	 * pieces of x386Info.  Most of this code comes from x386Init.c
+	 */
+}
+
+void xf86CloseConsole(void)
+{
+	/*
+	 * Close console at server exit.
+	 */
+}
+
+Bool xf86VTSwitchPending(void)
+{
+	 /*
+	  * Returns TRUE iff there is a VT switch operation pending for
+	  * the server.  In the USL VT model, this is indicated via a
+	  * signal handler.  Should return FALSE always for OSs without
+	  * VTs.
+	  */
+}
+
+Bool xf86VTSwitchAway(void)
+{
+	/*
+	 * Handles the OS-specific action for switching away from the active
+	 * VT.  Returns FALSE if the switch away fails.  Should return
+	 * FALSE always for OSs without VTs (then again, this function
+	 * should never be called in that case).
+	 */
+}
+
+Bool xf86VTSwitchTo(void)
+{
+	/*
+	 * Handles the OS-specific action for switching to the active VT.
+	 * Returns FALSE if the switch to fails.  Should return TRUE
+	 * always for OSs without VTs (then again, this function should
+	 * never be called in that case).
+	 */
+}
+
+Bool xf86LinearVidMem(void)
+{
+	/*
+	 * Returns TRUE if the OS supports mapping linear frame buffers
+	 * (ie memory at addresses above physical memory).
+	 */
+}
+
+pointer xf86MapVidMem(int ScreenNum, int Region, pointer Base,
+		      unsigned long Size)
+{
+	/*
+	 * Handle mapping the video memory.  Returns (pointer *)0 for
+	 * failure; causes server exit.  It is allowable to call FatalError()
+	 * from inside this function and exit directly.
+	 */
+}
+
+void xf86UnMapVidMem(int ScreenNum, int Region, pointer Base,
+		     unsigned long Size)
+{
+	/*
+	 * Handle unmapping the video memory.  This should undo what
+	 * xf86MapVidMem() does.  Base is a pointer obtained from
+	 * a previous call to xf86MapVidMem().
+	 */
+}
+
+void xf86MapDisplay(int ScreenNum, int Region)
+{
+	/*
+	 * For OSs that require the screen be mapped when entering a VT.
+	 * A dummy function will be defined for OSs that don't require
+	 * this (or don't have VTs at all).
+	 */
+}
+
+void xf86UnMapDisplay(int ScreenNum, int Region)
+{
+	/*
+	 * For Os that require that the screen be unmapped when leaving a
+	 * VT.  A dummy function will be defined for OSs that don't require
+	 * this (or don't have VTs at all).
+	 */
+}
+
+int xf86ReadBIOS(unsigned long Base, unsigned long Offset, 
+		  unsigned char *Buf, int Len)
+{
+	/*
+	 * Read Len bytes from the BIOS at address Base, offset Offset,
+	 * into buffer Buf.  Returns -1 for failure or if the OS does 
+	 * not support reading the BIOS.  This causes a driver probe 
+	 * to fail, but does not cause the server to abort.
+	 */
+}
+
+void xf86ClearIOPortList(int ScreenNum)
+{
+	/*
+	 * Clears any list of I/O ports that the OS-layer may be maintaining.
+	 * Note: the value used for ScreenNum must be the scrnIndex field
+	 * of the screenInfoRec, because this is the only index that is
+	 * guaranteed to be valid and never change during the life of the
+	 * server.  It is not the same as the index of pScreen in ScreenInfo.
+	 */
+}
+
+void xf86AddIOPorts(int ScreenNum, int NumPorts, unsigned *Ports)
+{
+        /*
+	 * Adds NumPorts I/O ports listed in array Ports to a list that
+	 * the OS-layer may be maintaining.  Successive calls to this
+	 * function are cumulative.
+	 */
+}
+
+void xf86EnableIOPorts(int ScreenNum)
+{
+        /*
+	 * Enables I/O permissions.  The OS layer can either use a 
+	 * previously created list of I/O ports to be used, or can 
+	 * enable all I/O port access.
+	 */
+}
+
+void xf86DisableIOPorts(int ScreenNum)
+{
+        /*
+	 * Disables I/O permissions.  Does not clear the list of I/O 
+	 * ports, if any exists.
+	 */
+}
+
+void xf86DisableIOPrivs(void)
+{
+        /*
+	 * Do whatever is necessary to disable I/O permissions after forking
+	 * a child process.
+	 */
+}
+
+Bool xf86DisableInterrupts(void)
+{
+	/*
+	 * Disable interrupts if allowed for this OS.  Returns FALSE if
+	 * this is not allowed or if the attempt fails for some reason.
+	 */
+}
+
+void xf86EnableInterrupts(void)
+{
+	/*
+	 * Reenable interrupts
+	 */
+}
+
+int xf86ProcessArgument(int argc, char *argv[], int i)
+{
+	/*
+	 * Process OS-specific command-line arguments.  See 
+	 * ddxProcessArgument() for more info.
+	 */
+}
+
+void xf86UseMsg(void)
+{
+	/*
+	 * Print list of OS-specific command-line arguments.  See 
+	 * ddxUseMsg() for more info.
+	 */
+}
+
+void xf86SoundKbdBell(int loudness, int pitch, int duration)
+{
+	/*
+	 * Sound the keyboard bell.  pitch is in Hz, duration in ms,
+	 * loudness is in the range 0-100 (0 -> off).  For systems
+	 * where the loudness can't be controlled, scale the duration
+	 * by loudness/50.
+	 */
+}
+
+void xf86SetKbdLeds(int leds)
+{
+	/*
+	 * Set the keyboard LEDs to the state indicated in leds
+	 */
+}
+
+int xf86GetKbdLeds(void)
+{
+	/*
+	 * Return the state of the keyboard LEDs.  If the OS doesn't
+	 * support this, return 0.
+	 */
+}
+
+void xf86SetKbdRepeat(char rad)
+{
+	/*
+	 * Set the keyboard repeat rate and delay according the
+	 * the rad value.  The lower 5 bits determine the repeat
+	 * rate (lower value -> higher rate).  The next 2 bits
+	 * determine the delay.
+	 * This should possibly be changed to take separate rate and
+	 * delay parameters.
+	 */
+}
+
+void xf86KbdInit(void)
+{
+	/*
+	 * Save initial keyboard state.  This is called at the start of
+	 * each server generation.
+	 */
+}
+
+int xf86KbdOn(void)
+{
+	/*
+	 * Set the keyboard up for use with X.  This is called whenever
+	 * the server becomes active (ie at the start of each generation and
+	 * whenever its VT becomes active).  Return the file descriptor
+	 * for keyboard input.  Return -1 if there is no file descriptor
+	 * to add as an input device.  If there are errors encountered,
+	 * call FatalError().  A return value of -1 is not considered an
+	 * error condition.
+	 */
+}
+
+int xf86KbdOff(void)
+{
+	/*
+	 * Return the keyboard to the state saved by xf86KbdInit().  This is
+	 * called at the end of a server generation, and also when the
+	 * server's VT ceases being active.  Returns the keyboard file
+	 * descriptor.  Returns -1 if there is no file descriptor to be
+	 * removed as an input device.  Errors should be handled the same
+	 * way as in xf86KbdOn().
+	 */
+}
+
+void xf86KbdEvents(void)
+{
+	/*
+	 * Read characters from the keyboard device, and post the events
+	 * by calling x386PostKbdEvent().  Read as much as is available
+	 * without waiting.
+	 */
+}
+
+void xf86SetMouseSpeed(int old, int new, unsigned cflag)
+{
+	/*
+	 * Set the speed of the mouse port.  old is the previous speed,
+	 * new is the new speed, and cflag is the value of the termio[s]
+	 * c_cflag field.  For mice that have programmable speed operation,
+	 * this should send the appropriate commands to the mouse.
+	 */
+}
+
+void xf86MouseInit(void)
+{
+	/*
+	 * This is called at the start of each server generation.  In most
+	 * cases this is a noop.  If the mouse must not be opened/closed
+	 * when VT switching, the open should be done here.
+	 */
+}
+
+int xf86MousedOn(void)
+{
+	/*
+	 * Set the mouse up for use with X.  This is called whenever
+	 * the server becomes active (ie at the start of each generation and
+	 * whenever its VT becomes active).  This function normally opens
+	 * the mouse device, and may call xf86SetupMouse() to initialise
+	 * the mouse parameters.  Return the file descriptor for mouse input.
+	 * Return -1 if there is no file descriptor to add as an input
+	 * device.  If there are errors encountered, call FatalError().
+	 * A return value of -1 is not considered an error condition.
+	 */
+}
+
+int xf86MouseOff(Bool doclose)
+{
+	/*
+	 * Release the mouse from use with X.  This is called at the end
+	 * of a server generation (with doclose==TRUE), and also when the
+	 * server's VT ceases being active (with doclose==FALSE).  If the
+	 * mouse should not be opened/closed when VT switching, the close
+	 * should be done here when doclose==TRUE.  For other systems, the
+	 * mouse device should be closed regardless of the doclose value.
+	 * Returns the mouse file descriptor.  Returns -1 if there is no
+	 * file descriptor to be removed as an input device.  Errors
+	 * should be handled the same way as in xf86MouseOn().
+	 */
+}
+
+void xf86MouseEvents(void)
+{
+	/*
+	 * Read characters from the mouse device, and post the events
+	 * by calling x386PostMseEvent().  Read as much as is available
+	 * without waiting.  If the OS doesn't handle the mouse protocol
+	 * translation, xf86MouseProtocol() may be called to do the
+	 * translation and event posting.  If the OS does handle the protocol
+	 * translation, MOUSE_PROTOCOL_IN_KERNEL should be #define'd in
+	 * xf86_OSlib.h.
+	 */
+}
+
+int xf86OsMouseProc(DevicePtr pPointer, int what)
+{
+	/*
+	 * Implements the device-proc for the pointer device when an
+	 * OS-based mouse driver is being used (as opposed to the
+	 * server's internal mouse driver).  Implemented as any other
+	 * device-proc in the server.
+	 *
+	 * This function only needs to be implemented if USE_OSMOUSE is
+	 * defined for the OS.
+	 */
+}
+
+int xf86OsMouseEvents(void)
+{
+	/*
+	 * When supporting an OS-based mouse driver (as opposed to the
+	 * server's internal mouse driver), read some events from the device
+	 * and post them to the DIX layer through x386PostMseEvent().
+	 *
+	 * This function only needs to be implemented if USE_OSMOUSE is
+	 * defined for the OS.
+	 */
+}
+
+void xf86OsMouseOption(int token, pointer lex_ptr)
+{
+	/*
+	 * Used in parsing an OsMouse keyword from the Xconfig file.
+	 * Passed the token type and a pointer to the token value.
+	 * The function should do whatever is appropriate for the OS's
+	 * mouse driver.
+	 *
+	 * This function only needs to be implemented if USE_OSMOUSE is
+	 * defined for the OS.
+	 */
+}
+
+
+$XFree86: xc/programs/Xserver/hw/xfree86/os-support/README.OS-lib,v 3.2 1996/12/23 06:48:59 dawes Exp $
+
+
+
+
+
+$Xorg: README.OS-lib,v 1.3 2000/08/17 19:51:19 cpqbld Exp $