initial ICD loader environment variable support (#77)

* basic ICD loader env var support for OCL_ICD_VENDORS

* added envvars source files

* added OCL_ICD_FILENAMES support

* added README section describing debug environment variables

* refactored platform specific defines into icd_platform.h

* disable tracing

Author: bashbaug

CMakeLists.txt

@@ -33,15 +33,28 @@ find_package (Threads REQUIRED)
 # advance. Use it with discretion.
 option (BUILD_SHARED_LIBS "Build shared libs" ON)
 
+include(CheckFunctionExists)
+check_function_exists(secure_getenv HAVE_SECURE_GETENV)
+check_function_exists(__secure_getenv HAVE___SECURE_GETENV)
+configure_file(${CMAKE_CURRENT_SOURCE_DIR}/loader/icd_cmake_config.h.in
+    ${CMAKE_CURRENT_BINARY_DIR}/icd_cmake_config.h)
+
 set (OPENCL_ICD_LOADER_SOURCES
     loader/icd.c
-    loader/icd_dispatch.c)
+    loader/icd.h
+    loader/icd_dispatch.c
+    loader/icd_dispatch.h
+    loader/icd_envvars.h
+    loader/icd_platform.h)
 
 if (WIN32)
     list (APPEND OPENCL_ICD_LOADER_SOURCES 
         loader/windows/icd_windows.c
-        loader/windows/icd_windows_hkr.c
         loader/windows/icd_windows_dxgk.c
+        loader/windows/icd_windows_dxgk.h
+        loader/windows/icd_windows_envvars.c
+        loader/windows/icd_windows_hkr.c
+        loader/windows/icd_windows_hkr.h
         loader/windows/OpenCL.def
         loader/windows/OpenCL.rc)
     # Only add the DXSDK include directory if the environment variable is
@@ -53,6 +66,7 @@ if (WIN32)
 else ()
     list (APPEND OPENCL_ICD_LOADER_SOURCES
         loader/linux/icd_linux.c
+        loader/linux/icd_linux_envvars.c
         loader/linux/icd_exports.map)
 endif ()
 
@@ -108,7 +122,7 @@ endif ()
 include_directories (${OPENCL_ICD_LOADER_HEADERS_DIR})
 add_definitions (-DCL_TARGET_OPENCL_VERSION=220)
 
-target_include_directories (OpenCL PRIVATE loader)
+target_include_directories (OpenCL PRIVATE ${CMAKE_CURRENT_BINARY_DIR} loader)
 target_link_libraries (OpenCL ${CMAKE_DL_LIBS})
 
 include (CTest)

README.md

@@ -115,4 +115,13 @@ Please create a GitHub issue to report an issue or ask questions.
 ## Contributing
 
 Contributions to the OpenCL ICD Loader are welcomed and encouraged.
