Add Support for optional ddi loading and ULTs

nrspruit · nrspruit · commit c8b0eb349450 · 2025-10-22T12:39:19.000-07:00
Signed-off-by: Neil R. Spruit &lt;neil.r.spruit@intel.com&gt;
diff --git a/.github/workflows/build-quick-static.yml b/.github/workflows/build-quick-static.yml
@@ -35,6 +35,7 @@ jobs:
               -D CMAKE_C_COMPILER_LAUNCHER=ccache \
               -D CMAKE_CXX_COMPILER_LAUNCHER=ccache \
               -D CMAKE_BUILD_TYPE=Release \
+              -D BUILD_L0_LOADER_TESTS=1 \
               -D BUILD_STATIC=0 \
               ..
             make -j$(nproc)
diff --git a/scripts/templates/ze_loader_internal.h.mako b/scripts/templates/ze_loader_internal.h.mako
@@ -71,6 +71,7 @@ namespace loader
         ze_driver_handle_t zerDriverHandle = nullptr;
         ze_api_version_t versionRequested = ZE_API_VERSION_CURRENT;
         bool ddiInitialized = false;
+        bool customDriver = false;
         ze_result_t zeddiInitResult = ZE_RESULT_ERROR_UNINITIALIZED;
         ze_result_t zetddiInitResult = ZE_RESULT_ERROR_UNINITIALIZED;
         ze_result_t zesddiInitResult = ZE_RESULT_ERROR_UNINITIALIZED;
