path: root/hw/xfree86/os-support/README.OS-lib

			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 $