Make layer activation via CreateDevice struct or env variable

Also finish making all activated layers per icd and per gpu.

1 files changed, 51 insertions, 0 deletions

diff --git a/layers/README.md b/layers/README.md
new file mode 100644
index 00000000..135c69ee
--- /dev/null
+++ b/layers/README.md
@@ -0,0 +1,51 @@
+Layer Description and Status
+10/22/2014
+
+Overview:
+Layer libraries can be written to intercept or hook XGL entrypoints for various
+debug and validation purpose.  One or more XGL entrypoints can be defined in your Layer
+library.  Undefined entrypoints in the Layer library will be passed to the next Layer which
+may be the driver.  Multiple layer libraries can be chained (actually a hierarchy) together.
+xglEnumerateLayer can be called to list the available layer libraries.  xglGetProcAddr i
+used internally by the Layers and ICD Loader to initialize dispatch tables. Layers are
+activated at xglCreateDevice time. xglCreateDevice createInfo struct is extended to allow
+a list of layers to be activated.  Layer libraries can alternatively be LD_PRELOADed.
+
+Layer library example code:
+layer/basic_plugin.c  - simple example
+<build dir>/layer/generic_layer.c  - auto generated example wrapping all XGL entrypoints
+
+Using Layers::
+Build XGL loader  and i965 icd driver using normal steps (cmake and make)
+Place libXGLLayer<name>.so in the same directory as your XGL test or app:
+  cp build/layer/libXGLLayerBasic.so build/tests
+
+Specify which Layers to activate by using xglCreateDevice XGL_LAYER_CREATE_INFO struct or
+environment variable LIBXGL_LAYERS_LIB
+   export LIBXGL_LAYERS_LIB=libXGLLayerBasic.so
+   cd build/tests; ./xglinfo
+
+
+Status:
+Current Features:
+-scanning of available Layers during xglInitAndEnumerateGpus
+-xglEnumerateLayers and xglGetProcAddr supported APIs in xgl.h, ICD loader and i965 driver
+-multiple layers in a hierarchy supported
+-layer enumeration works
+-layers  activated per gpu and per icd driver: separate  dispatch table and layer library
+   list in loader for each gpu or icd driver
+-activation via xglCreateDevice extension struct in CreateInfo or via env var
+   (LIBXGL_LAYER_LIBS)
+-layer libraries can be LD_PRELOADed
+
+Current known issues:
+-memory leak of gpu wrapped objects
+-layer libraries don't support multiple dispatch tables for multi-gpus
+-layers  with extension APIs  not yet tested or supported
+-layer libraries not yet include loader init functionality for full  LD_PRELOAD of
+    entire API including xglInitAndEnumerate
+-no support for apps registering layers, must be discovered via initial scan
+-no support for Loader discovering from layer and driver which layers support which
+  gpus/drivers: any layer can be use any gpu right now
+-xglEnumerateLayers doesn't qualify Layers based on gpu, but enumerates all that were scanned
+