[L0v2] Add retrieval of native graph handle

unified-runtime/include/unified-runtime/ur_api.h

@@ -510,6 +510,10 @@ typedef enum ur_function_t {
   UR_FUNCTION_USM_HOST_ALLOC_UNREGISTER_EXP = 313,
   /// Enumerator for ::urQueueGetGraphExp
   UR_FUNCTION_QUEUE_GET_GRAPH_EXP = 314,
+  /// Enumerator for ::urGraphGetNativeHandleExp
+  UR_FUNCTION_GRAPH_GET_NATIVE_HANDLE_EXP = 315,
+  /// Enumerator for ::urExecutableGraphGetNativeHandleExp
+  UR_FUNCTION_EXECUTABLE_GRAPH_GET_NATIVE_HANDLE_EXP = 316,
   /// @cond
   UR_FUNCTION_FORCE_UINT32 = 0x7fffffff
   /// @endcond
@@ -13892,6 +13896,54 @@ UR_APIEXPORT ur_result_t UR_APICALL urGraphDumpContentsExp(
     /// [in] Path to the file to write the dumped graph contents.
     const char *filePath);
 
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Return platform native graph handle.
+///
+/// @details
+///     - Retrieved native handle can be used for direct interaction with the
+///       native platform driver.
+///
+/// @returns
+///     - ::UR_RESULT_SUCCESS
+///     - ::UR_RESULT_ERROR_UNINITIALIZED
+///     - ::UR_RESULT_ERROR_DEVICE_LOST
+///     - ::UR_RESULT_ERROR_ADAPTER_SPECIFIC
+///     - ::UR_RESULT_ERROR_INVALID_NULL_HANDLE
+///         + `NULL == hGraph`
+///     - ::UR_RESULT_ERROR_INVALID_NULL_POINTER
+///         + `NULL == phNativeGraph`
+///     - ::UR_RESULT_ERROR_UNSUPPORTED_FEATURE
+///         + If the adapter has no underlying equivalent handle.
+UR_APIEXPORT ur_result_t UR_APICALL urGraphGetNativeHandleExp(
+    /// [in] Handle of the graph.
+    ur_exp_graph_handle_t hGraph,
+    /// [out] A pointer to the native handle of the graph.
+    ur_native_handle_t *phNativeGraph);
+
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Return platform native executable graph handle.
+///
+/// @details
+///     - Retrieved native handle can be used for direct interaction with the
+///       native platform driver.
+///
+/// @returns
+///     - ::UR_RESULT_SUCCESS
+///     - ::UR_RESULT_ERROR_UNINITIALIZED
+///     - ::UR_RESULT_ERROR_DEVICE_LOST
+///     - ::UR_RESULT_ERROR_ADAPTER_SPECIFIC
+///     - ::UR_RESULT_ERROR_INVALID_NULL_HANDLE
+///         + `NULL == hExecutableGraph`
+///     - ::UR_RESULT_ERROR_INVALID_NULL_POINTER
+///         + `NULL == phNativeExecutableGraph`
+///     - ::UR_RESULT_ERROR_UNSUPPORTED_FEATURE
+///         + If the adapter has no underlying equivalent handle.
+UR_APIEXPORT ur_result_t UR_APICALL urExecutableGraphGetNativeHandleExp(
+    /// [in] Handle of the executable graph.
+    ur_exp_executable_graph_handle_t hExecutableGraph,
+    /// [out] A pointer to the native handle of the executable graph.
+    ur_native_handle_t *phNativeExecutableGraph);
+
 #if !defined(__GNUC__)
 #pragma endregion
 #endif
@@ -16423,6 +16475,24 @@ typedef struct ur_graph_dump_contents_exp_params_t {
   const char **pfilePath;
 } ur_graph_dump_contents_exp_params_t;
 
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Function parameters for urGraphGetNativeHandleExp
+/// @details Each entry is a pointer to the parameter passed to the function;
+///     allowing the callback the ability to modify the parameter's value
+typedef struct ur_graph_get_native_handle_exp_params_t {
+  ur_exp_graph_handle_t *phGraph;
+  ur_native_handle_t **pphNativeGraph;
+} ur_graph_get_native_handle_exp_params_t;
+
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Function parameters for urExecutableGraphGetNativeHandleExp
+/// @details Each entry is a pointer to the parameter passed to the function;
+///     allowing the callback the ability to modify the parameter's value
+typedef struct ur_executable_graph_get_native_handle_exp_params_t {
+  ur_exp_executable_graph_handle_t *phExecutableGraph;
+  ur_native_handle_t **pphNativeExecutableGraph;
+} ur_executable_graph_get_native_handle_exp_params_t;
+
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Function parameters for urIPCGetMemHandleExp
 /// @details Each entry is a pointer to the parameter passed to the function;

unified-runtime/include/unified-runtime/ur_api_funcs.def

@@ -218,6 +218,8 @@ _UR_API(urGraphDestroyExp)
 _UR_API(urGraphExecutableGraphDestroyExp)
 _UR_API(urGraphIsEmptyExp)
 _UR_API(urGraphDumpContentsExp)
+_UR_API(urGraphGetNativeHandleExp)
+_UR_API(urExecutableGraphGetNativeHandleExp)
 _UR_API(urIPCGetMemHandleExp)
 _UR_API(urIPCPutMemHandleExp)
 _UR_API(urIPCOpenMemHandleExp)

unified-runtime/include/unified-runtime/ur_ddi.h

@@ -1892,6 +1892,11 @@ typedef ur_result_t(UR_APICALL *ur_pfnGraphIsEmptyExp_t)(ur_exp_graph_handle_t,
 typedef ur_result_t(UR_APICALL *ur_pfnGraphDumpContentsExp_t)(
     ur_exp_graph_handle_t, const char *);
 
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Function-pointer for urGraphGetNativeHandleExp
+typedef ur_result_t(UR_APICALL *ur_pfnGraphGetNativeHandleExp_t)(
+    ur_exp_graph_handle_t, ur_native_handle_t *);
+
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Table of GraphExp functions pointers
 typedef struct ur_graph_exp_dditable_t {
@@ -1901,6 +1906,7 @@ typedef struct ur_graph_exp_dditable_t {
   ur_pfnGraphExecutableGraphDestroyExp_t pfnExecutableGraphDestroyExp;
   ur_pfnGraphIsEmptyExp_t pfnIsEmptyExp;
   ur_pfnGraphDumpContentsExp_t pfnDumpContentsExp;
+  ur_pfnGraphGetNativeHandleExp_t pfnGetNativeHandleExp;
 } ur_graph_exp_dditable_t;
 
 ///////////////////////////////////////////////////////////////////////////////
@@ -1923,6 +1929,37 @@ UR_DLLEXPORT ur_result_t UR_APICALL urGetGraphExpProcAddrTable(
 typedef ur_result_t(UR_APICALL *ur_pfnGetGraphExpProcAddrTable_t)(
     ur_api_version_t, ur_graph_exp_dditable_t *);
 
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Function-pointer for urExecutableGraphGetNativeHandleExp
+typedef ur_result_t(UR_APICALL *ur_pfnExecutableGraphGetNativeHandleExp_t)(
+    ur_exp_executable_graph_handle_t, ur_native_handle_t *);
+
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Table of ExecutableGraphExp functions pointers
+typedef struct ur_executable_graph_exp_dditable_t {
+  ur_pfnExecutableGraphGetNativeHandleExp_t pfnGetNativeHandleExp;
+} ur_executable_graph_exp_dditable_t;
+
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Exported function for filling application's ExecutableGraphExp table
+///        with current process' addresses
+///
+/// @returns
+///     - ::UR_RESULT_SUCCESS
+///     - ::UR_RESULT_ERROR_UNINITIALIZED
+///     - ::UR_RESULT_ERROR_INVALID_NULL_POINTER
+///     - ::UR_RESULT_ERROR_UNSUPPORTED_VERSION
+UR_DLLEXPORT ur_result_t UR_APICALL urGetExecutableGraphExpProcAddrTable(
+    /// [in] API version requested
+    ur_api_version_t version,
+    /// [in,out] pointer to table of DDI function pointers
+    ur_executable_graph_exp_dditable_t *pDdiTable);
+
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Function-pointer for urGetExecutableGraphExpProcAddrTable
+typedef ur_result_t(UR_APICALL *ur_pfnGetExecutableGraphExpProcAddrTable_t)(
+    ur_api_version_t, ur_executable_graph_exp_dditable_t *);
+
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Function-pointer for urIPCGetMemHandleExp
 typedef ur_result_t(UR_APICALL *ur_pfnIPCGetMemHandleExp_t)(ur_context_handle_t,
@@ -2267,6 +2304,7 @@ typedef struct ur_dditable_t {
   ur_bindless_images_exp_dditable_t BindlessImagesExp;
   ur_command_buffer_exp_dditable_t CommandBufferExp;
   ur_graph_exp_dditable_t GraphExp;
+  ur_executable_graph_exp_dditable_t ExecutableGraphExp;
   ur_ipc_exp_dditable_t IPCExp;
   ur_memory_export_exp_dditable_t MemoryExportExp;
   ur_usm_p2p_exp_dditable_t UsmP2PExp;

unified-runtime/include/unified-runtime/ur_print.h

@@ -3735,6 +3735,27 @@ UR_APIEXPORT ur_result_t UR_APICALL urPrintGraphDumpContentsExpParams(
     const struct ur_graph_dump_contents_exp_params_t *params, char *buffer,
     const size_t buff_size, size_t *out_size);
 
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Print ur_graph_get_native_handle_exp_params_t struct
+/// @returns
+///     - ::UR_RESULT_SUCCESS
+///     - ::UR_RESULT_ERROR_INVALID_SIZE
+///         - `buff_size < out_size`
+UR_APIEXPORT ur_result_t UR_APICALL urPrintGraphGetNativeHandleExpParams(
+    const struct ur_graph_get_native_handle_exp_params_t *params, char *buffer,
+    const size_t buff_size, size_t *out_size);
+
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Print ur_executable_graph_get_native_handle_exp_params_t struct
+/// @returns
+///     - ::UR_RESULT_SUCCESS
+///     - ::UR_RESULT_ERROR_INVALID_SIZE
+///         - `buff_size < out_size`
+UR_APIEXPORT ur_result_t UR_APICALL
+urPrintExecutableGraphGetNativeHandleExpParams(
+    const struct ur_executable_graph_get_native_handle_exp_params_t *params,
+    char *buffer, const size_t buff_size, size_t *out_size);
+
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Print ur_ipc_get_mem_handle_exp_params_t struct
 /// @returns

unified-runtime/include/unified-runtime/ur_print.hpp

@@ -1377,6 +1377,12 @@ inline std::ostream &operator<<(std::ostream &os, enum ur_function_t value) {
   case UR_FUNCTION_QUEUE_GET_GRAPH_EXP:
     os << "UR_FUNCTION_QUEUE_GET_GRAPH_EXP";
     break;
+  case UR_FUNCTION_GRAPH_GET_NATIVE_HANDLE_EXP:
+    os << "UR_FUNCTION_GRAPH_GET_NATIVE_HANDLE_EXP";
+    break;
+  case UR_FUNCTION_EXECUTABLE_GRAPH_GET_NATIVE_HANDLE_EXP:
+    os << "UR_FUNCTION_EXECUTABLE_GRAPH_GET_NATIVE_HANDLE_EXP";
+    break;
   default:
     os << "unknown enumerator";
     break;
@@ -21588,6 +21594,48 @@ inline std::ostream &operator<<(
   return os;
 }
 
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Print operator for the ur_graph_get_native_handle_exp_params_t type
+/// @returns
+///     std::ostream &
+inline std::ostream &
+operator<<(std::ostream &os,
+           [[maybe_unused]] const struct ur_graph_get_native_handle_exp_params_t
+               *params) {
+
+  os << ".hGraph = ";
+
+  ur::details::printPtr(os, *(params->phGraph));
+
+  os << ", ";
+  os << ".phNativeGraph = ";
+
+  ur::details::printPtr(os, *(params->pphNativeGraph));
+
+  return os;
+}
+
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Print operator for the
+/// ur_executable_graph_get_native_handle_exp_params_t type
+/// @returns
+///     std::ostream &
+inline std::ostream &
+operator<<(std::ostream &os, [[maybe_unused]] const struct
+           ur_executable_graph_get_native_handle_exp_params_t *params) {
+
+  os << ".hExecutableGraph = ";
+
+  ur::details::printPtr(os, *(params->phExecutableGraph));
+
+  os << ", ";
+  os << ".phNativeExecutableGraph = ";
+
+  ur::details::printPtr(os, *(params->pphNativeExecutableGraph));
+
+  return os;
+}
+
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Print operator for the ur_ipc_get_mem_handle_exp_params_t type
 /// @returns
@@ -23235,6 +23283,13 @@ inline ur_result_t UR_APICALL printFunctionParams(std::ostream &os,
   case UR_FUNCTION_GRAPH_DUMP_CONTENTS_EXP: {
     os << (const struct ur_graph_dump_contents_exp_params_t *)params;
   } break;
+  case UR_FUNCTION_GRAPH_GET_NATIVE_HANDLE_EXP: {
+    os << (const struct ur_graph_get_native_handle_exp_params_t *)params;
+  } break;
+  case UR_FUNCTION_EXECUTABLE_GRAPH_GET_NATIVE_HANDLE_EXP: {
+    os << (const struct ur_executable_graph_get_native_handle_exp_params_t *)
+            params;
+  } break;
   case UR_FUNCTION_IPC_GET_MEM_HANDLE_EXP: {
     os << (const struct ur_ipc_get_mem_handle_exp_params_t *)params;
   } break;

unified-runtime/scripts/core/exp-graph.yml

@@ -198,3 +198,41 @@ params:
     - type: const char*
       name: filePath
       desc: "[in] Path to the file to write the dumped graph contents."
+--- #--------------------------------------------------------------------------
+type: function
+desc: "Return platform native graph handle."
+class: $xGraph
+name: GetNativeHandleExp
+details:
+    - "Retrieved native handle can be used for direct interaction with the native platform driver."
+params:
+    - type: "$x_exp_graph_handle_t"
+      name: hGraph
+      desc: |
+            [in] Handle of the graph.
+    - type: $x_native_handle_t*
+      name: phNativeGraph
+      desc: |
+            [out] A pointer to the native handle of the graph.
+returns:
+    - $X_RESULT_ERROR_UNSUPPORTED_FEATURE:
+        - "If the adapter has no underlying equivalent handle."
+--- #--------------------------------------------------------------------------
+type: function
+desc: "Return platform native executable graph handle."
+class: $xExecutableGraph
+name: GetNativeHandleExp
+details:
+    - "Retrieved native handle can be used for direct interaction with the native platform driver."
+params:
+    - type: "$x_exp_executable_graph_handle_t"
+      name: hExecutableGraph
+      desc: |
+            [in] Handle of the executable graph.
+    - type: $x_native_handle_t*
+      name: phNativeExecutableGraph
+      desc: |
+            [out] A pointer to the native handle of the executable graph.
+returns:
+    - $X_RESULT_ERROR_UNSUPPORTED_FEATURE:
+        - "If the adapter has no underlying equivalent handle."

unified-runtime/scripts/core/registry.yml

@@ -724,7 +724,13 @@ etors:
 - name: QUEUE_GET_GRAPH_EXP
   desc: Enumerator for $xQueueGetGraphExp
   value: '314'
-max_id: '314'
+- name: GRAPH_GET_NATIVE_HANDLE_EXP
+  desc: Enumerator for $xGraphGetNativeHandleExp
+  value: '315'
+- name: EXECUTABLE_GRAPH_GET_NATIVE_HANDLE_EXP
+  desc: Enumerator for $xExecutableGraphGetNativeHandleExp
+  value: '316'
+max_id: '316'
 ---
 type: enum
 desc: Defines structure types

unified-runtime/source/adapters/cuda/graph.cpp

@@ -39,3 +39,15 @@ UR_APIEXPORT ur_result_t UR_APICALL urGraphInstantiateGraphExp(
     ur_exp_executable_graph_handle_t * /* phExecutableGraph */) {
   return UR_RESULT_ERROR_UNSUPPORTED_FEATURE;
 }
+
+UR_APIEXPORT ur_result_t UR_APICALL
+urGraphGetNativeHandleExp(ur_exp_graph_handle_t /* hGraph */,
+                          ur_native_handle_t * /* phNativeGraph */) {
+  return UR_RESULT_ERROR_UNSUPPORTED_FEATURE;
+}
+
+UR_APIEXPORT ur_result_t UR_APICALL urGraphExecutableGraphGetNativeHandleExp(
+    ur_exp_executable_graph_handle_t /* hExecutableGraph */,
+    ur_native_handle_t * /* phNativeExecutableGraph */) {
+  return UR_RESULT_ERROR_UNSUPPORTED_FEATURE;
+}

unified-runtime/source/adapters/cuda/ur_interface_loader.cpp

@@ -90,6 +90,9 @@ UR_APIEXPORT ur_result_t UR_APICALL urGetGraphExpProcAddrTable(
   pDdiTable->pfnExecutableGraphDestroyExp = urGraphExecutableGraphDestroyExp;
   pDdiTable->pfnIsEmptyExp = urGraphIsEmptyExp;
   pDdiTable->pfnDumpContentsExp = urGraphDumpContentsExp;
+  pDdiTable->pfnGetNativeHandleExp = urGraphGetNativeHandleExp;
+  pDdiTable->pfnExecutableGraphGetNativeHandleExp =
+      urGraphExecutableGraphGetNativeHandleExp;
 
   return UR_RESULT_SUCCESS;
 }

unified-runtime/source/adapters/hip/graph.cpp

@@ -39,3 +39,15 @@ UR_APIEXPORT ur_result_t UR_APICALL urGraphInstantiateGraphExp(
     ur_exp_executable_graph_handle_t * /* phExecutableGraph */) {
   return UR_RESULT_ERROR_UNSUPPORTED_FEATURE;
 }
+
+UR_APIEXPORT ur_result_t UR_APICALL
+urGraphGetNativeHandleExp(ur_exp_graph_handle_t /* hGraph */,
+                          ur_native_handle_t * /* phNativeGraph */) {
+  return UR_RESULT_ERROR_UNSUPPORTED_FEATURE;
+}
+
+UR_APIEXPORT ur_result_t UR_APICALL urGraphExecutableGraphGetNativeHandleExp(
+    ur_exp_executable_graph_handle_t /* hExecutableGraph */,
+    ur_native_handle_t * /* phNativeExecutableGraph */) {
+  return UR_RESULT_ERROR_UNSUPPORTED_FEATURE;
+}

unified-runtime/source/adapters/hip/ur_interface_loader.cpp

@@ -90,6 +90,9 @@ UR_APIEXPORT ur_result_t UR_APICALL urGetGraphExpProcAddrTable(
   pDdiTable->pfnExecutableGraphDestroyExp = urGraphExecutableGraphDestroyExp;
   pDdiTable->pfnIsEmptyExp = urGraphIsEmptyExp;
   pDdiTable->pfnDumpContentsExp = urGraphDumpContentsExp;
+  pDdiTable->pfnGetNativeHandleExp = urGraphGetNativeHandleExp;
+  pDdiTable->pfnExecutableGraphGetNativeHandleExp =
+      urGraphExecutableGraphGetNativeHandleExp;
 
   return UR_RESULT_SUCCESS;
 }