GLX Symbol Mechanism
--------------------

Utah glx has been enhanced to allow multiple drivers to be compiled
into a single glx.so.  

Utah drivers rely on information in the relevent X server and 2d
driver for card configuration and other information.  When running in
direct mode, these server symbols will not be present in the client.
Previously dummy symbols were added to libGL.so to allow the dangling
dependencies to be resolved - this was quite inelegant, and meant that
libGL.so was tied to a particular piece of hardware - though no
functional piece of that library is actually hardware dependent.

Utah contains drivers that rely on different X servers, and even a
particular X server may not be compiled with all the relevent 2d
drivers.  

To resolve these issues, Utah drivers now reference all server symbols
via the glxsym struct, which is populated with pointers to all the
relevent server objects.  This is possible under Linux (and other
os's) because dlopen allows a process to 'open' its own executable
image as a library, and to issue dlsym queries on that image.  Thus we
can query at runtime what symbols are available, and disable drivers
which require non-existant symbols.  

In the case of direct mode, we don't query for server symbols, as we
know they won't be there.  

The upshots of this for driver writers are:

	- Each driver must supply a function which searches for every
symbol required by that driver.  This is to be called in glxmesa.c in
the code which decides which driver to activate.  If any of the
symbols is not present, the driver cannot be loaded.
	
	These driver-specific symbols should be added to the glxsym
struct in common/glx_symbols.h.  (These could be moved into local,
per-driver structs)

	Utah supplies a number of helper functions which check all the
commonly used symbols specific to a given XFree server,
glxHookSVGAServerSymbols() being the most widely used.  The driver
must call this from its own HookSymbols function to complete the task.

	- When referencing any of the driver-specific symbols, they
must be referenced indirectly via the glxsym struct.  There is a
convenience macro GLXSYM() to simplify this.  Simply wrap any server
symbol references with that macro.


Verifying GLXSYM usage
======================

It is very important to verify that your new code doesn't break the
symbol mechanism - a single unwrapped reference will break direct
rendering for all drivers.

To check this, compile glx.so, and issue the following command:

	 nm glx.so | grep " U " | grep -v GLIBC


These are the results on my current build:

         U dlclose
         U dlerror
         U dlopen
         U dlsym

Specifically check that you haven't added any X server or driver
references to this list.


Keith Whitwell
March 2000



