Deinitialization support.

Co-authored-by: Ben Ashbaugh <ben.ashbaugh@intel.com>

Author: Kerilk

CMakeLists.txt

@@ -161,7 +161,7 @@ set (OPENCL_COMPILE_DEFINITIONS
     CL_NO_NON_ICD_DISPATCH_EXTENSION_PROTOTYPES
     OPENCL_ICD_LOADER_VERSION_MAJOR=3
     OPENCL_ICD_LOADER_VERSION_MINOR=0
-    OPENCL_ICD_LOADER_VERSION_REV=7
+    OPENCL_ICD_LOADER_VERSION_REV=8
     $<$<BOOL:${ENABLE_OPENCL_LAYERS}>:CL_ENABLE_LAYERS>
     $<$<BOOL:${ENABLE_OPENCL_LOADER_MANAGED_DISPATCH}>:CL_ENABLE_LOADER_MANAGED_DISPATCH>
 )

README.md

@@ -145,3 +145,5 @@ The following debug environment variables are available for use with the OpenCL
 | OPENCL_LAYERS                     | Specifies a list of layers to load. |  `export OPENCL_LAYERS=libLayerA.so:libLayerB.so`<br/><br/>`set OPENCL_LAYERS=libLayerA.dll;libLayerB.dll` |
 | OPENCL_LAYER_PATH                 | On Linux and Android, specifies a directory to scan for layers to enumerate in place of the default `/etc/OpenCL/layers'. | `export OPENCL_LAYER_PATH=/my/local/layers/search/path` |
 | OCL_ICD_ENABLE_TRACE              | Enable the trace mechanism          |  `export OCL_ICD_ENABLE_TRACE=True`<br/><br/>`set OCL_ICD_ENABLE_TRACE=True`<br/>`true, T, 1 can also be used here.`  |
+| OCL_ICD_FORCE_LEGACY_TERMINATION  | Forces using the legacy termination scheme. Legacy termination supports older layers, but does not support layer de-initialization and does not close library handles for layers or ICDs.  |  `export OCL_ICD_FORCE_LEGACY_TERMINATION=True`<br/><br/>`set OCL_ICD_FORCE_LEGACY_TERMINATION=True`<br/>`true, T, 1 can also be used here.`  |
+| OCL_ICD_DISABLE_DYNAMIC_LIBRARY_UNLOADING | Prevents the ICD loader from closing dynamic library handles for layers and ICDs.  This can be used for debugging purposes or to allow leak sanitizers to have full stack traces. |  `export OCL_ICD_DISABLE_DYNAMIC_LIBRARY_UNLOADING=True`<br/><br/>`set OCL_ICD_DISABLE_DYNAMIC_LIBRARY_UNLOADING=True`<br/>`true, T, 1 can also be used here.`  |

include/cl_khr_icd2.h

@@ -18,6 +18,31 @@
 
 #include <CL/cl.h>
 
+#if !defined(CL_PLATFORM_UNLOADABLE_KHR)
+#define CL_PLATFORM_UNLOADABLE_KHR 0x0921
+#endif
+
+#if defined(CL_ENABLE_LAYERS) && !defined(CL_LAYER_PROPERTIES_LIST_END)
+typedef cl_properties cl_layer_properties;
+
+#define CL_LAYER_PROPERTIES_LIST_END         ((cl_layer_properties)0)
+
+typedef cl_int CL_API_CALL
+clInitLayerWithProperties_t(
+    cl_uint num_entries,
+    const cl_icd_dispatch *target_dispatch,
+    cl_uint *num_entries_ret,
+    const cl_icd_dispatch **layer_dispatch_ret,
+    const cl_layer_properties *properties);
+
+typedef clInitLayerWithProperties_t *pfn_clInitLayerWithProperties;
+
+typedef cl_int CL_API_CALL
+clDeinitLayer_t(void);
+
+typedef clDeinitLayer_t *pfn_clDeinitLayer;
+#endif //defined(CL_ENABLE_LAYERS) && !defined(CL_LAYER_PROPERTIES_LIST_END)
+
 #if !defined(CL_ICD2_TAG_KHR)
 #if INTPTR_MAX == INT32_MAX
 #define CL_ICD2_TAG_KHR ((intptr_t)0x434C3331)

loader/cllayerinfo.c

@@ -19,7 +19,6 @@
 #include "icd.h"
 #include <stdio.h>
 #include <stdlib.h>
-#include <CL/cl_layer.h>
 #if defined(_WIN32)
 #include <io.h>
 #include <share.h>
@@ -90,7 +89,7 @@ static void restore_outputs(void)
 void printLayerInfo(const struct KHRLayer *layer)
 {
     cl_layer_api_version api_version = 0;
-    pfn_clGetLayerInfo p_clGetLayerInfo = (pfn_clGetLayerInfo)(size_t)layer->p_clGetLayerInfo;
+    pfn_clGetLayerInfo p_clGetLayerInfo = layer->p_clGetLayerInfo;
     cl_int result = CL_SUCCESS;
     size_t sz;
 
@@ -113,20 +112,26 @@ void printLayerInfo(const struct KHRLayer *layer)
     }
 }
 
-int main (int argc, char *argv[])
+static void run_silently(void (*pfn)(void))
 {
-    (void)argc;
-    (void)argv;
     silence_layers();
     atexit(restore_outputs);
-    khrIcdInitialize();
+    pfn();
     restore_outputs();
     atexit(silence_layers);
+}
+
+int main (int argc, char *argv[])
+{
+    (void)argc;
+    (void)argv;
+    run_silently(&khrIcdInitialize);
     const struct KHRLayer *layer = khrFirstLayer;
     while (layer)
     {
         printLayerInfo(layer);
         layer = layer->next;
     }
+    run_silently(&khrIcdDeinitialize);
     return 0;
 }

loader/icd.c

@@ -19,32 +19,48 @@
 #include "icd.h"
 #include "icd_dispatch.h"
 #include "icd_envvars.h"
-#if defined(CL_ENABLE_LAYERS)
-#include <CL/cl_layer.h>
-#endif // defined(CL_ENABLE_LAYERS)
 #include <stdlib.h>
 #include <string.h>
 
 KHRicdVendor *khrIcdVendors = NULL;
+static KHRicdVendor *lastVendor = NULL;
 int khrEnableTrace = 0;
+static int khrDisableLibraryUnloading = 0;
+static int khrForceLegacyTermination = 0;
 
 #if defined(CL_ENABLE_LAYERS)
 struct KHRLayer *khrFirstLayer = NULL;
 #endif // defined(CL_ENABLE_LAYERS)
 
-// entrypoint to check and initialize trace.
-void khrIcdInitializeTrace(void)
+static inline int khrIcdCheckEnvTrue(const char *variable)
+{
+    return (variable && (strcmp(variable, "True") == 0 ||
+                strcmp(variable, "true") == 0 ||
+                strcmp(variable, "T") == 0 ||
+                strcmp(variable, "1") == 0));
+}
+
+// Set a given flag if the given environement variable is true
+static void khrInitializeFlagWithEnv(int *flag, const char *variable)
 {
-    char *enableTrace = khrIcd_getenv("OCL_ICD_ENABLE_TRACE");
-    if (enableTrace && (strcmp(enableTrace, "True") == 0 ||
-            strcmp(enableTrace, "true") == 0 ||
-            strcmp(enableTrace, "T") == 0 ||
-            strcmp(enableTrace, "1") == 0))
+    char *variableStr = khrIcd_getenv(variable);
+    if (khrIcdCheckEnvTrue(variableStr))
+    {
+        *flag = 1;
+    }
+    if (variableStr)
     {
-        khrEnableTrace = 1;
+        khrIcd_free_getenv(variableStr);
     }
 }
 
+void khrIcdInitializeEnvOptions(void)
+{
+    khrInitializeFlagWithEnv(&khrEnableTrace, "OCL_ICD_ENABLE_TRACE");
+    khrInitializeFlagWithEnv(&khrDisableLibraryUnloading, "OCL_ICD_DISABLE_DYNAMIC_LIBRARY_UNLOADING");
+    khrInitializeFlagWithEnv(&khrForceLegacyTermination, "OCL_ICD_FORCE_LEGACY_TERMINATION");
+}
+
 // entrypoint to initialize the ICD and add all vendors
 void khrIcdInitialize(void)
 {
@@ -186,6 +202,14 @@ void khrIcdVendorAdd(const char *libraryName)
 #endif
 
         // call clGetPlatformInfo on the returned platform to get the suffix
+
+        KHR_ICD2_DISPATCH(platforms[i])->clGetPlatformInfo(
+            platforms[i],
+            CL_PLATFORM_UNLOADABLE_KHR,
+            sizeof(vendor->unloadable),
+            &vendor->unloadable,
+            NULL);
+
         result = KHR_ICD2_DISPATCH(platforms[i])->clGetPlatformInfo(
             platforms[i],
             CL_PLATFORM_ICD_SUFFIX_KHR,
@@ -230,11 +254,13 @@ void khrIcdVendorAdd(const char *libraryName)
         vendor->suffix = suffix;
 
         // add this vendor to the list of vendors at the tail
-        {
-            KHRicdVendor **prevNextPointer = NULL;
-            for (prevNextPointer = &khrIcdVendors; *prevNextPointer; prevNextPointer = &( (*prevNextPointer)->next) );
-            *prevNextPointer = vendor;
+        if (lastVendor) {
+            lastVendor->next = vendor;
+            vendor->prev = lastVendor;
+        } else {
+            khrIcdVendors = vendor;
         }
+        lastVendor = vendor;
 
         KHR_ICD_TRACE("successfully added vendor %s with suffix %s\n", libraryName, suffix);
 
@@ -259,6 +285,8 @@ void khrIcdLayerAdd(const char *libraryName)
     cl_int result = CL_SUCCESS;
     pfn_clGetLayerInfo p_clGetLayerInfo = NULL;
     pfn_clInitLayer p_clInitLayer = NULL;
+    pfn_clInitLayerWithProperties p_clInitLayerWithProperties = NULL;
+    pfn_clDeinitLayer p_clDeinitLayer = NULL;
     struct KHRLayer *layerIterator = NULL;
     struct KHRLayer *layer = NULL;
     cl_layer_api_version api_version = 0;
@@ -300,14 +328,6 @@ void khrIcdLayerAdd(const char *libraryName)
         goto Done;
     }
 
-    // use that function to get the clInitLayer function pointer
-    p_clInitLayer = (pfn_clInitLayer)(size_t)khrIcdOsLibraryGetFunctionAddress(library, "clInitLayer");
-    if (!p_clInitLayer)
-    {
-        KHR_ICD_TRACE("failed to get function address clInitLayer\n");
-        goto Done;
-    }
-
     result = p_clGetLayerInfo(CL_LAYER_API_VERSION, sizeof(api_version), &api_version, NULL);
     if (CL_SUCCESS != result)
     {
@@ -321,6 +341,31 @@ void khrIcdLayerAdd(const char *libraryName)
         goto Done;
     }
 
+    // Support old version of layers, which should rely on at_exit for termination.
+    // In this case use clInitLayer to initialize layers
+    if (khrForceLegacyTermination)
+    {
+        p_clInitLayer = (pfn_clInitLayer)(size_t)khrIcdOsLibraryGetFunctionAddress(library, "clInitLayer");
+        if (!p_clInitLayer)
+        {
+            KHR_ICD_TRACE("failed to get function address clInitLayer\n");
+            goto Done;
+        }
+    } else { // New scheme, relies on clInitLayerWithProperties and the optional clDeinitLayer for termination
+        p_clInitLayerWithProperties = (pfn_clInitLayerWithProperties)(size_t)khrIcdOsLibraryGetFunctionAddress(library, "clInitLayerWithProperties");
+        if (!p_clInitLayerWithProperties)
+        {
+            KHR_ICD_TRACE("failed to get function address clInitLayerWithProperties\n");
+            goto Done;
+        }
+
+        p_clDeinitLayer = (pfn_clDeinitLayer)(size_t)khrIcdOsLibraryGetFunctionAddress(library, "clDeinitLayer");
+        if (!p_clDeinitLayer)
+        {
+            KHR_ICD_TRACE("layer does not support clDeinitLayer\n");
+        }
+    }
+
     layer = (struct KHRLayer*)calloc(sizeof(struct KHRLayer), 1);
     if (!layer)
     {
@@ -338,9 +383,10 @@ void khrIcdLayerAdd(const char *libraryName)
             goto Done;
         }
         memcpy(layer->libraryName, libraryName, sz_name);
-        layer->p_clGetLayerInfo = (void *)(size_t)p_clGetLayerInfo;
+        layer->p_clGetLayerInfo = p_clGetLayerInfo;
     }
 #endif
+    layer->p_clDeinitLayer = p_clDeinitLayer;
 
     if (khrFirstLayer) {
         targetDispatch = &(khrFirstLayer->dispatch);
@@ -349,11 +395,21 @@ void khrIcdLayerAdd(const char *libraryName)
     }
 
     loaderDispatchNumEntries = sizeof(khrMainDispatch)/sizeof(void*);
-    result = p_clInitLayer(
-        loaderDispatchNumEntries,
-        targetDispatch,
-        &layerDispatchNumEntries,
-        &layerDispatch);
+    if (khrForceLegacyTermination)
+    {
+        result = p_clInitLayer(
+            loaderDispatchNumEntries,
+            targetDispatch,
+            &layerDispatchNumEntries,
+            &layerDispatch);
+    } else {
+        result = p_clInitLayerWithProperties(
+            loaderDispatchNumEntries,
+            targetDispatch,
+            &layerDispatchNumEntries,
+            &layerDispatch,
+            NULL);
+    }
     if (CL_SUCCESS != result)
     {
         KHR_ICD_TRACE("failed to initialize layer\n");
@@ -472,3 +528,50 @@ void khrIcdContextPropertiesGetPlatform(const cl_context_properties *properties,
     }
 }
 
+#if defined(CL_ENABLE_LAYERS)
+static struct KHRLayer deinitLayer = {0};
+#endif
+
+void khrIcdDeinitialize(void) {
+    if (khrForceLegacyTermination)
+    {
+        KHR_ICD_TRACE("ICD Loader deinitialization disabled\n");
+        return;
+    }
+
+    KHR_ICD_TRACE("ICD Loader deinitialization\n");
+
+#if defined(CL_ENABLE_LAYERS)
+    // free layers first in reverse order of their creation (front to back)
+    // they may still need to use vendors while terminating
+    KHR_ICD_TRACE("Finalizing and unloading layers\n");
+    struct KHRLayer *head = khrFirstLayer;
+    deinitLayer.dispatch = khrDeinitDispatch;
+    khrFirstLayer = &deinitLayer;
+
+    while(head) {
+        struct KHRLayer *cur = head;
+#ifdef CL_LAYER_INFO
+        free(cur->libraryName);
+#endif
+        if (cur->p_clDeinitLayer)
+            cur->p_clDeinitLayer();
+        if (!khrDisableLibraryUnloading)
+            khrIcdOsLibraryUnload(cur->library);
+        head = cur->next;
+        free(cur);
+    }
+#endif // defined(CL_ENABLE_LAYERS)
+
+    // free vendor in reverse order of their creation (back to front)
+    KHR_ICD_TRACE("Finalizing and unloading vendors\n");
+    while (lastVendor) {
+        KHRicdVendor *cur = lastVendor;
+        free(cur->suffix);
+        if (cur->unloadable && !khrDisableLibraryUnloading)
+            khrIcdOsLibraryUnload(cur->library);
+        lastVendor = cur->prev;
+        free(cur);
+    }
+    khrIcdVendors = NULL;
+}

loader/icd.h

@@ -49,6 +49,9 @@
 #include <CL/cl.h>
 #include <CL/cl_ext.h>
 #include <CL/cl_icd.h>
+#if defined(CL_ENABLE_LAYERS)
+#include <CL/cl_layer.h>
+#endif // defined(CL_ENABLE_LAYERS)
 #include <stdio.h>
 
 /*
@@ -85,6 +88,9 @@ struct KHRicdVendorRec
     // the extension suffix for this platform
     char *suffix;
 
+    // can this vendor library be unloaded?
+    cl_bool unloadable;
+
     // function pointer to the ICD platform IDs extracted from the library
     pfn_clGetExtensionFunctionAddress clGetExtensionFunctionAddress;
 
@@ -98,6 +104,7 @@ struct KHRicdVendorRec
 
     // next vendor in the list vendors
     KHRicdVendor *next;
+    KHRicdVendor *prev;
 };
 
 // the global state
@@ -123,14 +130,17 @@ struct KHRLayer
 #ifdef CL_LAYER_INFO
     // The layer library name
     char *libraryName;
-    // the pointer to the clGetLayerInfo funciton
-    void *p_clGetLayerInfo;
+    // the pointer to the clGetLayerInfo function
+    pfn_clGetLayerInfo p_clGetLayerInfo;
 #endif
+    // the pointer to the clDeinitLayer function
+    pfn_clDeinitLayer p_clDeinitLayer;
 };
 
 // the global layer state
 extern struct KHRLayer * khrFirstLayer;
 extern const struct _cl_icd_dispatch khrMainDispatch;
+extern const struct _cl_icd_dispatch khrDeinitDispatch;
 #endif // defined(CL_ENABLE_LAYERS)
 
 /* 
@@ -144,8 +154,11 @@ extern const struct _cl_icd_dispatch khrMainDispatch;
 // API (e.g, getPlatformIDs, etc).
 void khrIcdInitialize(void);
 
-// entrypoint to check and initialize trace.
-void khrIcdInitializeTrace(void);
+// entrypoint to check and initialize env options.
+void khrIcdInitializeEnvOptions(void);
+
+// entrypoint to release icd resources
+void khrIcdDeinitialize(void);
 
 // go through the list of vendors (in /etc/OpenCL.conf or through 
 // the registry) and call khrIcdVendorAdd for each vendor encountered