Skip to content

[UR][L0v2] Introduce urGraphGetIdExp to provide unique graph identifiers #22418

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
mmichel11 wants to merge 3 commits into
base: sycl
Choose a base branch
from
Open

[UR][L0v2] Introduce urGraphGetIdExp to provide unique graph identifiers #22418

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
17e74a5
[UR][L0v2] Introduce urGraphGetIdExp to provide unique graph identifiers
mmichel11 Jun 24, 2026
ebcf935
Workaround zeDriverGetExtensionFunctionAddress issue that led to memo…
mmichel11 Jun 26, 2026
d36084c
Add spec revision for urGraphGetIdExp
mmichel11 Jun 26, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 30 additions & 0 deletions unified-runtime/include/unified-runtime/ur_api.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -532,6 +532,8 @@ typedef enum ur_function_t {
UR_FUNCTION_IPC_PUT_EVENT_HANDLE_EXP = 324,
/// Enumerator for ::urIPCOpenEventHandleExp
UR_FUNCTION_IPC_OPEN_EVENT_HANDLE_EXP = 325,
/// Enumerator for ::urGraphGetIdExp
UR_FUNCTION_GRAPH_GET_ID_EXP = 326,
/// @cond
UR_FUNCTION_FORCE_UINT32 = 0x7fffffff
/// @endcond
Expand Down Expand Up @@ -14252,6 +14254,25 @@ UR_APIEXPORT ur_result_t UR_APICALL urGraphIsEmptyExp(
/// [out] Pointer to a boolean where the result will be stored.
bool *pResult);

///////////////////////////////////////////////////////////////////////////////
/// @brief Returns a process-unique identifier that increases monotonically per
/// graph.
///
/// @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 == pGraphId`
UR_APIEXPORT ur_result_t UR_APICALL urGraphGetIdExp(
/// [in] Handle of the graph to query.
ur_exp_graph_handle_t hGraph,
/// [out] Pointer to a uint64_t where the unique graph ID will be stored.
uint64_t *pGraphId);

///////////////////////////////////////////////////////////////////////////////
/// @brief Callback function invoked when a graph is destroyed.
typedef void (*ur_exp_graph_destruction_callback_t)(
Expand Down Expand Up @@ -16879,6 +16900,15 @@ typedef struct ur_graph_is_empty_exp_params_t {
bool **ppResult;
} ur_graph_is_empty_exp_params_t;

///////////////////////////////////////////////////////////////////////////////
/// @brief Function parameters for urGraphGetIdExp
/// @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_id_exp_params_t {
ur_exp_graph_handle_t *phGraph;
uint64_t **ppGraphId;
} ur_graph_get_id_exp_params_t;

///////////////////////////////////////////////////////////////////////////////
/// @brief Function parameters for urGraphSetDestructionCallbackExp
/// @details Each entry is a pointer to the parameter passed to the function;
Expand Down
1 change: 1 addition & 0 deletions unified-runtime/include/unified-runtime/ur_api_funcs.def
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -218,6 +218,7 @@ _UR_API(urGraphInstantiateGraphExp)
_UR_API(urGraphDestroyExp)
_UR_API(urGraphExecutableGraphDestroyExp)
_UR_API(urGraphIsEmptyExp)
_UR_API(urGraphGetIdExp)
_UR_API(urGraphSetDestructionCallbackExp)
_UR_API(urGraphDumpContentsExp)
_UR_API(urGraphGetNativeHandleExp)
Expand Down
6 changes: 6 additions & 0 deletions unified-runtime/include/unified-runtime/ur_ddi.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1919,6 +1919,11 @@ typedef ur_result_t(UR_APICALL *ur_pfnGraphExecutableGraphDestroyExp_t)(
typedef ur_result_t(UR_APICALL *ur_pfnGraphIsEmptyExp_t)(ur_exp_graph_handle_t,
bool *);

///////////////////////////////////////////////////////////////////////////////
/// @brief Function-pointer for urGraphGetIdExp
typedef ur_result_t(UR_APICALL *ur_pfnGraphGetIdExp_t)(ur_exp_graph_handle_t,
uint64_t *);

///////////////////////////////////////////////////////////////////////////////
/// @brief Function-pointer for urGraphSetDestructionCallbackExp
typedef ur_result_t(UR_APICALL *ur_pfnGraphSetDestructionCallbackExp_t)(
Expand Down Expand Up @@ -1947,6 +1952,7 @@ typedef struct ur_graph_exp_dditable_t {
ur_pfnGraphDestroyExp_t pfnDestroyExp;
ur_pfnGraphExecutableGraphDestroyExp_t pfnExecutableGraphDestroyExp;
ur_pfnGraphIsEmptyExp_t pfnIsEmptyExp;
ur_pfnGraphGetIdExp_t pfnGetIdExp;
ur_pfnGraphSetDestructionCallbackExp_t pfnSetDestructionCallbackExp;
ur_pfnGraphDumpContentsExp_t pfnDumpContentsExp;
ur_pfnGraphGetNativeHandleExp_t pfnGetNativeHandleExp;
Expand Down
10 changes: 10 additions & 0 deletions unified-runtime/include/unified-runtime/ur_print.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3765,6 +3765,16 @@ UR_APIEXPORT ur_result_t UR_APICALL urPrintGraphIsEmptyExpParams(
const struct ur_graph_is_empty_exp_params_t *params, char *buffer,
const size_t buff_size, size_t *out_size);

///////////////////////////////////////////////////////////////////////////////
/// @brief Print ur_graph_get_id_exp_params_t struct
/// @returns
/// - ::UR_RESULT_SUCCESS
/// - ::UR_RESULT_ERROR_INVALID_SIZE
/// - `buff_size < out_size`
UR_APIEXPORT ur_result_t UR_APICALL urPrintGraphGetIdExpParams(
const struct ur_graph_get_id_exp_params_t *params, char *buffer,
const size_t buff_size, size_t *out_size);

///////////////////////////////////////////////////////////////////////////////
/// @brief Print ur_graph_set_destruction_callback_exp_params_t struct
/// @returns
Expand Down
26 changes: 26 additions & 0 deletions unified-runtime/include/unified-runtime/ur_print.hpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1422,6 +1422,9 @@ inline std::ostream &operator<<(std::ostream &os, enum ur_function_t value) {
case UR_FUNCTION_IPC_OPEN_EVENT_HANDLE_EXP:
os << "UR_FUNCTION_IPC_OPEN_EVENT_HANDLE_EXP";
break;
case UR_FUNCTION_GRAPH_GET_ID_EXP:
os << "UR_FUNCTION_GRAPH_GET_ID_EXP";
break;
default:
os << "unknown enumerator";
break;
Expand Down Expand Up @@ -21820,6 +21823,26 @@ inline std::ostream &operator<<(
return os;
}

///////////////////////////////////////////////////////////////////////////////
/// @brief Print operator for the ur_graph_get_id_exp_params_t type
/// @returns
/// std::ostream &
inline std::ostream &
operator<<(std::ostream &os,
[[maybe_unused]] const struct ur_graph_get_id_exp_params_t *params) {

os << ".hGraph = ";

ur::details::printPtr(os, *(params->phGraph));

os << ", ";
os << ".pGraphId = ";

ur::details::printPtr(os, *(params->ppGraphId));

return os;
}

///////////////////////////////////////////////////////////////////////////////
/// @brief Print operator for the ur_graph_set_destruction_callback_exp_params_t
/// type
Expand Down Expand Up @@ -23743,6 +23766,9 @@ inline ur_result_t UR_APICALL printFunctionParams(std::ostream &os,
case UR_FUNCTION_GRAPH_IS_EMPTY_EXP: {
os << (const struct ur_graph_is_empty_exp_params_t *)params;
} break;
case UR_FUNCTION_GRAPH_GET_ID_EXP: {
os << (const struct ur_graph_get_id_exp_params_t *)params;
} break;
case UR_FUNCTION_GRAPH_SET_DESTRUCTION_CALLBACK_EXP: {
os << (const struct ur_graph_set_destruction_callback_exp_params_t *)params;
} break;
Expand Down
4 changes: 4 additions & 0 deletions unified-runtime/scripts/core/EXP-GRAPH.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,7 @@ Functions
* ${x}GraphExecutableGraphDestroyExp
* ${x}GraphIsEmptyExp
* ${x}GraphDumpContentsExp
* ${x}GraphGetIdExp
* Queue
* ${x}QueueBeginGraphCaptureExp
* ${x}QueueBeginCaptureIntoGraphExp
Expand Down Expand Up @@ -76,6 +77,9 @@ Changelog
| | register user callbacks invoked on graph |
| | destruction. |
+-----------+---------------------------------------------+
| 1.5 | Add ${x}GraphGetIdExp to retrieve a |
| | process-unique identifier for a graph. |
+-----------+---------------------------------------------+

Support
--------------------------------------------------------------------------------
Expand Down
12 changes: 12 additions & 0 deletions unified-runtime/scripts/core/exp-graph.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -187,6 +187,18 @@ params:
returns:
- $X_RESULT_ERROR_INVALID_GRAPH
--- #--------------------------------------------------------------------------
type: function
desc: "Returns a process-unique identifier that increases monotonically per graph."
class: $xGraph
name: GetIdExp
params:
- type: $x_exp_graph_handle_t
name: hGraph
desc: "[in] Handle of the graph to query."
- type: uint64_t*
name: pGraphId
desc: "[out] Pointer to a uint64_t where the unique graph ID will be stored."
--- #--------------------------------------------------------------------------
type: fptr_typedef
desc: "Callback function invoked when a graph is destroyed."
name: $x_exp_graph_destruction_callback_t
Expand Down
5 changes: 4 additions & 1 deletion unified-runtime/scripts/core/registry.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -757,7 +757,10 @@ etors:
- name: IPC_OPEN_EVENT_HANDLE_EXP
desc: Enumerator for $xIPCOpenEventHandleExp
value: '325'
max_id: '325'
- name: GRAPH_GET_ID_EXP
desc: Enumerator for $xGraphGetIdExp
value: '326'
max_id: '326'
---
type: enum
desc: Defines structure types
Expand Down
5 changes: 5 additions & 0 deletions unified-runtime/source/adapters/cuda/graph.cpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,11 @@ urGraphIsEmptyExp(ur_exp_graph_handle_t /* hGraph */, bool * /* pIsEmpty */) {
return UR_RESULT_ERROR_UNSUPPORTED_FEATURE;
}

UR_APIEXPORT ur_result_t UR_APICALL
urGraphGetIdExp(ur_exp_graph_handle_t /* hGraph */, uint64_t * /* pGraphId */) {
return UR_RESULT_ERROR_UNSUPPORTED_FEATURE;
}

UR_APIEXPORT ur_result_t UR_APICALL urGraphSetDestructionCallbackExp(
ur_exp_graph_handle_t /* hGraph */,
ur_exp_graph_destruction_callback_t /* pfnCallback */,
Expand Down
1 change: 1 addition & 0 deletions unified-runtime/source/adapters/cuda/ur_interface_loader.cpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -99,6 +99,7 @@ UR_APIEXPORT ur_result_t UR_APICALL urGetGraphExpProcAddrTable(
pDdiTable->pfnDestroyExp = urGraphDestroyExp;
pDdiTable->pfnExecutableGraphDestroyExp = urGraphExecutableGraphDestroyExp;
pDdiTable->pfnIsEmptyExp = urGraphIsEmptyExp;
pDdiTable->pfnGetIdExp = urGraphGetIdExp;
pDdiTable->pfnSetDestructionCallbackExp = urGraphSetDestructionCallbackExp;
pDdiTable->pfnDumpContentsExp = urGraphDumpContentsExp;
pDdiTable->pfnGetNativeHandleExp = urGraphGetNativeHandleExp;
Expand Down
5 changes: 5 additions & 0 deletions unified-runtime/source/adapters/hip/graph.cpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,11 @@ urGraphIsEmptyExp(ur_exp_graph_handle_t /* hGraph */, bool * /* pIsEmpty */) {
return UR_RESULT_ERROR_UNSUPPORTED_FEATURE;
}

UR_APIEXPORT ur_result_t UR_APICALL
urGraphGetIdExp(ur_exp_graph_handle_t /* hGraph */, uint64_t * /* pGraphId */) {
return UR_RESULT_ERROR_UNSUPPORTED_FEATURE;
}

UR_APIEXPORT ur_result_t UR_APICALL urGraphSetDestructionCallbackExp(
ur_exp_graph_handle_t /* hGraph */,
ur_exp_graph_destruction_callback_t /* pfnCallback */,
Expand Down
1 change: 1 addition & 0 deletions unified-runtime/source/adapters/hip/ur_interface_loader.cpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -99,6 +99,7 @@ UR_APIEXPORT ur_result_t UR_APICALL urGetGraphExpProcAddrTable(
pDdiTable->pfnDestroyExp = urGraphDestroyExp;
pDdiTable->pfnExecutableGraphDestroyExp = urGraphExecutableGraphDestroyExp;
pDdiTable->pfnIsEmptyExp = urGraphIsEmptyExp;
pDdiTable->pfnGetIdExp = urGraphGetIdExp;
pDdiTable->pfnSetDestructionCallbackExp = urGraphSetDestructionCallbackExp;
pDdiTable->pfnDumpContentsExp = urGraphDumpContentsExp;
pDdiTable->pfnGetNativeHandleExp = urGraphGetNativeHandleExp;
Expand Down
8 changes: 8 additions & 0 deletions unified-runtime/source/adapters/level_zero/graph.cpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,14 @@ ur_result_t urGraphIsEmptyExp(ur_exp_graph_handle_t /* hGraph */,
return UR_RESULT_ERROR_UNSUPPORTED_FEATURE;
}

ur_result_t urGraphGetIdExp(ur_exp_graph_handle_t /* hGraph */,
uint64_t * /* pGraphId */) {
UR_LOG_LEGACY(ERR,
logger::LegacyMessage("[UR][L0] {} function not implemented!"),
"{} function not implemented!", __FUNCTION__);
return UR_RESULT_ERROR_UNSUPPORTED_FEATURE;
}

ur_result_t urGraphSetDestructionCallbackExp(
ur_exp_graph_handle_t /* hGraph */,
ur_exp_graph_destruction_callback_t /* pfnCallback */,
Expand Down
12 changes: 12 additions & 0 deletions unified-runtime/source/adapters/level_zero/platform.cpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -622,6 +622,18 @@ ur_result_t ur_platform_handle_t_::initialize() {
ZE_CALL_NOCHECK(zeDriverGetExtensionFunctionAddress,
(ZeDriver, funcName.c_str(), funcAddr));
}

// zeGraphGetIdExt must be special-cased: querying its address on drivers
// that predate its support leads to memory corruption errors in
// sycl/test-e2e/Adapters/level_zero/ tests, so manually check the driver
// version until the issue is resolved.
if (this->isDriverVersionNewerOrSimilar(1, 15, 38921)) {

@mmichel11 mmichel11 Jun 26, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I first observed these non-graph test failures in: https://github.com/intel/llvm/actions/runs/28179054588 where the driver does not yet support zeGraphGetIdExp. I reproduced this issue locally and confirmed the affected tests pass once I use a driver that supports zeGraphGetIdExt and skip the zeDriverGetExtensionFunctionAddress call for older drivers.

There's an issue to be filed to L0 which seems to be the source of this memory corruption, but this check provides us a workaround for now.

ZE_CALL_NOCHECK(zeDriverGetExtensionFunctionAddress,
(ZeDriver, "zeGraphGetIdExt",
reinterpret_cast<void **>(&ZeGraphExt.zeGraphGetIdExt)));
} else {
ZeGraphExt.zeGraphGetIdExt = nullptr;
}
}

if (this->isDriverVersionNewerOrSimilar(1, 14, 36035)) {
Expand Down
2 changes: 2 additions & 0 deletions unified-runtime/source/adapters/level_zero/platform.hpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -201,6 +201,8 @@ struct ur_platform_handle_t_ : ur::handle_base<ur::level_zero::ddi_getter>,
ze_result_t (*zeCommandListGetGraphExp)(
ze_command_list_handle_t hCommandList, ze_graph_handle_t *phGraph);
ze_result_t (*zeGraphIsEmptyExp)(ze_graph_handle_t hGraph);
ze_result_t (*zeGraphGetIdExt)(ze_graph_handle_t hGraph,
uint64_t *pGraphId);
ze_result_t (*zeGraphDumpContentsExp)(ze_graph_handle_t hGraph,
const char *filePath, void *pNext);
ze_result_t (*zeGraphSetDestructionCallbackExp)(
Expand Down
1 change: 1 addition & 0 deletions unified-runtime/source/adapters/level_zero/ur_interface_loader.cpp
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

1 change: 1 addition & 0 deletions unified-runtime/source/adapters/level_zero/ur_interface_loader.hpp
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

12 changes: 12 additions & 0 deletions unified-runtime/source/adapters/level_zero/v2/graph.cpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -148,6 +148,18 @@ ur_result_t urGraphIsEmptyExp(ur_exp_graph_handle_t hGraph, bool *pIsEmpty) {
return UR_RESULT_SUCCESS;
}

ur_result_t urGraphGetIdExp(ur_exp_graph_handle_t hGraph, uint64_t *pGraphId) {
ur_context_handle_t hContext = hGraph->getContext();
auto ZeGetId = hContext->getPlatform()->ZeGraphExt.zeGraphGetIdExt;
if (!checkGraphExtensionSupport(hContext) || !ZeGetId) {
return UR_RESULT_ERROR_UNSUPPORTED_FEATURE;
}

ZE2UR_CALL(ZeGetId, (hGraph->getZeHandle(), pGraphId));

return UR_RESULT_SUCCESS;
}

ur_result_t urGraphSetDestructionCallbackExp(
ur_exp_graph_handle_t hGraph,
ur_exp_graph_destruction_callback_t pfnCallback, void *pUserData) {
Expand Down
46 changes: 46 additions & 0 deletions unified-runtime/source/adapters/mock/ur_mockddi.cpp
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

6 changes: 6 additions & 0 deletions unified-runtime/source/adapters/native_cpu/graph.cpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,12 @@ urGraphIsEmptyExp(ur_exp_graph_handle_t /* hGraph */, bool * /* pIsEmpty */) {
DIE_NO_IMPLEMENTATION;
}

UR_APIEXPORT ur_result_t UR_APICALL
urGraphGetIdExp(ur_exp_graph_handle_t /* hGraph */, uint64_t * /* pGraphId */) {

DIE_NO_IMPLEMENTATION;
}

UR_APIEXPORT ur_result_t UR_APICALL urGraphSetDestructionCallbackExp(
ur_exp_graph_handle_t /* hGraph */,
ur_exp_graph_destruction_callback_t /* pfnCallback */,
Expand Down
1 change: 1 addition & 0 deletions unified-runtime/source/adapters/native_cpu/ur_interface_loader.cpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -99,6 +99,7 @@ UR_APIEXPORT ur_result_t UR_APICALL urGetGraphExpProcAddrTable(
pDdiTable->pfnDestroyExp = urGraphDestroyExp;
pDdiTable->pfnExecutableGraphDestroyExp = urGraphExecutableGraphDestroyExp;
pDdiTable->pfnIsEmptyExp = urGraphIsEmptyExp;
pDdiTable->pfnGetIdExp = urGraphGetIdExp;
pDdiTable->pfnSetDestructionCallbackExp = urGraphSetDestructionCallbackExp;
pDdiTable->pfnDumpContentsExp = urGraphDumpContentsExp;
pDdiTable->pfnGetNativeHandleExp = urGraphGetNativeHandleExp;
Expand Down
Loading
Loading