Expand urContextGetNativeHandle

include/ur.py

@@ -215,6 +215,7 @@ class ur_structure_type_v(IntEnum):
     SAMPLER_DESC = 13                               ## ::ur_sampler_desc_t
     QUEUE_PROPERTIES = 14                           ## ::ur_queue_properties_t
     QUEUE_INDEX_PROPERTIES = 15                     ## ::ur_queue_properties_t
+    CONTEXT_NATIVE_PROPERTIES = 16                  ## ::ur_context_native_properties_t
 
 class ur_structure_type_t(c_int):
     def __str__(self):
@@ -706,6 +707,18 @@ def __str__(self):
         return str(ur_context_info_v(self.value))
 
 
+###############################################################################
+## @brief Properties for for ::urContextCreateWithNativeHandle.
+class ur_context_native_properties_t(Structure):
+    _fields_ = [
+        ("stype", ur_structure_type_t),                                 ## [in] type of this structure, must be
+                                                                        ## ::UR_STRUCTURE_TYPE_CONTEXT_NATIVE_PROPERTIES
+        ("pNext", c_void_p),                                            ## [in,out][optional] pointer to extension-specific structure
+        ("isNativeHandleOwned", c_bool)                                 ## [in] Indicates UR owns the native handle or if it came from an interoperability
+                                                                        ## operation in the application that asked to not transfer the ownership to
+                                                                        ## the unified-runtime.
+    ]
+
 ###############################################################################
 ## @brief Context's extended deleter callback function with user data.
 def ur_context_extended_deleter_t(user_defined_callback):
@@ -1715,9 +1728,9 @@ class ur_platform_dditable_t(Structure):
 ###############################################################################
 ## @brief Function-pointer for urContextCreateWithNativeHandle
 if __use_win_types:
-    _urContextCreateWithNativeHandle_t = WINFUNCTYPE( ur_result_t, ur_native_handle_t, POINTER(ur_context_handle_t) )
+    _urContextCreateWithNativeHandle_t = WINFUNCTYPE( ur_result_t, ur_native_handle_t, c_ulong, POINTER(ur_device_handle_t), POINTER(ur_context_native_properties_t), POINTER(ur_context_handle_t) )
 else:
-    _urContextCreateWithNativeHandle_t = CFUNCTYPE( ur_result_t, ur_native_handle_t, POINTER(ur_context_handle_t) )
+    _urContextCreateWithNativeHandle_t = CFUNCTYPE( ur_result_t, ur_native_handle_t, c_ulong, POINTER(ur_device_handle_t), POINTER(ur_context_native_properties_t), POINTER(ur_context_handle_t) )
 
 ###############################################################################
 ## @brief Function-pointer for urContextSetExtendedDeleter

include/ur_api.h

