[UR] Clarify spec around devices created from native handles. (#17910)

Author: aarongreig

unified-runtime/include/ur_api.h

@@ -835,6 +835,8 @@ decl: static
 ordinal: "0"
 details:
     - "Creates runtime device handle from native driver device handle."
+    - "Will always return the same handle in `phDevice` for a given `hNativeDevice`."
+    - "If `hNativeDevice` is a root-level device, the handle returned in `phDevice` will be one of the handles that can be obtained by calling $xDeviceGet with the $X_DEVICE_TYPE_ALL device type."
     - "The application may call this function from simultaneous threads for the same context."
     - "The implementation of this function should be thread-safe."
 params:

unified-runtime/scripts/core/device.yml

@@ -24,6 +24,9 @@ TEST_P(urDeviceCreateWithNativeHandleTest, Success) {
       urDeviceCreateWithNativeHandle(native_handle, adapter, nullptr, &dev));
   ASSERT_NE(dev, nullptr);
 
+  // Based on the spec we can expect these to be equal.
+  ASSERT_EQ(dev, device);
+
   uint32_t dev_id = 0;
   ASSERT_SUCCESS(urDeviceGetInfo(dev, UR_DEVICE_INFO_TYPE, sizeof(uint32_t),
                                  &dev_id, nullptr));
@@ -41,6 +44,7 @@ TEST_P(urDeviceCreateWithNativeHandleTest,
   UUR_ASSERT_SUCCESS_OR_UNSUPPORTED(
       urDeviceCreateWithNativeHandle(native_handle, adapter, &props, &dev));
   ASSERT_NE(dev, nullptr);
+  ASSERT_EQ(dev, device);
 }
 
 TEST_P(urDeviceCreateWithNativeHandleTest, InvalidNullHandlePlatform) {

unified-runtime/source/loader/ur_libapi.cpp

@@ -121,14 +121,7 @@ TEST_P(urQueueGetInfoTest, SuccessRoundtripNullDevice) {
   ASSERT_SUCCESS(urQueueGetInfo(from_native_queue, property_name, property_size,
                                 &property_value, nullptr));
 
-  // We can't assume that the two device handles are equal (since creating the
-  // link to the UR structures has been severed by going through native handle,
-  // so just check the underlying native pointers
-  ur_native_handle_t original_device;
-  ur_native_handle_t new_device;
-  ASSERT_SUCCESS(urDeviceGetNativeHandle(device, &original_device));
-  ASSERT_SUCCESS(urDeviceGetNativeHandle(property_value, &new_device));
-  ASSERT_EQ(original_device, new_device);
+  ASSERT_EQ(property_value, device);
 }
 
 TEST_P(urQueueGetInfoTest, SuccessFlags) {