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 // translate device type to platform
 125 void khrIcdDeviceTypeGetPlatform(
 126     cl_device_type device_type,
 127     cl_platform_id *outPlatform);
 128
 129 // internal tracing macros
 130 #if 0
 131     #include <stdio.h>
 132     #define KHR_ICD_TRACE(...) \
 133     do \
 134     { \
 135         fprintf(stderr, "KHR ICD trace at %s:%d: ", __FILE__, __LINE__); \
 136         fprintf(stderr, __VA_ARGS__); \
 137     } while (0)
 138 #ifdef _WIN32
 139 #define KHR_ICD_WIDE_TRACE(...) \
 140     do \
 141     { \
 142         fwprintf(stderr, L"KHR ICD trace at %hs:%d: ", __FILE__, __LINE__); \
 143         fwprintf(stderr, __VA_ARGS__); \
 144     } while (0)
 145 #else
 146 #define KHR_ICD_WIDE_TRACE(...)
 147 #endif
 148     #define KHR_ICD_ASSERT(x) \
 149     do \
 150     { \
 151         if (!(x)) \
 152         { \
 153             fprintf(stderr, "KHR ICD assert at %s:%d: %s failed", __FILE__, __LINE__, #x); \
 154         } \
 155     } while (0)
 156 #else
 157     #define KHR_ICD_TRACE(...)
 158     #define KHR_ICD_WIDE_TRACE(...)
 159     #define KHR_ICD_ASSERT(x)
 160 #endif
 161
 162 // if handle is NULL then return invalid_handle_error_code
 163 #define KHR_ICD_VALIDATE_HANDLE_RETURN_ERROR(handle,invalid_handle_error_code) \
 164     do \
 165     { \
 166         if (!handle) \
 167         { \
 168             return invalid_handle_error_code; \
 169         } \
 170     } while (0)
 171
 172 // if handle is NULL then set errcode_ret to invalid_handle_error and return NULL
 173 // (NULL being an invalid handle)
 174 #define KHR_ICD_VALIDATE_HANDLE_RETURN_HANDLE(handle,invalid_handle_error) \
 175     do \
 176     { \
 177         if (!handle) \
 178         { \
 179             if (errcode_ret) \
 180             { \
 181                 *errcode_ret = invalid_handle_error; \
 182             } \
 183             return NULL; \
 184         } \
 185     } while (0)
 186
 187
 188 #endif
 189