Change urDeviceCreateWithNativeHandle to take an adapter handle.

It currently takes a platform handle, which is problematic for the sycl
RT because its make_device api only takes a native handle, so to figure
out the correct platform handle to pass at best we'd need to do some
backend specific querying of the native object, but even then that isn't
always possible as not all backends have a platform equivalent.

The platform handle does currently enable an optional (slightly) faster
path to return the correct device in some adapter implementations but
this isn't essential for them to work, so really its primary purpose is
to serve as the wrapped UR handle for the loader to work. This purpose
is equally well served by an adapter handle, which will also be a lot
easier for the sycl rt to correctly provide.

Author: aarongreig

include/ur_api.h

@@ -2062,15 +2062,15 @@ typedef struct ur_device_native_properties_t {
 ///     - ::UR_RESULT_ERROR_DEVICE_LOST
 ///     - ::UR_RESULT_ERROR_ADAPTER_SPECIFIC
 ///     - ::UR_RESULT_ERROR_INVALID_NULL_HANDLE
-///         + `NULL == hPlatform`
+///         + `NULL == hAdapter`
 ///     - ::UR_RESULT_ERROR_INVALID_NULL_POINTER
 ///         + `NULL == phDevice`
 ///     - ::UR_RESULT_ERROR_UNSUPPORTED_FEATURE
 ///         + If the adapter has no underlying equivalent handle.
 UR_APIEXPORT ur_result_t UR_APICALL
 urDeviceCreateWithNativeHandle(
     ur_native_handle_t hNativeDevice,                 ///< [in][nocheck] the native handle of the device.
-    ur_platform_handle_t hPlatform,                   ///< [in] handle of the platform instance
+    ur_adapter_handle_t hAdapter,                     ///< [in] handle of the adapter to which `hNativeDevice` belongs
     const ur_device_native_properties_t *pProperties, ///< [in][optional] pointer to native device properties struct.
     ur_device_handle_t *phDevice                      ///< [out] pointer to the handle of the device object created.
 );
@@ -11972,7 +11972,7 @@ typedef struct ur_device_get_native_handle_params_t {
 ///     allowing the callback the ability to modify the parameter's value
 typedef struct ur_device_create_with_native_handle_params_t {
     ur_native_handle_t *phNativeDevice;
-    ur_platform_handle_t *phPlatform;
+    ur_adapter_handle_t *phAdapter;
     const ur_device_native_properties_t **ppProperties;
     ur_device_handle_t **pphDevice;
 } ur_device_create_with_native_handle_params_t;

include/ur_ddi.h

@@ -2373,7 +2373,7 @@ typedef ur_result_t(UR_APICALL *ur_pfnDeviceGetNativeHandle_t)(
 /// @brief Function-pointer for urDeviceCreateWithNativeHandle
 typedef ur_result_t(UR_APICALL *ur_pfnDeviceCreateWithNativeHandle_t)(
     ur_native_handle_t,
-    ur_platform_handle_t,
+    ur_adapter_handle_t,
     const ur_device_native_properties_t *,
     ur_device_handle_t *);
 

include/ur_print.hpp

@@ -17357,10 +17357,10 @@ inline std::ostream &operator<<(std::ostream &os, [[maybe_unused]] const struct
                                   *(params->phNativeDevice)));
 
     os << ", ";
-    os << ".hPlatform = ";
+    os << ".hAdapter = ";
 
     ur::details::printPtr(os,
-                          *(params->phPlatform));
+                          *(params->phAdapter));
 
     os << ", ";
     os << ".pProperties = ";

scripts/core/device.yml

@@ -820,9 +820,9 @@ params:
     - type: $x_native_handle_t
       name: hNativeDevice
       desc: "[in][nocheck] the native handle of the device."
-    - type: $x_platform_handle_t
-      name: hPlatform
-      desc: "[in] handle of the platform instance"
+    - type: $x_adapter_handle_t
+      name: hAdapter
+      desc: "[in] handle of the adapter to which `hNativeDevice` belongs"
     - type: const $x_device_native_properties_t*
       name: pProperties
       desc: "[in][optional] pointer to native device properties struct."

source/adapters/cuda/device.cpp

@@ -1185,27 +1185,16 @@ UR_APIEXPORT ur_result_t UR_APICALL urDeviceGetNativeHandle(
 /// \return TBD
 
 UR_APIEXPORT ur_result_t UR_APICALL urDeviceCreateWithNativeHandle(
-    ur_native_handle_t hNativeDevice, ur_platform_handle_t hPlatform,
-    const ur_device_native_properties_t *pProperties,
+    ur_native_handle_t hNativeDevice,
+    [[maybe_unused]] ur_adapter_handle_t hAdapter,
+    [[maybe_unused]] const ur_device_native_properties_t *pProperties,
     ur_device_handle_t *phDevice) {
-  std::ignore = pProperties;
-
   CUdevice CuDevice = static_cast<CUdevice>(hNativeDevice);
 
   auto IsDevice = [=](std::unique_ptr<ur_device_handle_t_> &Dev) {
     return Dev->get() == CuDevice;
   };
 
-  // If a platform is provided just check if the device is in it
-  if (hPlatform) {
-    auto SearchRes = std::find_if(begin(hPlatform->Devices),
-                                  end(hPlatform->Devices), IsDevice);
-    if (SearchRes != end(hPlatform->Devices)) {
-      *phDevice = SearchRes->get();
-      return UR_RESULT_SUCCESS;
-    }
-  }
-
   // Get list of platforms
   uint32_t NumPlatforms = 0;
   ur_adapter_handle_t AdapterHandle = &adapter;

source/adapters/hip/device.cpp

@@ -988,7 +988,8 @@ UR_APIEXPORT ur_result_t UR_APICALL urDeviceGetNativeHandle(
 }
 
 UR_APIEXPORT ur_result_t UR_APICALL urDeviceCreateWithNativeHandle(
-    ur_native_handle_t hNativeDevice, ur_platform_handle_t hPlatform,
+    ur_native_handle_t hNativeDevice,
+    [[maybe_unused]] ur_adapter_handle_t hAdapter,
     [[maybe_unused]] const ur_device_native_properties_t *pProperties,
     ur_device_handle_t *phDevice) {
   // We can't cast between ur_native_handle_t and hipDevice_t, so memcpy the
@@ -1000,16 +1001,6 @@ UR_APIEXPORT ur_result_t UR_APICALL urDeviceCreateWithNativeHandle(
     return Dev->get() == HIPDevice;
   };
 
-  // If a platform is provided just check if the device is in it
-  if (hPlatform) {
-    auto SearchRes = std::find_if(begin(hPlatform->Devices),
-                                  end(hPlatform->Devices), IsDevice);
-    if (SearchRes != end(hPlatform->Devices)) {
-      *phDevice = SearchRes->get();
-      return UR_RESULT_SUCCESS;
-    }
-  }
-
   // Get list of platforms
   uint32_t NumPlatforms = 0;
   ur_adapter_handle_t AdapterHandle = &adapter;

source/adapters/level_zero/device.cpp

@@ -1602,14 +1602,14 @@ UR_APIEXPORT ur_result_t UR_APICALL urDeviceGetNativeHandle(
 
 UR_APIEXPORT ur_result_t UR_APICALL urDeviceCreateWithNativeHandle(
     ur_native_handle_t NativeDevice, ///< [in] the native handle of the device.
-    ur_platform_handle_t Platform,   ///< [in] handle of the platform instance
-    const ur_device_native_properties_t
+    [[maybe_unused]] ur_adapter_handle_t
+        Adapter, ///< [in] handle of the platform instance
+    [[maybe_unused]] const ur_device_native_properties_t
         *Properties, ///< [in][optional] pointer to native device properties
                      ///< struct.
     ur_device_handle_t
         *Device ///< [out] pointer to the handle of the device object created.
 ) {
-  std::ignore = Properties;
   auto ZeDevice = ur_cast<ze_device_handle_t>(NativeDevice);
 
   // The SYCL spec requires that the set of devices must remain fixed for the
@@ -1622,12 +1622,6 @@ UR_APIEXPORT ur_result_t UR_APICALL urDeviceCreateWithNativeHandle(
   if (const auto *platforms = GlobalAdapter->PlatformCache->get_value()) {
     for (const auto &p : *platforms) {
       Dev = p->getDeviceFromNativeHandle(ZeDevice);
-      if (Dev) {
-        // Check that the input Platform, if was given, matches the found one.
-        UR_ASSERT(!Platform || Platform == p.get(),
-                  UR_RESULT_ERROR_INVALID_PLATFORM);
-        break;
-      }
     }
   } else {
     return GlobalAdapter->PlatformCache->get_error();

source/adapters/mock/ur_mockddi.cpp

@@ -921,7 +921,8 @@ __urdlllocal ur_result_t UR_APICALL urDeviceGetNativeHandle(
 __urdlllocal ur_result_t UR_APICALL urDeviceCreateWithNativeHandle(
     ur_native_handle_t
         hNativeDevice, ///< [in][nocheck] the native handle of the device.
-    ur_platform_handle_t hPlatform, ///< [in] handle of the platform instance
+    ur_adapter_handle_t
+        hAdapter, ///< [in] handle of the adapter to which `hNativeDevice` belongs
     const ur_device_native_properties_t *
         pProperties, ///< [in][optional] pointer to native device properties struct.
     ur_device_handle_t
@@ -930,7 +931,7 @@ __urdlllocal ur_result_t UR_APICALL urDeviceCreateWithNativeHandle(
     ur_result_t result = UR_RESULT_SUCCESS;
 
     ur_device_create_with_native_handle_params_t params = {
-        &hNativeDevice, &hPlatform, &pProperties, &phDevice};
+        &hNativeDevice, &hAdapter, &pProperties, &phDevice};
 
     auto beforeCallback = reinterpret_cast<ur_mock_callback_t>(
         mock::getCallbacks().get_before_callback(

source/adapters/native_cpu/device.cpp

@@ -366,11 +366,11 @@ UR_APIEXPORT ur_result_t UR_APICALL urDeviceGetNativeHandle(
 }
 
 UR_APIEXPORT ur_result_t UR_APICALL urDeviceCreateWithNativeHandle(
-    ur_native_handle_t hNativeDevice, ur_platform_handle_t hPlatform,
+    ur_native_handle_t hNativeDevice, ur_adapter_handle_t hAdapter,
     const ur_device_native_properties_t *pProperties,
     ur_device_handle_t *phDevice) {
   std::ignore = hNativeDevice;
-  std::ignore = hPlatform;
+  std::ignore = hAdapter;
   std::ignore = pProperties;
   std::ignore = phDevice;
 

source/adapters/opencl/device.cpp

@@ -1125,7 +1125,7 @@ UR_APIEXPORT ur_result_t UR_APICALL urDeviceGetNativeHandle(
 }
 
 UR_APIEXPORT ur_result_t UR_APICALL urDeviceCreateWithNativeHandle(
-    ur_native_handle_t hNativeDevice, ur_platform_handle_t,
+    ur_native_handle_t hNativeDevice, ur_adapter_handle_t,
     const ur_device_native_properties_t *, ur_device_handle_t *phDevice) {
 
   *phDevice = reinterpret_cast<ur_device_handle_t>(hNativeDevice);