@@ -239,6 +239,7 @@ typedef enum ur_structure_type_t {
     UR_STRUCTURE_TYPE_SAMPLER_DESC = 13,                    ///< ::ur_sampler_desc_t
     UR_STRUCTURE_TYPE_QUEUE_PROPERTIES = 14,                ///< ::ur_queue_properties_t
     UR_STRUCTURE_TYPE_QUEUE_INDEX_PROPERTIES = 15,          ///< ::ur_queue_properties_t
+    UR_STRUCTURE_TYPE_CONTEXT_NATIVE_PROPERTIES = 16,       ///< ::ur_context_native_properties_t
     /// @cond
     UR_STRUCTURE_TYPE_FORCE_UINT32 = 0x7fffffff
     /// @endcond
@@ -1456,6 +1457,18 @@ urContextGetNativeHandle(
     ur_native_handle_t *phNativeContext ///< [out] a pointer to the native handle of the context.
 );
 
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Properties for for ::urContextCreateWithNativeHandle.
+typedef struct ur_context_native_properties_t {
+    ur_structure_type_t stype; ///< [in] type of this structure, must be
+                               ///< ::UR_STRUCTURE_TYPE_CONTEXT_NATIVE_PROPERTIES
+    void *pNext;               ///< [in,out][optional] pointer to extension-specific structure
+    bool isNativeHandleOwned;  ///< [in] Indicates UR owns the native handle or if it came from an interoperability
+                               ///< operation in the application that asked to not transfer the ownership to
+                               ///< the unified-runtime.
+
+} ur_context_native_properties_t;
+
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Create runtime context object from native context handle.
 ///
@@ -1472,11 +1485,16 @@ urContextGetNativeHandle(
 ///     - ::UR_RESULT_ERROR_INVALID_NULL_HANDLE
 ///         + `NULL == hNativeContext`
 ///     - ::UR_RESULT_ERROR_INVALID_NULL_POINTER
+///         + `NULL == phDevices`
+///         + `NULL == pProperties`
 ///         + `NULL == phContext`
 UR_APIEXPORT ur_result_t UR_APICALL
 urContextCreateWithNativeHandle(
-    ur_native_handle_t hNativeContext, ///< [in] the native handle of the context.
-    ur_context_handle_t *phContext     ///< [out] pointer to the handle of the context object created.
+    ur_native_handle_t hNativeContext,                 ///< [in] the native handle of the context.
+    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_context_native_properties_t *pProperties, ///< [in] pointer to properties struct
+    ur_context_handle_t *phContext                     ///< [out] pointer to the handle of the context object created.
 );
 
 ///////////////////////////////////////////////////////////////////////////////
@@ -5732,6 +5750,9 @@ typedef void(UR_APICALL *ur_pfnContextGetNativeHandleCb_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;
+    uint32_t *pnumDevices;
+    const ur_device_handle_t **pphDevices;
+    const ur_context_native_properties_t **ppProperties;
     ur_context_handle_t **pphContext;
 } ur_context_create_with_native_handle_params_t;
 

include/ur_ddi.h

@@ -129,6 +129,9 @@ 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,
+    uint32_t,
+    const ur_device_handle_t *,
+    const ur_context_native_properties_t *,
     ur_context_handle_t *);
 
 ///////////////////////////////////////////////////////////////////////////////

scripts/core/common.yml

@@ -294,6 +294,8 @@ etors:
       desc: $x_queue_properties_t
     - name: QUEUE_INDEX_PROPERTIES
       desc: $x_queue_properties_t
+    - name: CONTEXT_NATIVE_PROPERTIES
+      desc: $x_context_native_properties_t
 --- #--------------------------------------------------------------------------
 type: struct
 desc: "Base for all properties types"

scripts/core/context.yml

@@ -183,6 +183,19 @@ params:
       desc: |
             [out] a pointer to the native handle of the context.
 --- #--------------------------------------------------------------------------
+type: struct
+desc: "Properties for for $xContextCreateWithNativeHandle."
+class: $xContext
+name: $x_context_native_properties_t
+base: $x_base_properties_t
+members:
+    - type: bool
+      name: isNativeHandleOwned
+      desc: |
+            [in] Indicates UR owns the native handle or if it came from an interoperability
+            operation in the application that asked to not transfer the ownership to
+            the unified-runtime.
+--- #--------------------------------------------------------------------------
 type: function
 desc: "Create runtime context object from native context handle."
 class: $xContext
@@ -198,6 +211,15 @@ params:
       name: hNativeContext
       desc: |
             [in] the native handle of the context.
+    - 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"
+    - type: "const $x_context_native_properties_t*"
+      name: pProperties
+      desc: "[in] pointer to properties struct"
     - type: "$x_context_handle_t*"
       name: phContext
       desc: |

source/common/ur_params.hpp

@@ -156,6 +156,9 @@ inline std::ostream &operator<<(std::ostream &os, enum ur_context_flag_t value);
 inline std::ostream &operator<<(std::ostream &os,
                                 const struct ur_context_properties_t params);
 inline std::ostream &operator<<(std::ostream &os, enum ur_context_info_t value);
+inline std::ostream &
+operator<<(std::ostream &os,
+           const struct ur_context_native_properties_t params);
 inline std::ostream &operator<<(std::ostream &os, enum ur_mem_flag_t value);
 inline std::ostream &operator<<(std::ostream &os, enum ur_mem_type_t value);
 inline std::ostream &operator<<(std::ostream &os, enum ur_mem_info_t value);
@@ -605,6 +608,10 @@ inline std::ostream &operator<<(std::ostream &os,
     case UR_STRUCTURE_TYPE_QUEUE_INDEX_PROPERTIES:
         os << "UR_STRUCTURE_TYPE_QUEUE_INDEX_PROPERTIES";
         break;
+
+    case UR_STRUCTURE_TYPE_CONTEXT_NATIVE_PROPERTIES:
+        os << "UR_STRUCTURE_TYPE_CONTEXT_NATIVE_PROPERTIES";
+        break;
     default:
         os << "unknown enumerator";
         break;
@@ -708,6 +715,12 @@ inline void serializeStruct(std::ostream &os, const void *ptr) {
             (const ur_queue_properties_t *)ptr;
         ur_params::serializePtr(os, pstruct);
     } break;
+
+    case UR_STRUCTURE_TYPE_CONTEXT_NATIVE_PROPERTIES: {
+        const ur_context_native_properties_t *pstruct =
+            (const ur_context_native_properties_t *)ptr;
+        ur_params::serializePtr(os, pstruct);
+    } break;
     default:
         os << "unknown enumerator";
         break;
@@ -3747,6 +3760,28 @@ inline void serializeTaggedTyped_ur_context_info_t(std::ostream &os,
     }
 }
 } // namespace ur_params
