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.
bsd/ OS support for the NetBSD/FreeBSD/OpenBSD operating
systems.
linux/ OS support for the Linux operating system.
sco/ OS support for the SCO SVR3.x operating system.
solaris/ OS support for the Solaris 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 xf86Info. Most of this code comes from xf86Init.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, 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, 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 xf86EnableIOPorts(int ScreenNum)
{
/*
* Enables I/O permissions. The OS layer should
* enable all I/O port access.
*/
}
void xf86DisableIOPorts(int ScreenNum)
{
/*
* Disables I/O permissions.
*/
}
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.
*/
}
$XFree86: xc/programs/Xserver/hw/xfree86/os-support/README.OS-lib,v 3.10 2001/12/17 20:00:45 dawes Exp $
$XConsortium: README.OS-lib /main/5 1996/02/21 17:50:28 kaleb $
