loader/icd.h

   1 /*
   2  * Copyright (c) 2016-2019 The Khronos Group Inc.
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  *     http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  *
  16  * OpenCL is a trademark of Apple Inc. used under license by Khronos.
  17  */
  18
  19 #ifndef _ICD_H_
  20 #define _ICD_H_
  21
  22 #ifndef CL_USE_DEPRECATED_OPENCL_1_0_APIS
  23 #define CL_USE_DEPRECATED_OPENCL_1_0_APIS
  24 #endif
  25
  26 #ifndef CL_USE_DEPRECATED_OPENCL_1_1_APIS
  27 #define CL_USE_DEPRECATED_OPENCL_1_1_APIS
  28 #endif
  29
  30 #ifndef CL_USE_DEPRECATED_OPENCL_1_2_APIS
  31 #define CL_USE_DEPRECATED_OPENCL_1_2_APIS
  32 #endif
  33
  34 #include <CL/cl.h>
  35 #include <CL/cl_ext.h>
  36
  37 #ifdef _WIN32
  38 #include <tchar.h>
  39 #endif
  40
  41 /*
  42  * type definitions
  43  */
  44
  45 typedef CL_API_ENTRY cl_int (CL_API_CALL *pfn_clIcdGetPlatformIDs)(
  46     cl_uint num_entries,
  47     cl_platform_id *platforms,
  48     cl_uint *num_platforms) CL_API_SUFFIX__VERSION_1_0;
  49
  50 typedef CL_API_ENTRY cl_int (CL_API_CALL *pfn_clGetPlatformInfo)(
  51     cl_platform_id   platform,
  52     cl_platform_info param_name,
  53     size_t           param_value_size,
  54     void *           param_value,
  55     size_t *         param_value_size_ret) CL_API_SUFFIX__VERSION_1_0;
  56
  57 typedef CL_API_ENTRY void *(CL_API_CALL *pfn_clGetExtensionFunctionAddress)(
  58     const char *function_name)  CL_API_SUFFIX__VERSION_1_0;
  59
  60 typedef struct KHRicdVendorRec KHRicdVendor;
  61
  62 /*
  63  * KHRicdVendor
  64  *
  65  * Data for a single ICD vendor platform.
  66  */
  67 struct KHRicdVendorRec
  68 {
  69     // the loaded library object (true type varies on Linux versus Windows)
  70     void *library;
  71
  72     // the extension suffix for this platform
  73     char *suffix;
  74
  75     // function pointer to the ICD platform IDs extracted from the library
  76     pfn_clGetExtensionFunctionAddress clGetExtensionFunctionAddress;
  77
  78     // the platform retrieved from clGetIcdPlatformIDsKHR
  79     cl_platform_id platform;
  80
  81     // next vendor in the list vendors
  82     KHRicdVendor *next;
  83 };
  84
  85 // the global state
  86 extern KHRicdVendor * khrIcdVendors;
  87
  88 /*
  89  * khrIcd interface
  90  */
  91
  92 // read vendors from system configuration and store the data
  93 // loaded into khrIcdState.  this will call the OS-specific
  94 // function khrIcdEnumerateVendors.  this is called at every
  95 // dispatch function which may be a valid first call into the
  96 // API (e.g, getPlatformIDs, etc).
  97 void khrIcdInitialize(void);
  98
  99 // go through the list of vendors (in /etc/OpenCL.conf or through
 100 // the registry) and call khrIcdVendorAdd for each vendor encountered
 101 // n.b, this call is OS-specific
 102 void khrIcdOsVendorsEnumerateOnce(void);
 103
 104 // add a vendor's implementation to the list of libraries
 105 void khrIcdVendorAdd(const char *libraryName);
 106
 107 // dynamically load a library.  returns NULL on failure
 108 // n.b, this call is OS-specific
 109 void *khrIcdOsLibraryLoad(const char *libraryName);
 110
 111 // get a function pointer from a loaded library.  returns NULL on failure.
 112 // n.b, this call is OS-specific
 113 void *khrIcdOsLibraryGetFunctionAddress(void *library, const char *functionName);
 114
 115 // unload a library.
 116 // n.b, this call is OS-specific
 117 void khrIcdOsLibraryUnload(void *library);
 118
 119 // parse properties and determine the platform to use from them
 120 void khrIcdContextPropertiesGetPlatform(
 121     const cl_context_properties *properties,
 122     cl_platform_id *outPlatform);
 123
 124 // internal tracing macros
 125 #if 0
 126     #include <stdio.h>
 127     #define KHR_ICD_TRACE(...) \
 128     do \
 129     { \
 130         fprintf(stderr, "KHR ICD trace at %s:%d: ", __FILE__, __LINE__); \
 131         fprintf(stderr, __VA_ARGS__); \
 132     } while (0)
 133 #ifdef _WIN32
 134 #define KHR_ICD_WIDE_TRACE(...) \
 135     do \
 136     { \
 137         fwprintf(stderr, L"KHR ICD trace at %hs:%d: ", __FILE__, __LINE__); \
 138         fwprintf(stderr, __VA_ARGS__); \
 139     } while (0)
 140 #else
 141 #define KHR_ICD_WIDE_TRACE(...)
 142 #endif
 143     #define KHR_ICD_ASSERT(x) \
 144     do \
 145     { \
 146         if (!(x)) \
 147         { \
 148             fprintf(stderr, "KHR ICD assert at %s:%d: %s failed", __FILE__, __LINE__, #x); \
 149         } \
 150     } while (0)
 151 #else
 152     #define KHR_ICD_TRACE(...)
 153     #define KHR_ICD_WIDE_TRACE(...)
 154     #define KHR_ICD_ASSERT(x)
 155 #endif
 156
 157 // if handle is NULL then return invalid_handle_error_code
 158 #define KHR_ICD_VALIDATE_HANDLE_RETURN_ERROR(handle,invalid_handle_error_code) \
 159     do \
 160     { \
 161         if (!handle) \
 162         { \
 163             return invalid_handle_error_code; \
 164         } \
 165     } while (0)
 166
 167 // if handle is NULL then set errcode_ret to invalid_handle_error and return NULL
 168 // (NULL being an invalid handle)
 169 #define KHR_ICD_VALIDATE_HANDLE_RETURN_HANDLE(handle,invalid_handle_error) \
 170     do \
 171     { \
 172         if (!handle) \
 173         { \
 174             if (errcode_ret) \
 175             { \
 176                 *errcode_ret = invalid_handle_error; \
 177             } \
 178             return NULL; \
 179         } \
 180     } while (0)
 181
 182
 183 #endif
 184