cl_khr_icd 2.0.0 loader managed dispatch (#238)

* Working cl_khr_icd 2.0.0.

* Update CMakeLists.txt

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

---------

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

Author: Kerilk

.github/workflows/presubmit.yml

@@ -397,10 +397,17 @@ jobs:
         $KEY_NAME = "HKEY_LOCAL_MACHINE\SOFTWARE\Khronos\OpenCL\Vendors"
         foreach ($Config in 'Release','Debug') {
           $VALUE_NAME = "${env:GITHUB_WORKSPACE}/build/$Config/OpenCLDriverStub.dll"
+          $VALUE_NAME_2 = "${env:GITHUB_WORKSPACE}/build/$Config/OpenCLDriverStubICD2.dll"
           & $REG ADD $KEY_NAME /v $VALUE_NAME /t REG_DWORD /d 0
+          if ($LASTEXITCODE -ne 0) { throw "Editing registry failed." }
+          & $REG ADD $KEY_NAME /v $VALUE_NAME_2 /t REG_DWORD /d 0
+          if ($LASTEXITCODE -ne 0) { throw "Editing registry failed." }
           & ctest -C $Config --output-on-failure --no-tests=error --parallel ${env:NUMBER_OF_PROCESSORS}
           if ($LASTEXITCODE -ne 0) { throw "Testing OpenCL-ICD-Loader in $Config failed." }
+          & $REG DELETE $KEY_NAME /v $VALUE_NAME_2 /f
+          if ($LASTEXITCODE -ne 0) { throw "Editing registry failed." }
           & $REG DELETE $KEY_NAME /v $VALUE_NAME /f
+          if ($LASTEXITCODE -ne 0) { throw "Editing registry failed." }
         }
 
     - name: Install
@@ -429,8 +436,11 @@ jobs:
         $REG = if('${{matrix.BIN}}' -eq 'x64') {"reg"} else {"${env:SystemRoot}\Syswow64\reg.exe"}
         $KEY_NAME = "HKEY_LOCAL_MACHINE\SOFTWARE\Khronos\OpenCL\Vendors"
         $VALUE_NAME = "${env:GITHUB_WORKSPACE}/build/Release/OpenCLDriverStub.dll"
+        $VALUE_NAME_2 = "${env:GITHUB_WORKSPACE}/build/Release/OpenCLDriverStubICD2.dll"
         & $REG ADD $KEY_NAME /v $VALUE_NAME /t REG_DWORD /d 0
         if ($LASTEXITCODE -ne 0) { throw "Editing registry failed." }
+        & $REG ADD $KEY_NAME /v $VALUE_NAME_2 /t REG_DWORD /d 0
+        if ($LASTEXITCODE -ne 0) { throw "Editing registry failed." }
         foreach ($Config in 'Release','Debug') {
           & cmake `
             --build "${env:GITHUB_WORKSPACE}\downstream\pkgconfig\bare" `
@@ -442,6 +452,8 @@ jobs:
         }
         & $REG DELETE $KEY_NAME /v $VALUE_NAME /f
         if ($LASTEXITCODE -ne 0) { throw "Editing registry failed." }
+        & $REG DELETE $KEY_NAME /v $VALUE_NAME_2 /f
+        if ($LASTEXITCODE -ne 0) { throw "Editing registry failed." }
 
     - name: "Consume (Ninja-Multi-Config standalone): Configure/Build/Test"
       if: matrix.GEN == 'Ninja Multi-Config'
@@ -464,8 +476,11 @@ jobs:
         $REG = if('${{matrix.BIN}}' -eq 'x64') {"reg"} else {"${env:SystemRoot}\Syswow64\reg.exe"}
         $KEY_NAME = "HKEY_LOCAL_MACHINE\SOFTWARE\Khronos\OpenCL\Vendors"
         $VALUE_NAME = "${env:GITHUB_WORKSPACE}/build/Release/OpenCLDriverStub.dll"
+        $VALUE_NAME_2 = "${env:GITHUB_WORKSPACE}/build/Release/OpenCLDriverStubICD2.dll"
         & $REG ADD $KEY_NAME /v $VALUE_NAME /t REG_DWORD /d 0
         if ($LASTEXITCODE -ne 0) { throw "Editing registry failed." }
+        & $REG ADD $KEY_NAME /v $VALUE_NAME_2 /t REG_DWORD /d 0
+        if ($LASTEXITCODE -ne 0) { throw "Editing registry failed." }
         foreach ($Config in 'Release','Debug') {
           & cmake `
             --build "${env:GITHUB_WORKSPACE}\downstream\pkgconfig\bare" `
@@ -477,6 +492,8 @@ jobs:
         }
         & $REG DELETE $KEY_NAME /v $VALUE_NAME /f
         if ($LASTEXITCODE -ne 0) { throw "Editing registry failed." }
+        & $REG DELETE $KEY_NAME /v $VALUE_NAME_2 /f
+        if ($LASTEXITCODE -ne 0) { throw "Editing registry failed." }
 
     - name: Consume (Emulate SDK presence)
       run: |
@@ -502,8 +519,11 @@ jobs:
         $REG = if('${{matrix.BIN}}' -eq 'x64') {"reg"} else {"${env:SystemRoot}\Syswow64\reg.exe"}
         $KEY_NAME = "HKEY_LOCAL_MACHINE\SOFTWARE\Khronos\OpenCL\Vendors"
         $VALUE_NAME = "${env:GITHUB_WORKSPACE}/build/Release/OpenCLDriverStub.dll"
+        $VALUE_NAME_2 = "${env:GITHUB_WORKSPACE}/build/Release/OpenCLDriverStubICD2.dll"
         & $REG ADD $KEY_NAME /v $VALUE_NAME /t REG_DWORD /d 0
         if ($LASTEXITCODE -ne 0) { throw "Editing registry failed." }
+        & $REG ADD $KEY_NAME /v $VALUE_NAME_2 /t REG_DWORD /d 0
+        if ($LASTEXITCODE -ne 0) { throw "Editing registry failed." }
         foreach ($Config in 'Release','Debug') {
           & cmake `
             --build "${env:GITHUB_WORKSPACE}\downstream\pkgconfig\sdk" `
@@ -515,6 +535,8 @@ jobs:
         }
         & $REG DELETE $KEY_NAME /v $VALUE_NAME /f
         if ($LASTEXITCODE -ne 0) { throw "Editing registry failed." }
+        & $REG DELETE $KEY_NAME /v $VALUE_NAME_2 /f
+        if ($LASTEXITCODE -ne 0) { throw "Editing registry failed." }
 
     - name: "Consume (Ninja-Multi-Config SDK): Configure/Build/Test"
       if: matrix.GEN == 'Ninja Multi-Config'
@@ -537,8 +559,11 @@ jobs:
         $REG = if('${{matrix.BIN}}' -eq 'x64') {"reg"} else {"${env:SystemRoot}\Syswow64\reg.exe"}
         $KEY_NAME = "HKEY_LOCAL_MACHINE\SOFTWARE\Khronos\OpenCL\Vendors"
         $VALUE_NAME = "${env:GITHUB_WORKSPACE}/build/Release/OpenCLDriverStub.dll"
+        $VALUE_NAME_2 = "${env:GITHUB_WORKSPACE}/build/Release/OpenCLDriverStubICD2.dll"
         & $REG ADD $KEY_NAME /v $VALUE_NAME /t REG_DWORD /d 0
         if ($LASTEXITCODE -ne 0) { throw "Editing registry failed." }
+        & $REG ADD $KEY_NAME /v $VALUE_NAME_2 /t REG_DWORD /d 0
+        if ($LASTEXITCODE -ne 0) { throw "Editing registry failed." }
         foreach ($Config in 'Release','Debug') {
           & cmake `
             --build "${env:GITHUB_WORKSPACE}\downstream\pkgconfig\sdk" `
@@ -550,6 +575,8 @@ jobs:
         }
         & $REG DELETE $KEY_NAME /v $VALUE_NAME /f
         if ($LASTEXITCODE -ne 0) { throw "Editing registry failed." }
+        & $REG DELETE $KEY_NAME /v $VALUE_NAME_2 /f
+        if ($LASTEXITCODE -ne 0) { throw "Editing registry failed." }
 
   macos:
     runs-on: macos-latest

CMakeLists.txt

@@ -52,6 +52,7 @@ option(OPENCL_ICD_LOADER_BUILD_SHARED_LIBS "Build OpenCL ICD Loader as shared li
 # It is currently needed default while the specification is being formalized,
 # and to study the performance impact.
 option (ENABLE_OPENCL_LAYERS "Enable OpenCL Layers" ON)
+option (ENABLE_OPENCL_LOADER_MANAGED_DISPATCH "Enable OpenCL Loader managed dispatch" ON)
 include(CMakeDependentOption)
 cmake_dependent_option(ENABLE_OPENCL_LAYERINFO "Enable building cllayerinfo tool" ON ENABLE_OPENCL_LAYERS OFF)
 
@@ -68,6 +69,7 @@ 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
+    include/cl_khr_icd2.h
     loader/icd.c
     loader/icd.h
     loader/icd_version.h
@@ -76,6 +78,7 @@ set (OPENCL_ICD_LOADER_SOURCES
     loader/icd_dispatch_generated.c
     loader/icd_envvars.h
     loader/icd_platform.h)
+include_directories (include)
 
 if (WIN32)
     list (APPEND OPENCL_ICD_LOADER_SOURCES
@@ -159,8 +162,9 @@ 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=6
+    OPENCL_ICD_LOADER_VERSION_REV=7
     $<$<BOOL:${ENABLE_OPENCL_LAYERS}>:CL_ENABLE_LAYERS>
+    $<$<BOOL:${ENABLE_OPENCL_LOADER_MANAGED_DISPATCH}>:CL_ENABLE_LOADER_MANAGED_DISPATCH>
 )
 
 target_compile_definitions (OpenCL

include/cl_khr_icd2.h

@@ -0,0 +1,41 @@
+/*
+ * Copyright (c) 2016-2025 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.
+ */
+
+#if !defined(CL_ICD2_TAG_KHR)
+#if INTPTR_MAX == INT32_MAX
+#define CL_ICD2_TAG_KHR ((intptr_t)0x434C3331)
+#else
+#define CL_ICD2_TAG_KHR ((intptr_t)0x4F50454E434C3331)
+#endif
+
+typedef void * CL_API_CALL
+clIcdGetFunctionAddressForPlatformKHR_t(
+    cl_platform_id platform,
+    const char* func_name);
+
+typedef clIcdGetFunctionAddressForPlatformKHR_t *
+clIcdGetFunctionAddressForPlatformKHR_fn;
+
+typedef cl_int CL_API_CALL
+clIcdSetPlatformDispatchDataKHR_t(
+    cl_platform_id platform,
+    void *disp_data);
+
+typedef clIcdSetPlatformDispatchDataKHR_t *
+clIcdSetPlatformDispatchDataKHR_fn;
+#endif // !defined(CL_ICD2_TAG_KHR)

loader/icd.c

@@ -58,6 +58,10 @@ void khrIcdVendorAdd(const char *libraryName)
     cl_int result = CL_SUCCESS;
     pfn_clGetExtensionFunctionAddress p_clGetExtensionFunctionAddress = NULL;
     pfn_clIcdGetPlatformIDs p_clIcdGetPlatformIDs = NULL;
+#if defined(CL_ENABLE_LOADER_MANAGED_DISPATCH)
+    clIcdGetFunctionAddressForPlatformKHR_fn p_clIcdGetFunctionAddressForPlatform = NULL;
+    clIcdSetPlatformDispatchDataKHR_fn p_clIcdSetPlatformDispatchData = NULL;
+#endif
     cl_uint i = 0;
     cl_uint platformCount = 0;
     cl_platform_id *platforms = NULL;
@@ -104,6 +108,12 @@ void khrIcdVendorAdd(const char *libraryName)
         goto Done;
     }
 
+#if defined(CL_ENABLE_LOADER_MANAGED_DISPATCH)
+    // try to get clIcdGetFunctionAddressForPlatformKHR and clIcdSetPlatformDispatchDataKHR to detect cl_khr_icd2 support
+    p_clIcdGetFunctionAddressForPlatform = (clIcdGetFunctionAddressForPlatformKHR_fn)(size_t)p_clGetExtensionFunctionAddress("clIcdGetFunctionAddressForPlatformKHR");
+    p_clIcdSetPlatformDispatchData = (clIcdSetPlatformDispatchDataKHR_fn)(size_t)p_clGetExtensionFunctionAddress("clIcdSetPlatformDispatchDataKHR");
+#endif
+
     // query the number of platforms available and allocate space to store them
     result = p_clIcdGetPlatformIDs(0, NULL, &platformCount);
     if (CL_SUCCESS != result)
@@ -132,27 +142,68 @@ void khrIcdVendorAdd(const char *libraryName)
         char *suffix;
         size_t suffixSize;
 
-        // call clGetPlatformInfo on the returned platform to get the suffix
-        if (!platforms[i])
+        // skip NULL platforms and non dispatchable platforms
+        if (!platforms[i] || !platforms[i]->dispatch)
+        {
+            continue;
+        }
+
+#if defined(CL_ENABLE_LOADER_MANAGED_DISPATCH)
+        if (KHR_ICD2_HAS_TAG(platforms[i]) && !p_clIcdGetFunctionAddressForPlatform)
+        {
+           KHR_ICD_TRACE("found icd 2 object, but platform is missing clIcdGetFunctionAddressForPlatformKHR\n");
+           continue;
+        }
+        if (KHR_ICD2_HAS_TAG(platforms[i]) && !p_clIcdSetPlatformDispatchData)
+        {
+           KHR_ICD_TRACE("found icd 2 object, but platform is missing clIcdSetPlatformDispatchDataKHR\n");
+           continue;
+        }
+        if (KHR_ICD2_HAS_TAG(platforms[i]) && !((intptr_t)((platforms[i])->dispatch->clUnloadCompiler) == CL_ICD2_TAG_KHR))
+        {
+           KHR_ICD_TRACE("found icd 2 object, but platform is missing tag in clUnloadCompiler\n");
+           continue;
+        }
+#endif
+
+        // allocate a structure for the vendor
+        vendor = (KHRicdVendor*)malloc(sizeof(*vendor) );
+        if (!vendor)
         {
+            KHR_ICD_TRACE("failed to allocate memory\n");
             continue;
         }
-        result = platforms[i]->dispatch->clGetPlatformInfo(
+        memset(vendor, 0, sizeof(*vendor));
+
+#if defined(CL_ENABLE_LOADER_MANAGED_DISPATCH)
+        // populate cl_khr_icd2 platform's loader managed dispatch tables
+        if (KHR_ICD2_HAS_TAG(platforms[i]))
+        {
+            khrIcd2PopulateDispatchTable(platforms[i], p_clIcdGetFunctionAddressForPlatform, &vendor->dispData.dispatch);
+            p_clIcdSetPlatformDispatchData(platforms[i], &vendor->dispData);
+            KHR_ICD_TRACE("found icd 2 platform, using loader managed dispatch\n");
+        }
+#endif
+
+        // call clGetPlatformInfo on the returned platform to get the suffix
+        result = KHR_ICD2_DISPATCH(platforms[i])->clGetPlatformInfo(
             platforms[i],
             CL_PLATFORM_ICD_SUFFIX_KHR,
             0,
             NULL,
             &suffixSize);
         if (CL_SUCCESS != result)
         {
+            free(vendor);
             continue;
         }
         suffix = (char *)malloc(suffixSize);
         if (!suffix)
         {
+            free(vendor);
             continue;
         }
-        result = platforms[i]->dispatch->clGetPlatformInfo(
+        result = KHR_ICD2_DISPATCH(platforms[i])->clGetPlatformInfo(
             platforms[i],
             CL_PLATFORM_ICD_SUFFIX_KHR,
             suffixSize,
@@ -161,19 +212,10 @@ void khrIcdVendorAdd(const char *libraryName)
         if (CL_SUCCESS != result)
         {
             free(suffix);
+            free(vendor);
             continue;
         }
 
-        // allocate a structure for the vendor
-        vendor = (KHRicdVendor*)malloc(sizeof(*vendor) );
-        if (!vendor) 
-        {
-            free(suffix);
-            KHR_ICD_TRACE("failed to allocate memory\n");
-            continue;
-        }
-        memset(vendor, 0, sizeof(*vendor) );
-
         // populate vendor data
         vendor->library = khrIcdOsLibraryLoad(libraryName);
         if (!vendor->library) 

loader/icd.h

@@ -20,6 +20,7 @@
 #define _ICD_H_
 
 #include "icd_platform.h"
+#include "icd_dispatch.h"
 
 #ifndef CL_USE_DEPRECATED_OPENCL_1_0_APIS
 #define CL_USE_DEPRECATED_OPENCL_1_0_APIS
@@ -90,6 +91,11 @@ struct KHRicdVendorRec
     // the platform retrieved from clGetIcdPlatformIDsKHR
     cl_platform_id platform;
 
+#if defined(CL_ENABLE_LOADER_MANAGED_DISPATCH)
+    // the loader populated dispatch table for cl_khr_icd2 compliant platforms
+    struct KHRDisp dispData;
+#endif
+
     // next vendor in the list vendors
     KHRicdVendor *next;
 };
@@ -201,11 +207,24 @@ do \
 #define KHR_ICD_WIDE_TRACE(...)
 #endif
 
+#define KHR_ICD_ERROR_RETURN_ERROR(_error)                          \
+do {                                                                \
+    return _error;                                                  \
+} while(0)
+
+#define KHR_ICD_ERROR_RETURN_HANDLE(_error)                         \
+do {                                                                \
+    if (errcode_ret) {                                              \
+        *errcode_ret = _error;                                      \
+    }                                                               \
+    return NULL;                                                    \
+} while(0)
+
 // Check if the passed-in handle is NULL, and if it is, return the error.
 #define KHR_ICD_VALIDATE_HANDLE_RETURN_ERROR(_handle, _error)       \
 do {                                                                \
     if (!_handle) {                                                 \
-        return _error;                                              \
+        KHR_ICD_ERROR_RETURN_ERROR(_error);                         \
     }                                                               \
 } while (0)
 
@@ -214,10 +233,7 @@ do {                                                                \
 #define KHR_ICD_VALIDATE_HANDLE_RETURN_HANDLE(_handle, _error)      \
 do {                                                                \
     if (!_handle) {                                                 \
-        if (errcode_ret) {                                          \
-            *errcode_ret = _error;                                  \
-        }                                                           \
-        return NULL;                                                \
+        KHR_ICD_ERROR_RETURN_HANDLE(_error);                        \
     }                                                               \
 } while (0)
 
@@ -226,7 +242,7 @@ do {                                                                \
 #define KHR_ICD_VALIDATE_POINTER_RETURN_ERROR(_pointer)             \
 do {                                                                \
     if (!_pointer) {                                                \
-        return CL_INVALID_OPERATION;                                \
+        KHR_ICD_ERROR_RETURN_ERROR(CL_INVALID_OPERATION);           \
     }                                                               \
 } while (0)
 
@@ -236,10 +252,7 @@ do {                                                                \
 #define KHR_ICD_VALIDATE_POINTER_RETURN_HANDLE(_pointer)            \
 do {                                                                \
     if (!_pointer) {                                                \
-        if (errcode_ret) {                                          \
-            *errcode_ret = CL_INVALID_OPERATION;                    \
-        }                                                           \
-        return NULL;                                                \
+        KHR_ICD_ERROR_RETURN_HANDLE(CL_INVALID_OPERATION);          \
     }                                                               \
 } while (0)
 

loader/icd_dispatch.c

@@ -303,7 +303,7 @@ static inline void* clGetExtensionFunctionAddressForPlatform_body(
     // to get the extension function address.
 
     KHR_ICD_VALIDATE_HANDLE_RETURN_ERROR(platform, NULL);
-    return platform->dispatch->clGetExtensionFunctionAddressForPlatform(
+    return KHR_ICD2_DISPATCH(platform)->clGetExtensionFunctionAddressForPlatform(
         platform,
         function_name);
 }