loader: Fix and enhance README.md.
Several adjustments were made, including:
1) Add some MS Windows-related information. For example, the loader is
"XGL.dll" on Windows, and "libSGL.so" on Linux. Also, the separator
character is given, for each OS, for the PATH environment variables.
2) Add some addition information about dispatching.
3) Add example code for setting the magic value in the ICD.
4) Fix the numbering that looked fine in the "mardown" website, but not on
GitHub.
5) Try to improve grammar, punctuation, etc.
diff --git a/loader/README.md b/loader/README.md
index f197167..b88d98b 100644
--- a/loader/README.md
+++ b/loader/README.md
@@ -1,26 +1,35 @@
# Loader Description
## Overview
-The Loader implements the main XGL library: libXGL.so on Linux. It handles
-layer management and driver management. Loader driver management includes
-finding driver librairies and loading them. Additionally, the loader dispatches
-the API calls to the correct driver based on the GPU selected by the app. The
-loader fully supports multi-gpu operation.
+The Loader implements the main XGL library (e.g. "XGL.dll" on Windows and
+"libXGL.so" on Linux). It handles layer management and driver management. The
+loader fully supports multi-gpu operation. As part of this, it dispatches API
+calls to the correct driver, and to the correct layers, based on the GPU object
+selected by the application.
-Loader layer management includes finding layer libraries and activating them
-as requested. Loader correctly sets up layer and its own dispatch tables to
-support multiple layers activated. Each active layer can intercept a subset of
-the full API entrypoints. A layer which doesn't intercept a given entrypoint
-will be skipped for that entrypoint. The loader supports layers that operate
-on multiple GPUs.
+The loader's driver management includes finding driver libraries and loading
+them. When a driver is initialized, the loader sets up its dispatch tables,
+using a very light-weight "trampoline" mechanism. To do so, it reserves space
+for a pointer in API objects (see below for more information about this).
+
+The loader's layer management includes finding layer libraries and activating
+them as requested. The loader correctly sets up each activated layer, and its
+own dispatch tables in order to support all activated layers. Each active
+layer can intercept a subset of the full API entrypoints. A layer which
+doesn't intercept a given entrypoint will be skipped for that entrypoint. The
+loader supports layers that operate on multiple GPUs.
## Environment Variables
-LIBXGL\_DRIVERS\_PATH directory for loader to search for ICD driver libraries to open
+**LIBXGL\_DRIVERS\_PATH** directory for loader to search for ICD driver libraries to open
-LIBXGL\_LAYERS\_PATH directory for loader to search for layer libraries that may get activated and used at xglCreateDevice() time.
+**LIBXGL\_LAYERS\_PATH** directory for loader to search for layer libraries that may get activated and used at xglCreateDevice() time.
-LIBXGL\_LAYER\_NAMES colon separate list of layer names to be activated. Example,
- LIBXGL\_LAYER\_NAMES=MemTracker:DrawState
+**LIBXGL\_LAYER\_NAMES** colon-separated list of layer names to be activated (e.g., LIBXGL\_LAYER\_NAMES=MemTracker:DrawState).
+
+Note: Both of the LIBXGL\_*\_PATH variables may contain more than one directory. Each directory must be separated by one of the following characters, depending on your OS:
+
+- ";" on Windows
+- ":" on Linux
## Interface to driver (ICD)
- xglEnumerateGpus exported
@@ -30,19 +39,34 @@
- all objects created by ICD can be cast to (XGL\_LAYER\_DISPATCH\_TABLE \*\*)
where the loader will replace the first entry with a pointer to the dispatch table which is
owned by the loader. This implies three things for ICD drivers:
- 1. the ICD must return a pointer for the opaque object handle
- 2. this pointer points to a regular C structure with the first entry being a pointer.
+ 1. The ICD must return a pointer for the opaque object handle
+ 2. This pointer points to a regular C structure with the first entry being a pointer.
Note: for any C++ ICD's that implement XGL objects directly as C++ classes.
- The C++ compiler may put a vtable at offset zero if your class is virtual.
- In this case use a regular C structure as follows for your C++ objects:
+ The C++ compiler may put a vtable at offset zero, if your class is virtual.
+ In this case use a regular C structure (see below).
+ 3. The reservedForLoader.loaderMagic member must be initialized with ICD\_LOADER\_MAGIC, as follows:
+
```
#include "xglIcd.h"
+
struct {
- XGL_LOADER_DATA *reservedForLoader;
- myObjectClass myObj;
+ XGL_LOADER_DATA *reservedForLoader; // Reserve space for pointer to loader's dispatch table
+ myObjectClass myObj; // Your driver's C++ class
} xglObj;
+
+ xglObj alloc_icd_obj()
+ {
+ xglObj *newObj = alloc_obj();
+ ...
+ // Initialize pointer to loader's dispatch table with ICD_LOADER_MAGIC
+ set_loader_magic_value(newObj);
+ ...
+ return newObj;
+ }
```
- 3. the reservedForLoader.loaderMagic member must be initialized with ICD\_LOADER\_MAGIC
-- the ICD may or may not implement a dispatch table
-- ICD entrypoints can be named anything including the offcial xgl name such as xglCreateDevice(). However, beware of interposing by dynamic OS library loaders if the offical names are used. On Linux, if offical names are used, the ICD library must be linked with -Bsymbolic
+
+Additional Notes:
+
+- The ICD may or may not implement a dispatch table.
+- ICD entrypoints can be named anything including the offcial xgl name such as xglCreateDevice(). However, beware of interposing by dynamic OS library loaders if the offical names are used. On Linux, if offical names are used, the ICD library must be linked with -Bsymbolic.