
This README file describes the design and idea behind the loadable module
code for XFree86. This code is based of code that was developed by Metro Link 
and donated to The XFree86 Project.

<at this point we should include the design document as written by Stuart>

Debugging this code is somewhat dificult as gdb will not be able to step
through loaded modules in source mode. The functions

LoaderPrintSymbol( address )
LoaderPrintAddress( symbol )

are provided to allow easy orientation in the loaded module. Most problems
stem from global functions and variables that are not exported from other
modules or the main server executable, but are referenced in a module.
All global variables should be put in ScreenPrivates or other container
objects, that are driver specific. This will solve the biggest problem
cleanly and at the same time provide an important step towards multi headed
servers.

More documentation on the design and implementation should be added here.

Specific comments to some design ideas and the state of the code

- Init Function

every module has its init function, which has the name ModuleInit.
When loading the module this function is repeatedly called with two pointers
(one to a magic value, one to a data element) until it returns a magic value
indicating that it is done. Currently the magic values support several
actions:

magic				data points to

MAGIC_ADD_VIDEO_CHIP_REC	the videoChipRec to be added to the list
				of drivers

MAGIC_LOAD			the name of the module to load

MAGIC_CCD_DO_BITBLT		the do_bitblt function for the current
				color depth

MAGIC_CCD_SCREEN_PRIV_IDX	the ScreenPrivIdx for the current color depth

MAGIC_CCD_XAA_SCREEN_INIT	the XaaScreenInit function for the current
				color depth

MAGIC_PEX_INIT			
MAGIC_XIE_INIT			init functions of extensions

MAGIC_DONT_CHECK_UNRESOLVED	checking for unresolved symbols will be delayed
				for one step until LoaderCheckUnresolved()
				is called with LD_RESOLV_NOW the same number of 
				times than MAGIC_DONT_CHECK_UNRESOLVED
				has been passed before.

MAGIC_DONE			nothing; side effect is to stop looping

- mixed color depths

the current code has various cross dependencies on cfb8, libvga256, and all
higher depths cfbs as well as all the xaa modules. These need to be
straightened out (this has been started but is far from done).
We basically need a redesigned server to solve these issues cleanly.

- unresolved functions

the current code has one 'minor' flaw. When checking unresolved symbols
we reference quite a few things from the cfb libraries that we did not
pull in. Since these functions are never called, this doesn't really
matter, but it is uggly, obviously.

Changing all this to use function pointers and initializing all of
them sounds like the clean solution, but I'm wondering if it wasn't
better to define a default function that is bound to all unresolved
symbols and prints out that there was a problem with resolving symbols
and makes the server exit gracefully. This would be a reasonable
default behaviour and would allow to keep dangling references to
functions that are known not to be called.

This "elegant hack" has been implemented for the Elf loader, but better
solutions are welcome.

- OS support

Currently this has been tested on Linux, it should work on SVR4. This
code needs to be ported to the other operating systems XFree86 supports.

- finding modules

ModulePath can contain several entries of directories that contain modules.
Modules can be implicitly or explicitly loaded. To load a module explicitly
you have to include it in the Module Section. Load "name" tries to find
name, name.o, name_drv.o, or name.a in any of the directories given in the 
ModulePath or in the subdirectories drivers, extensions, internal under these 
directories. Normally the chipset drivers should be implemented in a way that 
they implicitly load all other core modules needed by this driver.

----------------------------------------------------------------------

Last updated Feb 25, 1997, Dirk H. Hohndel <hohndel@XFree86.Org>




$XFree86: xc/programs/Xserver/hw/xfree86/loader/README,v 1.4 1997/04/08 14:54:33 hohndel Exp $
