#Layer Description and Status 27 Nov 2014
##Overview
Layer libraries can be written to intercept or hook XGL entrypoints for various debug and validation purposes. 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 is 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 depending upon how they are implemented.
Note that some layers are code-generated and will therefore exist in the include/xglLayer.h - header file for layer code layer/Basic.cpp (name=Basic) simple example wrapping a few entrypoints. Shows layer features: - Multiple dispatch tables for supporting multiple GPUs. - Example layer extension function shown. - Layer extension advertised by xglGetExtension(). - xglEnumerateLayers() supports loader layer name queries and call interception - Can be LD_PRELOADed individually layer/Multi.cpp (name=multi1:multi2) simple example showing multiple layers per library /layer/generic_layer.c (name=Generic) - auto generated example wrapping all XGL entrypoints. Single global dispatch table. Can be LD_PRELOADed. /layer/api_dump.c - print out API calls along with parameter values /layer/api_dump_file.c - Write API calls along with parameter values to xgl_apidump.txt file. /layer/api_dump_no_addr.c - print out API calls along with parameter values but replace any variable addresses with the static string "addr". /layer/object_track.c - Print object CREATE/USE/DESTROY stats. Individually track objects by category. XGL_OBJECT_TYPE enum defined in object_track.h. If a Dbg callback function is registered, this layer will use callback function(s) for reporting, otherwise uses stdout. Provides custom interface to query number of live objects of given type "XGL_UINT64 objTrackGetObjectCount(XGL_OBJECT_TYPE type)" and a secondary call to return an array of those objects "XGL_RESULT objTrackGetObjects(XGL_OBJECT_TYPE type, XGL_UINT64 objCount, OBJTRACK_NODE* pObjNodeArray)". layer/draw_state.c - Report the Descriptor Set, Pipeline State, and dynamic state at each Draw call. If a Dbg callback function is registered, this layer will use callback function(s) for reporting, otherwise uses stdout. layer/mem_tracker.c - Track GPU Memory and any binding it has to objects and/or Cmd Buffers. Report issues with freeing memory, memory dependencies on Cmd Buffers, and any memory leaks at DestroyDevice time. If a Dbg callback function is registered, this layer will use callback function(s) for reporting, otherwise uses stdout.
-scanning of available Layers during xglInitAndEnumerateGpus; -layer names retrieved via xglEnumerateLayers(); -xglEnumerateLayers and xglGetProcAddr supported APIs in xgl.h, ICD loader and i965 driver; -multiple layers in a hierarchy supported; -layer enumeration supported per GPU; -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_NAMES); -layer libraries can be LD_PRELOADed if implemented correctly;
-layer libraries (except Basic) don't support multiple dispatch tables for multi-gpus; -layer libraries not yet include loader init functionality for full LD_PRELOAD of entire API including xglInitAndEnumerateGpus; -Since Layers aren't activated until xglCreateDevice, any calls to xglGetExtension() will not report layer extensions unless implemented in the layer; -layer extensions do NOT need to be enabled in xglCreateDevice to be available; -no support for apps registering layers, must be discovered via initial scan