Make ContextCreateWithNative device list optional and add adapter param.

aarongreig · aarongreig · commit b163c7719015 · 2024-07-23T11:01:32.000+01:00
Also make QueueCreateWithNative device optional.
diff --git a/include/ur_api.h b/include/ur_api.h
@@ -2399,16 +2399,19 @@ typedef struct ur_context_native_properties_t {
 ///     - ::UR_RESULT_ERROR_UNINITIALIZED
 ///     - ::UR_RESULT_ERROR_DEVICE_LOST
 ///     - ::UR_RESULT_ERROR_ADAPTER_SPECIFIC
+///     - ::UR_RESULT_ERROR_INVALID_NULL_HANDLE
+///         + `NULL == hAdapter`
 ///     - ::UR_RESULT_ERROR_INVALID_NULL_POINTER
-///         + `NULL == phDevices`
 ///         + `NULL == phContext`
 ///     - ::UR_RESULT_ERROR_UNSUPPORTED_FEATURE
 ///         + If the adapter has no underlying equivalent handle.
 UR_APIEXPORT ur_result_t UR_APICALL
 urContextCreateWithNativeHandle(
     ur_native_handle_t hNativeContext,                 ///< [in][nocheck] the native handle of the context.
+    ur_adapter_handle_t hAdapter,                      ///< [in] handle of the adapter that owns the native handle
     uint32_t numDevices,                               ///< [in] number of devices associated with the context
-    const ur_device_handle_t *phDevices,               ///< [in][range(0, numDevices)] list of devices associated with the context
+    const ur_device_handle_t *phDevices,               ///< [in][optional][range(0, numDevices)] list of devices associated with
+                                                       ///< the context
     const ur_context_native_properties_t *pProperties, ///< [in][optional] pointer to native context properties struct
     ur_context_handle_t *phContext                     ///< [out] pointer to the handle of the context object created.
 );
@@ -5623,7 +5626,6 @@ typedef struct ur_queue_native_properties_t {
 ///     - ::UR_RESULT_ERROR_ADAPTER_SPECIFIC
 ///     - ::UR_RESULT_ERROR_INVALID_NULL_HANDLE
 ///         + `NULL == hContext`
-///         + `NULL == hDevice`
 ///     - ::UR_RESULT_ERROR_INVALID_NULL_POINTER
 ///         + `NULL == phQueue`
 ///     - ::UR_RESULT_ERROR_UNSUPPORTED_FEATURE
@@ -5632,7 +5634,7 @@ UR_APIEXPORT ur_result_t UR_APICALL
 urQueueCreateWithNativeHandle(
     ur_native_handle_t hNativeQueue,                 ///< [in][nocheck] the native handle of the queue.
     ur_context_handle_t hContext,                    ///< [in] handle of the context object
-    ur_device_handle_t hDevice,                      ///< [in] handle of the device object
+    ur_device_handle_t hDevice,                      ///< [in][optional] handle of the device object
     const ur_queue_native_properties_t *pProperties, ///< [in][optional] pointer to native queue properties struct
     ur_queue_handle_t *phQueue                       ///< [out] pointer to the handle of the queue object created.
 );
@@ -9820,6 +9822,7 @@ typedef struct ur_context_get_native_handle_params_t {
 ///     allowing the callback the ability to modify the parameter's value
 typedef struct ur_context_create_with_native_handle_params_t {
     ur_native_handle_t *phNativeContext;
+    ur_adapter_handle_t *phAdapter;
     uint32_t *pnumDevices;
     const ur_device_handle_t **pphDevices;
     const ur_context_native_properties_t **ppProperties;
diff --git a/include/ur_ddi.h b/include/ur_ddi.h
@@ -135,6 +135,7 @@ typedef ur_result_t(UR_APICALL *ur_pfnContextGetNativeHandle_t)(
 /// @brief Function-pointer for urContextCreateWithNativeHandle
 typedef ur_result_t(UR_APICALL *ur_pfnContextCreateWithNativeHandle_t)(
     ur_native_handle_t,
+    ur_adapter_handle_t,
     uint32_t,
     const ur_device_handle_t *,
     const ur_context_native_properties_t *,
diff --git a/include/ur_print.hpp b/include/ur_print.hpp
@@ -10653,6 +10653,12 @@ inline std::ostream &operator<<(std::ostream &os, [[maybe_unused]] const struct
     ur::details::printPtr(os, reinterpret_cast<void *>(
                                   *(params->phNativeContext)));
 
+    os << ", ";
+    os << ".hAdapter = ";
+
+    ur::details::printPtr(os,
+                          *(params->phAdapter));
+
     os << ", ";
     os << ".numDevices = ";
 
diff --git a/scripts/core/context.yml b/scripts/core/context.yml
@@ -228,12 +228,15 @@ params:
       name: hNativeContext
       desc: |
             [in][nocheck] the native handle of the context.
+    - type: $x_adapter_handle_t
+      name: hAdapter
+      desc: "[in] handle of the adapter that owns the native handle"
     - type: uint32_t
       name: numDevices
       desc: "[in] number of devices associated with the context"
     - type: "const $x_device_handle_t*"
       name: phDevices
-      desc: "[in][range(0, numDevices)] list of devices associated with the context"
+      desc: "[in][optional][range(0, numDevices)] list of devices associated with the context"
     - type: "const $x_context_native_properties_t*"
       name: pProperties
       desc: "[in][optional] pointer to native context properties struct"
diff --git a/scripts/core/queue.yml b/scripts/core/queue.yml
@@ -286,7 +286,7 @@ params:
       desc: "[in] handle of the context object"
     - type: $x_device_handle_t
       name: hDevice
-      desc: "[in] handle of the device object"
+      desc: "[in][optional] handle of the device object"
     - type: "const $x_queue_native_properties_t*"
       name: pProperties
       desc: "[in][optional] pointer to native queue properties struct"
diff --git a/source/adapters/cuda/context.cpp b/source/adapters/cuda/context.cpp
@@ -143,6 +143,7 @@ UR_APIEXPORT ur_result_t UR_APICALL urContextGetNativeHandle(
 
 UR_APIEXPORT ur_result_t UR_APICALL urContextCreateWithNativeHandle(
     [[maybe_unused]] ur_native_handle_t hNativeContext,
+    [[maybe_unused]] ur_adapter_handle_t hAdapter,
     [[maybe_unused]] uint32_t numDevices,
     [[maybe_unused]] const ur_device_handle_t *phDevices,
     [[maybe_unused]] const ur_context_native_properties_t *pProperties,
diff --git a/source/adapters/hip/context.cpp b/source/adapters/hip/context.cpp
@@ -122,6 +122,7 @@ UR_APIEXPORT ur_result_t UR_APICALL urContextGetNativeHandle(
 
 UR_APIEXPORT ur_result_t UR_APICALL urContextCreateWithNativeHandle(
     [[maybe_unused]] ur_native_handle_t hNativeContext,
+    [[maybe_unused]] ur_adapter_handle_t hAdapter,
     [[maybe_unused]] uint32_t numDevices,
     [[maybe_unused]] const ur_device_handle_t *phDevices,
     [[maybe_unused]] const ur_context_native_properties_t *pProperties,
diff --git a/source/adapters/level_zero/context.cpp b/source/adapters/level_zero/context.cpp
@@ -147,7 +147,7 @@ UR_APIEXPORT ur_result_t UR_APICALL urContextGetNativeHandle(
 UR_APIEXPORT ur_result_t UR_APICALL urContextCreateWithNativeHandle(
     ur_native_handle_t
         NativeContext, ///< [in] the native handle of the context.
-    uint32_t NumDevices, const ur_device_handle_t *Devices,
+    ur_adapter_handle_t, uint32_t NumDevices, const ur_device_handle_t *Devices,
     const ur_context_native_properties_t *Properties,
     ur_context_handle_t
         *Context ///< [out] pointer to the handle of the context object created.
diff --git a/source/adapters/mock/ur_mockddi.cpp b/source/adapters/mock/ur_mockddi.cpp
@@ -1264,10 +1264,13 @@ __urdlllocal ur_result_t UR_APICALL urContextGetNativeHandle(
 /// @brief Intercept function for urContextCreateWithNativeHandle
 __urdlllocal ur_result_t UR_APICALL urContextCreateWithNativeHandle(
     ur_native_handle_t
-        hNativeContext,  ///< [in][nocheck] the native handle of the context.
+        hNativeContext, ///< [in][nocheck] the native handle of the context.
+    ur_adapter_handle_t
+        hAdapter, ///< [in] handle of the adapter that owns the native handle
     uint32_t numDevices, ///< [in] number of devices associated with the context
     const ur_device_handle_t *
-        phDevices, ///< [in][range(0, numDevices)] list of devices associated with the context
+        phDevices, ///< [in][optional][range(0, numDevices)] list of devices associated with
+                   ///< the context
     const ur_context_native_properties_t *
         pProperties, ///< [in][optional] pointer to native context properties struct
     ur_context_handle_t *
@@ -1276,7 +1279,8 @@ __urdlllocal ur_result_t UR_APICALL urContextCreateWithNativeHandle(
     ur_result_t result = UR_RESULT_SUCCESS;
 
     ur_context_create_with_native_handle_params_t params = {
-        &hNativeContext, &numDevices, &phDevices, &pProperties, &phContext};
+        &hNativeContext, &hAdapter,    &numDevices,
+        &phDevices,      &pProperties, &phContext};
 
     auto beforeCallback = reinterpret_cast<ur_mock_callback_t>(
         mock::getCallbacks().get_before_callback(
@@ -4841,7 +4845,7 @@ __urdlllocal ur_result_t UR_APICALL urQueueCreateWithNativeHandle(
     ur_native_handle_t
         hNativeQueue, ///< [in][nocheck] the native handle of the queue.
     ur_context_handle_t hContext, ///< [in] handle of the context object
-    ur_device_handle_t hDevice,   ///< [in] handle of the device object
+    ur_device_handle_t hDevice, ///< [in][optional] handle of the device object
     const ur_queue_native_properties_t *
         pProperties, ///< [in][optional] pointer to native queue properties struct
     ur_queue_handle_t
diff --git a/source/adapters/native_cpu/context.cpp b/source/adapters/native_cpu/context.cpp
@@ -79,11 +79,12 @@ UR_APIEXPORT ur_result_t UR_APICALL urContextGetNativeHandle(
 }
 
 UR_APIEXPORT ur_result_t UR_APICALL urContextCreateWithNativeHandle(
-    ur_native_handle_t hNativeContext, uint32_t numDevices,
-    const ur_device_handle_t *phDevices,
+    ur_native_handle_t hNativeContext, ur_adapter_handle_t hAdapter,
+    uint32_t numDevices, const ur_device_handle_t *phDevices,
     const ur_context_native_properties_t *pProperties,
     ur_context_handle_t *phContext) {
   std::ignore = hNativeContext;
+  std::ignore = hAdapter;
   std::ignore = numDevices;
   std::ignore = phDevices;
   std::ignore = pProperties;
diff --git a/source/adapters/opencl/context.cpp b/source/adapters/opencl/context.cpp
@@ -133,7 +133,8 @@ UR_APIEXPORT ur_result_t UR_APICALL urContextGetNativeHandle(
 }
 
 UR_APIEXPORT ur_result_t UR_APICALL urContextCreateWithNativeHandle(
-    ur_native_handle_t hNativeContext, uint32_t, const ur_device_handle_t *,
+    ur_native_handle_t hNativeContext, ur_adapter_handle_t, uint32_t,
+    const ur_device_handle_t *,
     const ur_context_native_properties_t *pProperties,
     ur_context_handle_t *phContext) {
 
diff --git a/source/loader/layers/sanitizer/ur_sanddi.cpp b/source/loader/layers/sanitizer/ur_sanddi.cpp
@@ -335,6 +335,7 @@ __urdlllocal ur_result_t UR_APICALL urContextCreate(
 __urdlllocal ur_result_t UR_APICALL urContextCreateWithNativeHandle(
     ur_native_handle_t
         hNativeContext, ///< [in][nocheck] the native handle of the getContext()->
+    ur_adapter_handle_t hAdapter,
     uint32_t numDevices, ///< [in] number of devices associated with the context
     const ur_device_handle_t *
         phDevices, ///< [in][range(0, numDevices)] list of devices associated with the context
@@ -352,8 +353,9 @@ __urdlllocal ur_result_t UR_APICALL urContextCreateWithNativeHandle(
 
     getContext()->logger.debug("==== urContextCreateWithNativeHandle");
 
-    ur_result_t result = pfnCreateWithNativeHandle(
-        hNativeContext, numDevices, phDevices, pProperties, phContext);
+    ur_result_t result =
+        pfnCreateWithNativeHandle(hNativeContext, hAdapter, numDevices,
+                                  phDevices, pProperties, phContext);
 
     if (result == UR_RESULT_SUCCESS) {
         UR_CALL(setupContext(*phContext, numDevices, phDevices));
diff --git a/source/loader/layers/tracing/ur_trcddi.cpp b/source/loader/layers/tracing/ur_trcddi.cpp
@@ -966,10 +966,13 @@ __urdlllocal ur_result_t UR_APICALL urContextGetNativeHandle(
 /// @brief Intercept function for urContextCreateWithNativeHandle
 __urdlllocal ur_result_t UR_APICALL urContextCreateWithNativeHandle(
     ur_native_handle_t
-        hNativeContext,  ///< [in][nocheck] the native handle of the context.
+        hNativeContext, ///< [in][nocheck] the native handle of the context.
+    ur_adapter_handle_t
+        hAdapter, ///< [in] handle of the adapter that owns the native handle
     uint32_t numDevices, ///< [in] number of devices associated with the context
     const ur_device_handle_t *
-        phDevices, ///< [in][range(0, numDevices)] list of devices associated with the context
+        phDevices, ///< [in][optional][range(0, numDevices)] list of devices associated with
+                   ///< the context
     const ur_context_native_properties_t *
         pProperties, ///< [in][optional] pointer to native context properties struct
     ur_context_handle_t *
@@ -983,15 +986,17 @@ __urdlllocal ur_result_t UR_APICALL urContextCreateWithNativeHandle(
     }
 
     ur_context_create_with_native_handle_params_t params = {
-        &hNativeContext, &numDevices, &phDevices, &pProperties, &phContext};
+        &hNativeContext, &hAdapter,    &numDevices,
+        &phDevices,      &pProperties, &phContext};
     uint64_t instance = getContext()->notify_begin(
         UR_FUNCTION_CONTEXT_CREATE_WITH_NATIVE_HANDLE,
         "urContextCreateWithNativeHandle", &params);
 
     getContext()->logger.info("---> urContextCreateWithNativeHandle");
 
-    ur_result_t result = pfnCreateWithNativeHandle(
-        hNativeContext, numDevices, phDevices, pProperties, phContext);
+    ur_result_t result =
+        pfnCreateWithNativeHandle(hNativeContext, hAdapter, numDevices,
+                                  phDevices, pProperties, phContext);
 
     getContext()->notify_end(UR_FUNCTION_CONTEXT_CREATE_WITH_NATIVE_HANDLE,
                              "urContextCreateWithNativeHandle", &params,
@@ -3695,7 +3700,7 @@ __urdlllocal ur_result_t UR_APICALL urQueueCreateWithNativeHandle(
     ur_native_handle_t
         hNativeQueue, ///< [in][nocheck] the native handle of the queue.
     ur_context_handle_t hContext, ///< [in] handle of the context object
-    ur_device_handle_t hDevice,   ///< [in] handle of the device object
+    ur_device_handle_t hDevice, ///< [in][optional] handle of the device object
     const ur_queue_native_properties_t *
         pProperties, ///< [in][optional] pointer to native queue properties struct
     ur_queue_handle_t
diff --git a/source/loader/layers/validation/ur_valddi.cpp b/source/loader/layers/validation/ur_valddi.cpp
@@ -976,10 +976,13 @@ __urdlllocal ur_result_t UR_APICALL urContextGetNativeHandle(
 /// @brief Intercept function for urContextCreateWithNativeHandle
 __urdlllocal ur_result_t UR_APICALL urContextCreateWithNativeHandle(
     ur_native_handle_t
-        hNativeContext,  ///< [in][nocheck] the native handle of the context.
+        hNativeContext, ///< [in][nocheck] the native handle of the context.
+    ur_adapter_handle_t
+        hAdapter, ///< [in] handle of the adapter that owns the native handle
     uint32_t numDevices, ///< [in] number of devices associated with the context
     const ur_device_handle_t *
-        phDevices, ///< [in][range(0, numDevices)] list of devices associated with the context
+        phDevices, ///< [in][optional][range(0, numDevices)] list of devices associated with
+                   ///< the context
     const ur_context_native_properties_t *
         pProperties, ///< [in][optional] pointer to native context properties struct
     ur_context_handle_t *
@@ -993,17 +996,23 @@ __urdlllocal ur_result_t UR_APICALL urContextCreateWithNativeHandle(
     }
 
     if (getContext()->enableParameterValidation) {
-        if (NULL == phDevices) {
-            return UR_RESULT_ERROR_INVALID_NULL_POINTER;
+        if (NULL == hAdapter) {
+            return UR_RESULT_ERROR_INVALID_NULL_HANDLE;
         }
 
         if (NULL == phContext) {
             return UR_RESULT_ERROR_INVALID_NULL_POINTER;
         }
     }
 
-    ur_result_t result = pfnCreateWithNativeHandle(
-        hNativeContext, numDevices, phDevices, pProperties, phContext);
+    if (getContext()->enableLifetimeValidation &&
+        !getContext()->refCountContext->isReferenceValid(hAdapter)) {
+        getContext()->refCountContext->logInvalidReference(hAdapter);
+    }
+
+    ur_result_t result =
+        pfnCreateWithNativeHandle(hNativeContext, hAdapter, numDevices,
+                                  phDevices, pProperties, phContext);
 
     if (getContext()->enableLeakChecking && result == UR_RESULT_SUCCESS) {
         getContext()->refCountContext->createRefCount(*phContext);
@@ -4179,7 +4188,7 @@ __urdlllocal ur_result_t UR_APICALL urQueueCreateWithNativeHandle(
     ur_native_handle_t
         hNativeQueue, ///< [in][nocheck] the native handle of the queue.
     ur_context_handle_t hContext, ///< [in] handle of the context object
-    ur_device_handle_t hDevice,   ///< [in] handle of the device object
+    ur_device_handle_t hDevice, ///< [in][optional] handle of the device object
     const ur_queue_native_properties_t *
         pProperties, ///< [in][optional] pointer to native queue properties struct
     ur_queue_handle_t
@@ -4197,10 +4206,6 @@ __urdlllocal ur_result_t UR_APICALL urQueueCreateWithNativeHandle(
             return UR_RESULT_ERROR_INVALID_NULL_HANDLE;
         }
 
-        if (NULL == hDevice) {
-            return UR_RESULT_ERROR_INVALID_NULL_HANDLE;
-        }
-
         if (NULL == phQueue) {
             return UR_RESULT_ERROR_INVALID_NULL_POINTER;
         }
diff --git a/source/loader/ur_ldrddi.cpp b/source/loader/ur_ldrddi.cpp
@@ -1044,10 +1044,13 @@ __urdlllocal ur_result_t UR_APICALL urContextGetNativeHandle(
 /// @brief Intercept function for urContextCreateWithNativeHandle
 __urdlllocal ur_result_t UR_APICALL urContextCreateWithNativeHandle(
     ur_native_handle_t
-        hNativeContext,  ///< [in][nocheck] the native handle of the context.
+        hNativeContext, ///< [in][nocheck] the native handle of the context.
+    ur_adapter_handle_t
+        hAdapter, ///< [in] handle of the adapter that owns the native handle
     uint32_t numDevices, ///< [in] number of devices associated with the context
     const ur_device_handle_t *
-        phDevices, ///< [in][range(0, numDevices)] list of devices associated with the context
+        phDevices, ///< [in][optional][range(0, numDevices)] list of devices associated with
+                   ///< the context
     const ur_context_native_properties_t *
         pProperties, ///< [in][optional] pointer to native context properties struct
     ur_context_handle_t *
@@ -1058,14 +1061,16 @@ __urdlllocal ur_result_t UR_APICALL urContextCreateWithNativeHandle(
     [[maybe_unused]] auto context = getContext();
 
     // extract platform's function pointer table
-    auto dditable =
-        reinterpret_cast<ur_device_object_t *>(*phDevices)->dditable;
+    auto dditable = reinterpret_cast<ur_adapter_object_t *>(hAdapter)->dditable;
     auto pfnCreateWithNativeHandle =
         dditable->ur.Context.pfnCreateWithNativeHandle;
     if (nullptr == pfnCreateWithNativeHandle) {
         return UR_RESULT_ERROR_UNINITIALIZED;
     }
 
+    // convert loader handle to platform handle
+    hAdapter = reinterpret_cast<ur_adapter_object_t *>(hAdapter)->handle;
+
     // convert loader handles to platform handles
     auto phDevicesLocal = std::vector<ur_device_handle_t>(numDevices);
     for (size_t i = 0; i < numDevices; ++i) {
@@ -1074,7 +1079,7 @@ __urdlllocal ur_result_t UR_APICALL urContextCreateWithNativeHandle(
     }
 
     // forward to device-platform
-    result = pfnCreateWithNativeHandle(hNativeContext, numDevices,
+    result = pfnCreateWithNativeHandle(hNativeContext, hAdapter, numDevices,
                                        phDevicesLocal.data(), pProperties,
                                        phContext);
 
@@ -3908,7 +3913,7 @@ __urdlllocal ur_result_t UR_APICALL urQueueCreateWithNativeHandle(
     ur_native_handle_t
         hNativeQueue, ///< [in][nocheck] the native handle of the queue.
     ur_context_handle_t hContext, ///< [in] handle of the context object
-    ur_device_handle_t hDevice,   ///< [in] handle of the device object
+    ur_device_handle_t hDevice, ///< [in][optional] handle of the device object
     const ur_queue_native_properties_t *
         pProperties, ///< [in][optional] pointer to native queue properties struct
     ur_queue_handle_t
@@ -3930,7 +3935,9 @@ __urdlllocal ur_result_t UR_APICALL urQueueCreateWithNativeHandle(
     hContext = reinterpret_cast<ur_context_object_t *>(hContext)->handle;
 
     // convert loader handle to platform handle
-    hDevice = reinterpret_cast<ur_device_object_t *>(hDevice)->handle;
+    hDevice = (hDevice)
+                  ? reinterpret_cast<ur_device_object_t *>(hDevice)->handle
+                  : nullptr;
 
     // forward to device-platform
     result = pfnCreateWithNativeHandle(hNativeQueue, hContext, hDevice,
diff --git a/source/loader/ur_libapi.cpp b/source/loader/ur_libapi.cpp
diff --git a/source/ur_api.cpp b/source/ur_api.cpp
diff --git a/test/conformance/context/context_adapter_native_cpu.match b/test/conformance/context/context_adapter_native_cpu.match
diff --git a/test/conformance/context/urContextCreateWithNativeHandle.cpp b/test/conformance/context/urContextCreateWithNativeHandle.cpp
diff --git a/test/conformance/source/environment.cpp b/test/conformance/source/environment.cpp
diff --git a/test/conformance/testing/include/uur/environment.h b/test/conformance/testing/include/uur/environment.h
diff --git a/test/conformance/testing/include/uur/fixtures.h b/test/conformance/testing/include/uur/fixtures.h