diff --git a/source/loader/driver_discovery.h b/source/loader/driver_discovery.h
@@ -13,7 +13,13 @@
 
 namespace loader {
 
-using DriverLibraryPath = std::string;
+struct DriverLibraryPath {
+    std::string path;
+    bool customDriver;
+    
+    DriverLibraryPath(const std::string& p, bool isCustom = false) 
+        : path(p), customDriver(isCustom) {}
+};
 
 std::vector<DriverLibraryPath> discoverEnabledDrivers();
 
diff --git a/source/loader/linux/driver_discovery_lin.cpp b/source/loader/linux/driver_discovery_lin.cpp
@@ -113,17 +113,19 @@ std::vector<DriverLibraryPath> discoverEnabledDrivers() {
   // ZE_ENABLE_ALT_DRIVERS is for development/debug only
   altDrivers = getenv("ZE_ENABLE_ALT_DRIVERS");
   if (altDrivers == nullptr) {
+    // Standard drivers - not custom
     for (auto path : knownDriverNames) {
       if (libraryExistsInSearchPaths(path)) {
-        enabledDrivers.emplace_back(path);
+        enabledDrivers.emplace_back(path, false);
       }
     }
   } else {
+    // Alternative drivers from environment variable - these are custom
     std::stringstream ss(altDrivers);
     while (ss.good()) {
       std::string substr;
       getline(ss, substr, ',');
-      enabledDrivers.emplace_back(substr);
+      enabledDrivers.emplace_back(substr, true);
     }
   }
   return enabledDrivers;
diff --git a/source/loader/windows/driver_discovery_win.cpp b/source/loader/windows/driver_discovery_win.cpp
@@ -33,16 +33,18 @@ std::vector<DriverLibraryPath> discoverEnabledDrivers() {
     // ZE_ENABLE_ALT_DRIVERS is for development/debug only
     envBufferSize = GetEnvironmentVariable("ZE_ENABLE_ALT_DRIVERS", &altDrivers[0], envBufferSize);
     if (!envBufferSize) {
+        // Standard drivers discovered from registry - not custom
         auto displayDrivers = discoverDriversBasedOnDisplayAdapters(GUID_DEVCLASS_DISPLAY);
         auto computeDrivers = discoverDriversBasedOnDisplayAdapters(GUID_DEVCLASS_COMPUTEACCELERATOR);
         enabledDrivers.insert(enabledDrivers.end(), displayDrivers.begin(), displayDrivers.end());
         enabledDrivers.insert(enabledDrivers.end(), computeDrivers.begin(), computeDrivers.end());
     } else {
+        // Alternative drivers from environment variable - these are custom
         std::stringstream ss(altDrivers.c_str());
         while (ss.good()) {
             std::string substr;
             getline(ss, substr, ',');
-            enabledDrivers.emplace_back(substr);
+            enabledDrivers.emplace_back(substr, true);
         }
     }
 
@@ -110,7 +112,7 @@ DriverLibraryPath readDriverPathForDisplayAdapter(DEVINST dnDevNode) {
 
     if (CR_SUCCESS != configErr) {
         assert(false && "CM_Open_DevNode_Key failed");
-        return "";
+        return DriverLibraryPath("", false);
     }
 
     DWORD regValueType = {};
@@ -133,7 +135,7 @@ DriverLibraryPath readDriverPathForDisplayAdapter(DEVINST dnDevNode) {
     regOpStatus = RegCloseKey(hkey);
     assert((ERROR_SUCCESS == regOpStatus) && "RegCloseKey failed");
 
-    return driverPath;
+    return DriverLibraryPath(driverPath, false);
 }
 
 std::wstring readDisplayAdaptersDeviceIdsList(const GUID rguid) {
@@ -193,11 +195,12 @@ std::vector<DriverLibraryPath> discoverDriversBasedOnDisplayAdapters(const GUID
 
         auto driverPath = readDriverPathForDisplayAdapter(devinst);
 
-        if (driverPath.empty()) {
+        if (driverPath.path.empty()) {
             continue;
         }
 
-        bool alreadyOnTheList = (enabledDrivers.end() != std::find(enabledDrivers.begin(), enabledDrivers.end(), driverPath));
+        bool alreadyOnTheList = (enabledDrivers.end() != std::find_if(enabledDrivers.begin(), enabledDrivers.end(), 
+            [&driverPath](const DriverLibraryPath& d) { return d.path == driverPath.path; }));
         if (alreadyOnTheList) {
             continue;
         }
diff --git a/source/loader/ze_loader.cpp b/source/loader/ze_loader.cpp
@@ -510,19 +510,21 @@ namespace loader
                     std::string message = "init driver " + driver.name + " found GPU Supported Driver.";
                     debug_trace_message(message, "");
                 }
+                loadDriver = true;
             }
-            loadDriver = true;
         }
         if ((!desc && (flags == 0 || flags & ZE_INIT_FLAG_VPU_ONLY)) || (desc && desc->flags & ZE_INIT_DRIVER_TYPE_FLAG_NPU)) {
             if (driver.name.find("vpu") != std::string::npos || driver.name.find("npu") != std::string::npos) {
                 if (debugTraceEnabled) {
                     std::string message = "init driver " + driver.name + " found VPU/NPU Supported Driver.";
                     debug_trace_message(message, "");
                 }
+                loadDriver = true;
             }
-            loadDriver = true;
         }
 
+        loadDriver = !driver.handle && driver.customDriver ? true : loadDriver;
+
         if (loadDriver && !driver.handle) {
             auto handle = LOAD_DRIVER_LIBRARY( driver.name.c_str() );
             if( NULL != handle )
@@ -584,6 +586,14 @@ namespace loader
             driver.ddiInitialized = true;
         }
 
+        if (!driver.handle && !driver.ddiInitialized) {
+            if (debugTraceEnabled) {
+                std::string message = "init driver " + driver.name + " does not match the requested flags or desc, skipping driver.";
+                debug_trace_message(message, "");
+            }
+            return ZE_RESULT_ERROR_UNINITIALIZED;
+        }
+
         return ZE_RESULT_SUCCESS;
     }
 
@@ -682,14 +692,14 @@ namespace loader
             }
         }
 
-        for( auto name : discoveredDrivers )
+        for( auto driverInfo : discoveredDrivers )
         {
             if (discoveredDrivers.size() == 1) {
-                auto handle = LOAD_DRIVER_LIBRARY( name.c_str() );
+                auto handle = LOAD_DRIVER_LIBRARY( driverInfo.path.c_str() );
                 if( NULL != handle )
                 {
                     if (debugTraceEnabled) {
-                        std::string message = "Loading Driver " + name + " succeeded";
+                        std::string message = "Loading Driver " + driverInfo.path + " succeeded";
 #if !defined(_WIN32) && !defined(ANDROID)
                         // TODO: implement same message for windows, move dlinfo to ze_util.h as a macro
                         struct link_map *dlinfo_map;
@@ -701,17 +711,19 @@ namespace loader
                     }
                     allDrivers.emplace_back();
                     allDrivers.rbegin()->handle = handle;
-                    allDrivers.rbegin()->name = name;
+                    allDrivers.rbegin()->name = driverInfo.path;
+                    allDrivers.rbegin()->customDriver = driverInfo.customDriver;
                 } else if (debugTraceEnabled) {
                     GET_LIBRARY_ERROR(loadLibraryErrorValue);
-                    std::string errorMessage = "Load Library of " + name + " failed with ";
+                    std::string errorMessage = "Load Library of " + driverInfo.path + " failed with ";
                     debug_trace_message(errorMessage, loadLibraryErrorValue);
                     loadLibraryErrorValue.clear();
                 }
             } else {
                 allDrivers.emplace_back();
                 allDrivers.rbegin()->handle = nullptr;
-                allDrivers.rbegin()->name = name;
+                allDrivers.rbegin()->name = driverInfo.path;
+                allDrivers.rbegin()->customDriver = driverInfo.customDriver;
             }
         }
         if(allDrivers.size()==0){
diff --git a/source/loader/ze_loader_internal.h b/source/loader/ze_loader_internal.h
@@ -62,6 +62,7 @@ namespace loader
         ze_driver_handle_t zerDriverHandle = nullptr;
         ze_api_version_t versionRequested = ZE_API_VERSION_CURRENT;
         bool ddiInitialized = false;
+        bool customDriver = false;
         ze_result_t zeddiInitResult = ZE_RESULT_ERROR_UNINITIALIZED;
         ze_result_t zetddiInitResult = ZE_RESULT_ERROR_UNINITIALIZED;
         ze_result_t zesddiInitResult = ZE_RESULT_ERROR_UNINITIALIZED;
diff --git a/test/CMakeLists.txt b/test/CMakeLists.txt
@@ -11,7 +11,7 @@ add_executable(
 # Only include driver_ordering_unit_tests for static builds or non-Windows platforms
 # as it requires internal loader symbols that are not exported in Windows DLLs
 if(BUILD_STATIC OR NOT WIN32)
-  target_sources(tests PRIVATE driver_ordering_unit_tests.cpp)
+  target_sources(tests PRIVATE driver_ordering_unit_tests.cpp init_driver_unit_tests.cpp)
 endif()
 
 # For static builds, we need to include the loader source files directly
@@ -69,6 +69,37 @@ if(BUILD_STATIC)
   endif()
 endif()
 
+# Create fake driver copies for init_driver_unit_tests
+if(NOT BUILD_STATIC OR NOT WIN32)
+  if(MSVC)
+    add_custom_command(TARGET tests POST_BUILD
+      COMMAND ${CMAKE_COMMAND} -E copy_if_different
+        $<TARGET_FILE_DIR:tests>/ze_null.dll
+        $<TARGET_FILE_DIR:tests>/ze_fake_gpu.dll
+      COMMAND ${CMAKE_COMMAND} -E copy_if_different
+        $<TARGET_FILE_DIR:tests>/ze_null_test1.dll
+        $<TARGET_FILE_DIR:tests>/ze_fake_npu.dll
+      COMMAND ${CMAKE_COMMAND} -E copy_if_different
+        $<TARGET_FILE_DIR:tests>/ze_null_test2.dll
+        $<TARGET_FILE_DIR:tests>/ze_fake_vpu.dll
+      COMMENT "Copying null drivers to fake driver names for init_driver_unit_tests"
+    )
+  else()
+    add_custom_command(TARGET tests POST_BUILD
+      COMMAND ${CMAKE_COMMAND} -E copy_if_different
+        ${CMAKE_BINARY_DIR}/lib/libze_null.so.1
+        ${CMAKE_BINARY_DIR}/lib/libze_fake_gpu.so.1
+      COMMAND ${CMAKE_COMMAND} -E copy_if_different
+        ${CMAKE_BINARY_DIR}/lib/libze_null_test1.so.1
+        ${CMAKE_BINARY_DIR}/lib/libze_fake_npu.so.1
+      COMMAND ${CMAKE_COMMAND} -E copy_if_different
+        ${CMAKE_BINARY_DIR}/lib/libze_null_test2.so.1
+        ${CMAKE_BINARY_DIR}/lib/libze_fake_vpu.so.1
+      COMMENT "Copying null drivers to fake driver names for init_driver_unit_tests"
+    )
+  endif()
+endif()
+
 add_test(NAME tests_api COMMAND tests --gtest_filter=*GivenLevelZeroLoaderPresentWhenCallingzeGetLoaderVersionsAPIThenValidVersionIsReturned*)
 set_property(TEST tests_api PROPERTY ENVIRONMENT "ZE_ENABLE_LOADER_DEBUG_TRACE=1;ZE_ENABLE_NULL_DRIVER=1")
 add_test(NAME tests_init_gpu_all COMMAND tests --gtest_filter=*GivenLevelZeroLoaderPresentWhenCallingZeInitDriversWithGPUTypeThenExpectPassWithGPUorAllOnly*)
@@ -596,6 +627,9 @@ set_property(TEST driver_ordering_trim_function PROPERTY ENVIRONMENT "ZE_ENABLE_
 add_test(NAME driver_ordering_parse_driver_order COMMAND tests --gtest_filter=DriverOrderingHelperFunctionsTest.ParseDriverOrder_*)
 set_property(TEST driver_ordering_parse_driver_order PROPERTY ENVIRONMENT "ZE_ENABLE_LOADER_DEBUG_TRACE=1;ZE_ENABLE_NULL_DRIVER=1")
 
+# Init Driver Unit Tests
+add_test(NAME init_driver_unit_tests COMMAND tests --gtest_filter=InitDriverUnitTest.*)
+set_property(TEST init_driver_unit_tests PROPERTY ENVIRONMENT "ZE_ENABLE_LOADER_DEBUG_TRACE=1;ZE_ENABLE_NULL_DRIVER=1")
 
 # These tests are currently not supported on Windows. The reason is that the std::cerr is not being redirected to a pipe in Windows to be then checked against the expected output.
 if(NOT MSVC)
diff --git a/test/init_driver_unit_tests.cpp b/test/init_driver_unit_tests.cpp

Original file line number	Diff line number	Diff line change
`@@ -113,17 +113,19 @@ std::vector<DriverLibraryPath> discoverEnabledDrivers() {`
`113`	`113`	`// ZE_ENABLE_ALT_DRIVERS is for development/debug only`
`114`	`114`	`altDrivers = getenv("ZE_ENABLE_ALT_DRIVERS");`
`115`	`115`	`if (altDrivers == nullptr) {`
	`116`	`+ // Standard drivers - not custom`
`116`	`117`	`for (auto path : knownDriverNames) {`
`117`	`118`	`if (libraryExistsInSearchPaths(path)) {`
`118`		`- enabledDrivers.emplace_back(path);`
	`119`	`+ enabledDrivers.emplace_back(path, false);`
`119`	`120`	`}`
`120`	`121`	`}`
`121`	`122`	`} else {`
	`123`	`+ // Alternative drivers from environment variable - these are custom`
`122`	`124`	`std::stringstream ss(altDrivers);`
`123`	`125`	`while (ss.good()) {`
`124`	`126`	`std::string substr;`
`125`	`127`	`getline(ss, substr, ',');`
`126`		`- enabledDrivers.emplace_back(substr);`
	`128`	`+ enabledDrivers.emplace_back(substr, true);`
`127`	`129`	`}`
`128`	`130`	`}`
`129`	`131`	`return enabledDrivers;`
Original file line number	Diff line number	Diff line change
`@@ -510,19 +510,21 @@ namespace loader`
`510`	`510`	`std::string message = "init driver " + driver.name + " found GPU Supported Driver.";`
`511`	`511`	`debug_trace_message(message, "");`
`512`	`512`	`}`
	`513`	`+ loadDriver = true;`
`513`	`514`	`}`
`514`		`- loadDriver = true;`
`515`	`515`	`}`
`516`	`516`	`if ((!desc && (flags == 0 \|\| flags & ZE_INIT_FLAG_VPU_ONLY)) \|\| (desc && desc->flags & ZE_INIT_DRIVER_TYPE_FLAG_NPU)) {`
`517`	`517`	`if (driver.name.find("vpu") != std::string::npos \|\| driver.name.find("npu") != std::string::npos) {`
`518`	`518`	`if (debugTraceEnabled) {`
`519`	`519`	`std::string message = "init driver " + driver.name + " found VPU/NPU Supported Driver.";`
`520`	`520`	`debug_trace_message(message, "");`
`521`	`521`	`}`
	`522`	`+ loadDriver = true;`
`522`	`523`	`}`
`523`		`- loadDriver = true;`
`524`	`524`	`}`
`525`	`525`
	`526`	`+ loadDriver = !driver.handle && driver.customDriver ? true : loadDriver;`
	`527`	`+`
`526`	`528`	`if (loadDriver && !driver.handle) {`
`527`	`529`	`auto handle = LOAD_DRIVER_LIBRARY( driver.name.c_str() );`
`528`	`530`	`if( NULL != handle )`
`@@ -584,6 +586,14 @@ namespace loader`
`584`	`586`	`driver.ddiInitialized = true;`
`585`	`587`	`}`
`586`	`588`
	`589`	`+ if (!driver.handle && !driver.ddiInitialized) {`
	`590`	`+ if (debugTraceEnabled) {`
	`591`	`+ std::string message = "init driver " + driver.name + " does not match the requested flags or desc, skipping driver.";`
	`592`	`+ debug_trace_message(message, "");`
	`593`	`+ }`
	`594`	`+ return ZE_RESULT_ERROR_UNINITIALIZED;`
	`595`	`+ }`
	`596`	`+`
`587`	`597`	`return ZE_RESULT_SUCCESS;`
`588`	`598`	`}`
`589`	`599`
`@@ -682,14 +692,14 @@ namespace loader`
`682`	`692`	`}`
`683`	`693`	`}`
`684`	`694`
`685`		`- for( auto name : discoveredDrivers )`
	`695`	`+ for( auto driverInfo : discoveredDrivers )`
`686`	`696`	`{`
`687`	`697`	`if (discoveredDrivers.size() == 1) {`
`688`		`- auto handle = LOAD_DRIVER_LIBRARY( name.c_str() );`
	`698`	`+ auto handle = LOAD_DRIVER_LIBRARY( driverInfo.path.c_str() );`
`689`	`699`	`if( NULL != handle )`
`690`	`700`	`{`
`691`	`701`	`if (debugTraceEnabled) {`
`692`		`- std::string message = "Loading Driver " + name + " succeeded";`
	`702`	`+ std::string message = "Loading Driver " + driverInfo.path + " succeeded";`
`693`	`703`	`#if !defined(_WIN32) && !defined(ANDROID)`
`694`	`704`	`// TODO: implement same message for windows, move dlinfo to ze_util.h as a macro`
`695`	`705`	`struct link_map *dlinfo_map;`
`@@ -701,17 +711,19 @@ namespace loader`
`701`	`711`	`}`
`702`	`712`	`allDrivers.emplace_back();`
`703`	`713`	`allDrivers.rbegin()->handle = handle;`
`704`		`- allDrivers.rbegin()->name = name;`
	`714`	`+ allDrivers.rbegin()->name = driverInfo.path;`
	`715`	`+ allDrivers.rbegin()->customDriver = driverInfo.customDriver;`
`705`	`716`	`} else if (debugTraceEnabled) {`
`706`	`717`	`GET_LIBRARY_ERROR(loadLibraryErrorValue);`
`707`		`- std::string errorMessage = "Load Library of " + name + " failed with ";`
	`718`	`+ std::string errorMessage = "Load Library of " + driverInfo.path + " failed with ";`
`708`	`719`	`debug_trace_message(errorMessage, loadLibraryErrorValue);`
`709`	`720`	`loadLibraryErrorValue.clear();`
`710`	`721`	`}`
`711`	`722`	`} else {`
`712`	`723`	`allDrivers.emplace_back();`
`713`	`724`	`allDrivers.rbegin()->handle = nullptr;`
`714`		`- allDrivers.rbegin()->name = name;`
	`725`	`+ allDrivers.rbegin()->name = driverInfo.path;`
	`726`	`+ allDrivers.rbegin()->customDriver = driverInfo.customDriver;`
`715`	`727`	`}`
`716`	`728`	`}`
`717`	`729`	`if(allDrivers.size()==0){`