+inline std::ostream &
+operator<<(std::ostream &os,
+           const struct ur_context_native_properties_t params) {
+    os << "(struct ur_context_native_properties_t){";
+
+    os << ".stype = ";
+
+    os << (params.stype);
+
+    os << ", ";
+    os << ".pNext = ";
+
+    ur_params::serializeStruct(os, (params.pNext));
+
+    os << ", ";
+    os << ".isNativeHandleOwned = ";
+
+    os << (params.isNativeHandleOwned);
+
+    os << "}";
+    return os;
+}
 inline std::ostream &operator<<(std::ostream &os, enum ur_mem_flag_t value) {
     switch (value) {
 
@@ -7515,6 +7550,28 @@ operator<<(std::ostream &os,
 
     ur_params::serializePtr(os, *(params->phNativeContext));
 
+    os << ", ";
+    os << ".numDevices = ";
+
+    os << *(params->pnumDevices);
+
+    os << ", ";
+    os << ".phDevices = [";
+    for (size_t i = 0;
+         *(params->pphDevices) != NULL && i < *params->pnumDevices; ++i) {
+        if (i != 0) {
+            os << ", ";
+        }
+
+        ur_params::serializePtr(os, (*(params->pphDevices))[i]);
+    }
+    os << "]";
+
+    os << ", ";
+    os << ".pProperties = ";
+
+    ur_params::serializePtr(os, *(params->ppProperties));
+
     os << ", ";
     os << ".phContext = ";
 

source/drivers/null/ur_nullddi.cpp

@@ -570,7 +570,12 @@ __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] the native handle of the context.
+        hNativeContext,  ///< [in] the native handle of the context.
+    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_context_native_properties_t
+        *pProperties, ///< [in] pointer to properties struct
     ur_context_handle_t *
         phContext ///< [out] pointer to the handle of the context object created.
 ) {
@@ -580,7 +585,8 @@ __urdlllocal ur_result_t UR_APICALL urContextCreateWithNativeHandle(
     auto pfnCreateWithNativeHandle =
         d_context.urDdiTable.Context.pfnCreateWithNativeHandle;
     if (nullptr != pfnCreateWithNativeHandle) {
-        result = pfnCreateWithNativeHandle(hNativeContext, phContext);
+        result = pfnCreateWithNativeHandle(hNativeContext, numDevices,
+                                           phDevices, pProperties, phContext);
     } else {
         // generic implementation
         *phContext = reinterpret_cast<ur_context_handle_t>(d_context.get());

source/loader/layers/tracing/ur_trcddi.cpp

@@ -694,7 +694,12 @@ __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] the native handle of the context.
+        hNativeContext,  ///< [in] the native handle of the context.
+    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_context_native_properties_t
+        *pProperties, ///< [in] pointer to properties struct
     ur_context_handle_t *
         phContext ///< [out] pointer to the handle of the context object created.
 ) {
@@ -705,13 +710,14 @@ __urdlllocal ur_result_t UR_APICALL urContextCreateWithNativeHandle(
         return UR_RESULT_ERROR_UNSUPPORTED_FEATURE;
     }
 
-    ur_context_create_with_native_handle_params_t params = {&hNativeContext,
-                                                            &phContext};
+    ur_context_create_with_native_handle_params_t params = {
+        &hNativeContext, &numDevices, &phDevices, &pProperties, &phContext};
     uint64_t instance =
         context.notify_begin(UR_FUNCTION_CONTEXT_CREATE_WITH_NATIVE_HANDLE,
                              "urContextCreateWithNativeHandle", &params);
 
-    ur_result_t result = pfnCreateWithNativeHandle(hNativeContext, phContext);
+    ur_result_t result = pfnCreateWithNativeHandle(
+        hNativeContext, numDevices, phDevices, pProperties, phContext);
 
     context.notify_end(UR_FUNCTION_CONTEXT_CREATE_WITH_NATIVE_HANDLE,
                        "urContextCreateWithNativeHandle", &params, &result,

source/loader/layers/validation/ur_valddi.cpp

@@ -747,7 +747,12 @@ __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] the native handle of the context.
+        hNativeContext,  ///< [in] the native handle of the context.
+    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_context_native_properties_t
+        *pProperties, ///< [in] pointer to properties struct
     ur_context_handle_t *
         phContext ///< [out] pointer to the handle of the context object created.
 ) {
@@ -763,12 +768,21 @@ __urdlllocal ur_result_t UR_APICALL urContextCreateWithNativeHandle(
             return UR_RESULT_ERROR_INVALID_NULL_HANDLE;
         }
 
+        if (NULL == phDevices) {
+            return UR_RESULT_ERROR_INVALID_NULL_POINTER;
+        }
+
+        if (NULL == pProperties) {
+            return UR_RESULT_ERROR_INVALID_NULL_POINTER;
+        }
+
         if (NULL == phContext) {
             return UR_RESULT_ERROR_INVALID_NULL_POINTER;
         }
     }
 
-    ur_result_t result = pfnCreateWithNativeHandle(hNativeContext, phContext);
+    ur_result_t result = pfnCreateWithNativeHandle(
+        hNativeContext, numDevices, phDevices, pProperties, phContext);
 
     if (context.enableLeakChecking && result == UR_RESULT_SUCCESS) {
         refCountContext.createRefCount(*phContext);

source/loader/ur_ldrddi.cpp

@@ -821,7 +821,12 @@ __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] the native handle of the context.
+        hNativeContext,  ///< [in] the native handle of the context.
+    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_context_native_properties_t
+        *pProperties, ///< [in] pointer to properties struct
     ur_context_handle_t *
         phContext ///< [out] pointer to the handle of the context object created.
 ) {
@@ -840,8 +845,17 @@ __urdlllocal ur_result_t UR_APICALL urContextCreateWithNativeHandle(
     hNativeContext =
         reinterpret_cast<ur_native_object_t *>(hNativeContext)->handle;
 
+    // convert loader handles to platform handles
+    auto phDevicesLocal = new ur_device_handle_t[numDevices];
+    for (size_t i = 0; (nullptr != phDevices) && (i < numDevices); ++i) {
+        phDevicesLocal[i] =
+            reinterpret_cast<ur_device_object_t *>(phDevices[i])->handle;
+    }
+
     // forward to device-platform
-    result = pfnCreateWithNativeHandle(hNativeContext, phContext);
+    result = pfnCreateWithNativeHandle(hNativeContext, numDevices, phDevices,
+                                       pProperties, phContext);
+    delete[] phDevicesLocal;
 
     if (UR_RESULT_SUCCESS != result) {
         return result;

source/loader/ur_libapi.cpp

@@ -881,10 +881,17 @@ ur_result_t UR_APICALL urContextGetNativeHandle(
 ///     - ::UR_RESULT_ERROR_INVALID_NULL_HANDLE
 ///         + `NULL == hNativeContext`
 ///     - ::UR_RESULT_ERROR_INVALID_NULL_POINTER
+///         + `NULL == phDevices`
+///         + `NULL == pProperties`
 ///         + `NULL == phContext`
 ur_result_t UR_APICALL urContextCreateWithNativeHandle(
     ur_native_handle_t
-        hNativeContext, ///< [in] the native handle of the context.
+        hNativeContext,  ///< [in] the native handle of the context.
+    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_context_native_properties_t
+        *pProperties, ///< [in] pointer to properties struct
     ur_context_handle_t *
         phContext ///< [out] pointer to the handle of the context object created.
 ) {
@@ -894,7 +901,8 @@ ur_result_t UR_APICALL urContextCreateWithNativeHandle(
         return UR_RESULT_ERROR_UNINITIALIZED;
     }
 
-    return pfnCreateWithNativeHandle(hNativeContext, phContext);
+    return pfnCreateWithNativeHandle(hNativeContext, numDevices, phDevices,
+                                     pProperties, phContext);
 }
 
 ///////////////////////////////////////////////////////////////////////////////