[SYCL][UR] Include backend name in exception messages (#18889)

kbenzie · web-flow · commit 906f5984a697 · 2025-06-11T10:55:27.000+01:00
To aid with more accurate identification of the source of an error in
the event of a thrown exception, include the backend name in error
messages resulting from calls to Unified Runtime entry points. Here's an
example of the output.

Before:

```
==== DeviceSanitizer: ASAN
terminate called after throwing an instance of 'sycl::_V1::exception'
 what(): UR backend failed. UR backend returns:40 (UR_RESULT_ERROR_OUT_OF_RESOURCES)
```

After:

```
==== DeviceSanitizer: ASAN
terminate called after throwing an instance of 'sycl::_V1::exception'
 what(): level_zero backend failed with error: 40 (UR_RESULT_ERROR_OUT_OF_RESOURCES)
```
diff --git a/sycl/include/sycl/detail/common.hpp b/sycl/include/sycl/detail/common.hpp
@@ -168,11 +168,9 @@ class __SYCL_EXPORT tls_code_loc_t {
 #define __SYCL_ASSERT(x) assert(x)
 #endif // #ifdef __SYCL_DEVICE_ONLY__
 
-#define __SYCL_UR_ERROR_REPORT                                                 \
-  "Native API failed. " /*__FILE__*/                                           \
-  /* TODO: replace __FILE__ to report only relative path*/                     \
-  /* ":" __SYCL_STRINGIFY(__LINE__) ": " */                                    \
-                          "Native API returns: "
+#define __SYCL_UR_ERROR_REPORT(backend)                                        \
+  std::string(sycl::detail::get_backend_name_no_vendor(backend)) +             \
+      " backend failed with error: "
 
 #include <sycl/exception.hpp>
 
diff --git a/sycl/source/detail/adapter.hpp b/sycl/source/detail/adapter.hpp
@@ -10,6 +10,7 @@
 
 #include <detail/config.hpp>
 #include <detail/ur.hpp>
+#include <sycl/backend_types.hpp>
 #include <sycl/detail/common.hpp>
 #include <sycl/detail/iostream_proxy.hpp>
 #include <sycl/detail/type_traits.hpp>
@@ -23,12 +24,12 @@
 #include <memory>
 #include <mutex>
 
-#define __SYCL_CHECK_UR_CODE_NO_EXC(expr)                                      \
+#define __SYCL_CHECK_UR_CODE_NO_EXC(expr, backend)                             \
   {                                                                            \
     auto code = expr;                                                          \
     if (code != UR_RESULT_SUCCESS) {                                           \
-      std::cerr << __SYCL_UR_ERROR_REPORT << sycl::detail::codeToString(code)  \
-                << std::endl;                                                  \
+      std::cerr << __SYCL_UR_ERROR_REPORT(backend)                             \
+                << sycl::detail::codeToString(code) << std::endl;              \
     }                                                                          \
   }
 
@@ -74,7 +75,8 @@ class Adapter {
       throw sycl::detail::set_ur_error(
           sycl::exception(
               sycl::make_error_code(errc),
-              __SYCL_UR_ERROR_REPORT + sycl::detail::codeToString(ur_result) +
+              __SYCL_UR_ERROR_REPORT(MBackend) +
+                  sycl::detail::codeToString(ur_result) +
                   (message ? "\n" + std::string(message) + "(adapter error )" +
                                  std::to_string(adapter_error) + "\n"
                            : std::string{})),
@@ -83,7 +85,7 @@ class Adapter {
     if (ur_result != UR_RESULT_SUCCESS) {
       throw sycl::detail::set_ur_error(
           sycl::exception(sycl::make_error_code(errc),
-                          __SYCL_UR_ERROR_REPORT +
+                          __SYCL_UR_ERROR_REPORT(MBackend) +
                               sycl::detail::codeToString(ur_result)),
           ur_result);
     }
@@ -143,6 +145,9 @@ class Adapter {
     checkUrResult<errc>(Err);
   }
 
+  /// Returns the backend reported by the adapter.
+  backend getBackend() const { return MBackend; }
+
   /// Tells if this adapter can serve specified backend.
   /// For example, Unified Runtime adapter will be able to serve
   /// multiple backends as determined by the platforms reported by the adapter.
diff --git a/sycl/source/detail/device_impl.cpp b/sycl/source/detail/device_impl.cpp
@@ -41,7 +41,7 @@ device_impl::~device_impl() {
     const AdapterPtr &Adapter = getAdapter();
     ur_result_t Err =
         Adapter->call_nocheck<UrApiKind::urDeviceRelease>(MDevice);
-    __SYCL_CHECK_UR_CODE_NO_EXC(Err);
+    __SYCL_CHECK_UR_CODE_NO_EXC(Err, Adapter->getBackend());
   } catch (std::exception &e) {
     __SYCL_REPORT_EXCEPTION_TO_STREAM("exception in ~device_impl", e);
   }
diff --git a/sycl/source/detail/error_handling/error_handling.cpp b/sycl/source/detail/error_handling/error_handling.cpp
@@ -11,6 +11,7 @@
 //===----------------------------------------------------------------------===//
 
 #include "error_handling.hpp"
+#include "sycl/detail/common.hpp"
 
 #include <detail/adapter.hpp>
 #include <sycl/backend_types.hpp>
@@ -69,8 +70,7 @@ void handleOutOfResources(const device_impl &DeviceImpl,
   // Fallback
   constexpr ur_result_t Error = UR_RESULT_ERROR_OUT_OF_RESOURCES;
   throw sycl::exception(sycl::make_error_code(sycl::errc::runtime),
-                        "UR backend failed. UR backend returns:" +
-                            codeToString(Error));
+                        __SYCL_UR_ERROR_REPORT(Backend) + codeToString(Error));
 }
 
 void handleInvalidWorkGroupSize(const device_impl &DeviceImpl,
@@ -459,7 +459,8 @@ void handleErrorOrWarning(ur_result_t Error, const device_impl &DeviceImpl,
   default:
     throw detail::set_ur_error(
         exception(make_error_code(errc::runtime),
-                  "UR error: " + sycl::detail::codeToString(Error)),
+                  __SYCL_UR_ERROR_REPORT(DeviceImpl.getBackend()) +
+                      sycl::detail::codeToString(Error)),
         Error);
   }
 }
diff --git a/sycl/source/detail/kernel_program_cache.hpp b/sycl/source/detail/kernel_program_cache.hpp
@@ -129,7 +129,7 @@ class KernelProgramCache {
             ur_result_t Err =
                 AdapterSharedPtr->call_nocheck<UrApiKind::urProgramRelease>(
                     Val);
-            __SYCL_CHECK_UR_CODE_NO_EXC(Err);
+            __SYCL_CHECK_UR_CODE_NO_EXC(Err, AdapterSharedPtr->getBackend());
           }
         }
       } catch (std::exception &e) {
@@ -214,7 +214,7 @@ class KernelProgramCache {
             ur_result_t Err =
                 AdapterSharedPtr->call_nocheck<UrApiKind::urKernelRelease>(
                     Val.first);
-            __SYCL_CHECK_UR_CODE_NO_EXC(Err);
+            __SYCL_CHECK_UR_CODE_NO_EXC(Err, AdapterSharedPtr->getBackend());
           }
         }
       } catch (std::exception &e) {
diff --git a/sycl/source/detail/queue_impl.hpp b/sycl/source/detail/queue_impl.hpp
@@ -269,7 +269,7 @@ class queue_impl : public std::enable_shared_from_this<queue_impl> {
       // ->call<>() instead of ->call_nocheck<>() above.
       if (status != UR_RESULT_SUCCESS &&
           status != UR_RESULT_ERROR_UNINITIALIZED) {
-        __SYCL_CHECK_UR_CODE_NO_EXC(status);
+        __SYCL_CHECK_UR_CODE_NO_EXC(status, getAdapter()->getBackend());
       }
     } catch (std::exception &e) {
       __SYCL_REPORT_EXCEPTION_TO_STREAM("exception in ~queue_impl", e);
diff --git a/sycl/source/detail/scheduler/scheduler.cpp b/sycl/source/detail/scheduler/scheduler.cpp
@@ -190,10 +190,12 @@ void Scheduler::enqueueCommandForCG(EventImplPtr NewEvent,
             NewCmd, Lock, Res, ToCleanUp, NewCmd, Blocking);
         if (!Enqueued && EnqueueResultT::SyclEnqueueFailed == Res.MResult) {
           throw sycl::detail::set_ur_error(
-              sycl::exception(sycl::make_error_code(errc::runtime),
-                              std::string("Enqueue process failed.\n") +
-                                  __SYCL_UR_ERROR_REPORT +
-                                  sycl::detail::codeToString(Res.MErrCode)),
+              sycl::exception(
+                  sycl::make_error_code(errc::runtime),
+                  std::string("Enqueue process failed.\n") +
+                      __SYCL_UR_ERROR_REPORT(
+                          NewCmd->getWorkerContext()->getBackend()) +
+                      sycl::detail::codeToString(Res.MErrCode)),
               Res.MErrCode);
         }
       } catch (...) {
diff --git a/sycl/source/detail/ur.cpp b/sycl/source/detail/ur.cpp
@@ -119,7 +119,13 @@ std::vector<AdapterPtr> &initializeUr(ur_loader_config_handle_t LoaderConfig) {
 
 static void initializeAdapters(std::vector<AdapterPtr> &Adapters,
                                ur_loader_config_handle_t LoaderConfig) {
-#define CHECK_UR_SUCCESS(Call) __SYCL_CHECK_UR_CODE_NO_EXC(Call)
+#define CHECK_UR_SUCCESS(Call)                                                 \
+  {                                                                            \
+    if (ur_result_t error = Call) {                                            \
+      std::cerr << "UR adapter initialization failed: "                        \
+                << sycl::detail::codeToString(error) << std::endl;             \
+    }                                                                          \
+  }
 
   UrFuncInfo<UrApiKind::urLoaderConfigCreate> loaderConfigCreateInfo;
   auto loaderConfigCreate =
diff --git a/sycl/unittests/xpti_trace/QueueApiFailures.cpp b/sycl/unittests/xpti_trace/QueueApiFailures.cpp
@@ -88,7 +88,7 @@ class QueueApiFailures : public ::testing::Test {
   const std::string TestKernelLocationMessage = BuildCodeLocationMessage(
       TestKI::getFileName(), TestKI::getFunctionName(), TestKI::getLineNumber(),
       TestKI::getColumnNumber());
-  const std::string URLevelFailMessage = "Native API failed";
+  const std::string URLevelFailMessage = " backend failed with error: ";
   const std::string SYCLLevelFailMessage = "Enqueue process failed";
 };
 

Original file line number	Diff line number	Diff line change
`@@ -41,7 +41,7 @@ device_impl::~device_impl() {`
`41`	`41`	`const AdapterPtr &Adapter = getAdapter();`
`42`	`42`	`ur_result_t Err =`
`43`	`43`	`Adapter->call_nocheck<UrApiKind::urDeviceRelease>(MDevice);`
`44`		`- __SYCL_CHECK_UR_CODE_NO_EXC(Err);`
	`44`	`+ __SYCL_CHECK_UR_CODE_NO_EXC(Err, Adapter->getBackend());`
`45`	`45`	`} catch (std::exception &e) {`
`46`	`46`	`__SYCL_REPORT_EXCEPTION_TO_STREAM("exception in ~device_impl", e);`
`47`	`47`	`}`
Original file line number	Diff line number	Diff line change
`@@ -129,7 +129,7 @@ class KernelProgramCache {`
`129`	`129`	`ur_result_t Err =`
`130`	`130`	`AdapterSharedPtr->call_nocheck<UrApiKind::urProgramRelease>(`
`131`	`131`	`Val);`
`132`		`- __SYCL_CHECK_UR_CODE_NO_EXC(Err);`
	`132`	`+ __SYCL_CHECK_UR_CODE_NO_EXC(Err, AdapterSharedPtr->getBackend());`
`133`	`133`	`}`
`134`	`134`	`}`
`135`	`135`	`} catch (std::exception &e) {`
`@@ -214,7 +214,7 @@ class KernelProgramCache {`
`214`	`214`	`ur_result_t Err =`
`215`	`215`	`AdapterSharedPtr->call_nocheck<UrApiKind::urKernelRelease>(`
`216`	`216`	`Val.first);`
`217`		`- __SYCL_CHECK_UR_CODE_NO_EXC(Err);`
	`217`	`+ __SYCL_CHECK_UR_CODE_NO_EXC(Err, AdapterSharedPtr->getBackend());`
`218`	`218`	`}`
`219`	`219`	`}`
`220`	`220`	`} catch (std::exception &e) {`
Original file line number	Diff line number	Diff line change
`@@ -269,7 +269,7 @@ class queue_impl : public std::enable_shared_from_this<queue_impl> {`
`269`	`269`	`// ->call<>() instead of ->call_nocheck<>() above.`
`270`	`270`	`if (status != UR_RESULT_SUCCESS &&`
`271`	`271`	`status != UR_RESULT_ERROR_UNINITIALIZED) {`
`272`		`- __SYCL_CHECK_UR_CODE_NO_EXC(status);`
	`272`	`+ __SYCL_CHECK_UR_CODE_NO_EXC(status, getAdapter()->getBackend());`
`273`	`273`	`}`
`274`	`274`	`} catch (std::exception &e) {`
`275`	`275`	`__SYCL_REPORT_EXCEPTION_TO_STREAM("exception in ~queue_impl", e);`