From 923a3c0e9bcfec4699ce60837b647aa960001444 Mon Sep 17 00:00:00 2001 From: Krzysztof Swiecicki Date: Fri, 28 Nov 2025 15:18:17 +0000 Subject: [PATCH] [UR] Add missing EXP-GRAPH.rst file --- unified-runtime/include/ur_api.h | 3 + unified-runtime/include/ur_print.hpp | 16 +++++ unified-runtime/scripts/core/EXP-GRAPH.rst | 76 ++++++++++++++++++++++ unified-runtime/scripts/core/exp-graph.yml | 12 ++++ unified-runtime/tools/urinfo/urinfo.hpp | 3 + 5 files changed, 110 insertions(+) create mode 100644 unified-runtime/scripts/core/EXP-GRAPH.rst diff --git a/unified-runtime/include/ur_api.h b/unified-runtime/include/ur_api.h index 646255be5f13b..75cb616f48dd4 100644 --- a/unified-runtime/include/ur_api.h +++ b/unified-runtime/include/ur_api.h @@ -2489,6 +2489,9 @@ typedef enum ur_device_info_t { UR_DEVICE_INFO_CLOCK_DEVICE_SUPPORT_EXP = 0x2062, /// [::ur_bool_t] returns true if the device is integrated GPU. UR_DEVICE_INFO_IS_INTEGRATED_GPU = 0x2070, + /// [::ur_bool_t] returns true if the device supports graph record and replay + /// functionality. + UR_DEVICE_INFO_GRAPH_RECORD_AND_REPLAY_SUPPORT_EXP = 0x2080, /// [::ur_bool_t] Returns true if the device supports the USM P2P /// experimental feature. UR_DEVICE_INFO_USM_P2P_SUPPORT_EXP = 0x4000, diff --git a/unified-runtime/include/ur_print.hpp b/unified-runtime/include/ur_print.hpp index bb989dceeaddf..a3afc20786add 100644 --- a/unified-runtime/include/ur_print.hpp +++ b/unified-runtime/include/ur_print.hpp @@ -3257,6 +3257,9 @@ inline std::ostream &operator<<(std::ostream &os, enum ur_device_info_t value) { case UR_DEVICE_INFO_IS_INTEGRATED_GPU: os << "UR_DEVICE_INFO_IS_INTEGRATED_GPU"; break; + case UR_DEVICE_INFO_GRAPH_RECORD_AND_REPLAY_SUPPORT_EXP: + os << "UR_DEVICE_INFO_GRAPH_RECORD_AND_REPLAY_SUPPORT_EXP"; + break; case UR_DEVICE_INFO_USM_P2P_SUPPORT_EXP: os << "UR_DEVICE_INFO_USM_P2P_SUPPORT_EXP"; break; @@ -5466,6 +5469,19 @@ inline ur_result_t printTagged(std::ostream &os, const void *ptr, os << ")"; } break; + case UR_DEVICE_INFO_GRAPH_RECORD_AND_REPLAY_SUPPORT_EXP: { + const ur_bool_t *tptr = (const ur_bool_t *)ptr; + if (sizeof(ur_bool_t) > size) { + os << "invalid size (is: " << size + << ", expected: >=" << sizeof(ur_bool_t) << ")"; + return UR_RESULT_ERROR_INVALID_SIZE; + } + os << (const void *)(tptr) << " ("; + + os << *tptr; + + os << ")"; + } break; case UR_DEVICE_INFO_USM_P2P_SUPPORT_EXP: { const ur_bool_t *tptr = (const ur_bool_t *)ptr; if (sizeof(ur_bool_t) > size) { diff --git a/unified-runtime/scripts/core/EXP-GRAPH.rst b/unified-runtime/scripts/core/EXP-GRAPH.rst new file mode 100644 index 0000000000000..7b3dff39fe787 --- /dev/null +++ b/unified-runtime/scripts/core/EXP-GRAPH.rst @@ -0,0 +1,76 @@ +<% + OneApi=tags['$OneApi'] + x=tags['$x'] + X=x.upper() +%> + +.. _experimental-graph: + +================================================================================ +Graph +================================================================================ + +.. warning:: + + Experimental features: + + * May be replaced, updated, or removed at any time. + * Do not require maintaining API/ABI stability of their own additions over + time. + + +Motivation +-------------------------------------------------------------------------------- +This extension introduces functionality for recording enqueued operations into a +graph for later execution. Queues can enter graph capture mode, where operations +enqueued to them are recorded into a graph instead of being executed immediately. +This graph can then be instantiated as an executable graph and appended to a queue +multiple times for repeated execution. + +API +-------------------------------------------------------------------------------- + +Enums +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +* ${x}_device_info_t + * ${X}_DEVICE_INFO_GRAPH_RECORD_AND_REPLAY_SUPPORT_EXP + +Functions +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +* Graph + * ${x}GraphCreateExp + * ${x}GraphInstantiateGraphExp + * ${x}GraphDestroyExp + * ${x}GraphExecutableGraphDestroyExp + * ${x}GraphIsEmptyExp + * ${x}GraphDumpContentsExp +* Queue + * ${x}QueueBeginGraphCaptureExp + * ${x}QueueBeginCaptureIntoGraphExp + * ${x}QueueEndGraphCaptureExp + * ${x}QueueAppendGraphExp + * ${x}QueueIsGraphCaptureEnabledExp + +Changelog +-------------------------------------------------------------------------------- + ++-----------+---------------------------------------------+ +| Revision | Changes | ++===========+=============================================+ +| 1.0 | Initial Draft | ++-----------+---------------------------------------------+ +| 1.1 | Extend ${x}_device_info_t enumerator with | +| | graph record and replay entry. | ++-----------+---------------------------------------------+ + +Support +-------------------------------------------------------------------------------- + +Adapters which support this experimental feature *must* return true for the new +``${X}_DEVICE_INFO_GRAPH_RECORD_AND_REPLAY_SUPPORT_EXP`` device info query. + +Contributors +-------------------------------------------------------------------------------- + +* Krzysztof, Filipek `krzysztof.filipek@intel.com `_ +* Krzysztof, Swiecicki `krzysztof.swiecicki@intel.com `_ diff --git a/unified-runtime/scripts/core/exp-graph.yml b/unified-runtime/scripts/core/exp-graph.yml index a53e088ed1a1c..f2f6b9dc258e7 100644 --- a/unified-runtime/scripts/core/exp-graph.yml +++ b/unified-runtime/scripts/core/exp-graph.yml @@ -24,6 +24,18 @@ type: handle desc: "Handle of record & replay executable graph object" name: "$x_exp_executable_graph_handle_t" --- #-------------------------------------------------------------------------- +type: enum +extend: true +typed_etors: true +desc: "Extension enums to $x_device_info_t to support graph record and replay functionality." +name: $x_device_info_t +etors: + - name: GRAPH_RECORD_AND_REPLAY_SUPPORT_EXP + value: "0x2080" + desc: | + [$x_bool_t] returns true if the device supports graph record and replay + functionality. +--- #-------------------------------------------------------------------------- type: function desc: "Create a new record & replay graph instance explicitly." class: $xGraph diff --git a/unified-runtime/tools/urinfo/urinfo.hpp b/unified-runtime/tools/urinfo/urinfo.hpp index a058b8e69a07c..537753ad04ed1 100644 --- a/unified-runtime/tools/urinfo/urinfo.hpp +++ b/unified-runtime/tools/urinfo/urinfo.hpp @@ -460,6 +460,9 @@ inline void printDeviceInfos(ur_device_handle_t hDevice, std::cout << prefix; printDeviceInfo(hDevice, UR_DEVICE_INFO_IS_INTEGRATED_GPU); std::cout << prefix; + printDeviceInfo( + hDevice, UR_DEVICE_INFO_GRAPH_RECORD_AND_REPLAY_SUPPORT_EXP); + std::cout << prefix; printDeviceInfo(hDevice, UR_DEVICE_INFO_USM_P2P_SUPPORT_EXP); std::cout << prefix; printDeviceInfo(hDevice,