-You will be prompted with a one-time "click-through" CLA dialog as part of submitting your pull request or other contribution to GitHub.
+You will be prompted with a one-time "click-through" CLA dialog as part of submitting your pull request or other contribution to GitHub.
+
+## Table of Debug Environment Variables
+
+The following debug environment variables are available for use with the OpenCL ICD loader:
+
+| Environment Variable              | Behavior            |  Example Format      |
+|:---------------------------------:|---------------------|----------------------|
+| OCL_ICD_FILENAMES                 | Specifies a list of additional ICDs to load.  The ICDs will be enumerated first, before any ICDs discovered via default mechanisms. | `export OCL_ICD_FILENAMES=libVendorA.so:libVendorB.so`<br/><br/>`set OCL_ICD_FILENAMES=vendor_a.dll;vendor_b.dll` |
+| OCL_ICD_VENDORS                   | On Linux and Android, specifies a directory to scan for ICDs to enumerate in place of the default `/etc/OpenCL/vendors'. |  `export OCL_ICD_VENDORS=/my/local/icd/search/path` |

loader/icd.c

@@ -18,6 +18,7 @@
 
 #include "icd.h"
 #include "icd_dispatch.h"
+#include "icd_envvars.h"
 #include <stdlib.h>
 #include <string.h>
 
@@ -188,6 +189,46 @@ void khrIcdVendorAdd(const char *libraryName)
     }
 }
 
+// Get next file or dirname given a string list or registry key path.
+// Note: the input string may be modified!
+static char *loader_get_next_path(char *path) {
+    size_t len;
+    char *next;
+
+    if (path == NULL) return NULL;
+    next = strchr(path, PATH_SEPARATOR);
+    if (next == NULL) {
+        len = strlen(path);
+        next = path + len;
+    } else {
+        *next = '\0';
+        next++;
+    }
+
+    return next;
+}
+
+void khrIcdVendorsEnumerateEnv(void)
+{
+    char* icdFilenames = khrIcd_secure_getenv("OCL_ICD_FILENAMES");
+    char* cur_file = NULL;
+    char* next_file = NULL;
+    if (icdFilenames)
+    {
+        KHR_ICD_TRACE("Found OCL_ICD_FILENAMES environment variable.\n");
+
+        next_file = icdFilenames;
+        while (NULL != next_file && *next_file != '\0') {
+            cur_file = next_file;
+            next_file = loader_get_next_path(cur_file);
+
+            khrIcdVendorAdd(cur_file);
+        }
+
+        khrIcd_free_getenv(icdFilenames);
+    }
+}
+
 void khrIcdContextPropertiesGetPlatform(const cl_context_properties *properties, cl_platform_id *outPlatform)
 {
     if (properties == NULL && khrIcdVendors != NULL)

loader/icd.h

@@ -19,6 +19,8 @@
 #ifndef _ICD_H_
 #define _ICD_H_
 
+#include "icd_platform.h"
+
 #ifndef CL_USE_DEPRECATED_OPENCL_1_0_APIS
 #define CL_USE_DEPRECATED_OPENCL_1_0_APIS
 #endif
@@ -34,10 +36,6 @@
 #include <CL/cl.h>
 #include <CL/cl_ext.h>
 
-#ifdef _WIN32
-#include <tchar.h>
-#endif
-
 /*
  * type definitions
  */
@@ -101,6 +99,9 @@ void khrIcdInitialize(void);
 // n.b, this call is OS-specific
 void khrIcdOsVendorsEnumerateOnce(void);
 
+// read vendors from environment variables
+void khrIcdVendorsEnumerateEnv(void);
+
 // add a vendor's implementation to the list of libraries
 void khrIcdVendorAdd(const char *libraryName);
 

loader/icd_cmake_config.h.in

@@ -0,0 +1,2 @@
+#cmakedefine HAVE_SECURE_GETENV
+#cmakedefine HAVE___SECURE_GETENV

loader/icd_envvars.h

@@ -0,0 +1,26 @@
+/*
+ * Copyright (c) 2016-2019 The Khronos Group Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * OpenCL is a trademark of Apple Inc. used under license by Khronos.
+ */
+
+#ifndef _ICD_ENVVARS_H_
+#define _ICD_ENVVARS_H_
+
+char *khrIcd_getenv(const char *name);
+char *khrIcd_secure_getenv(const char *name);
+void khrIcd_free_getenv(char *val);
+
+#endif

loader/icd_platform.h

@@ -0,0 +1,39 @@
+/*
+ * Copyright (c) 2016-2019 The Khronos Group Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * OpenCL is a trademark of Apple Inc. used under license by Khronos.
+ */
+
+#ifndef _ICD_PLATFORM_H_
+#define _ICD_PLATFORM_H_
+
+#if defined(__linux__) || defined(__APPLE__)
+
+#define PATH_SEPARATOR  ':'
+#define DIRECTORY_SYMBOL '/'
+#ifdef __ANDROID__
+#define ICD_VENDOR_PATH "/system/vendor/Khronos/OpenCL/vendors/";
+#else
+#define ICD_VENDOR_PATH "/etc/OpenCL/vendors/";
+#endif // ANDROID
+
+#elif defined(_WIN32)
+
+#define PATH_SEPARATOR ';'
+#define DIRECTORY_SYMBOL '\\'
+
+#endif
+
+#endif