Graph - Extensions

Graph - Extensions#

oneAPI Level Zero Specification - Version 1.18.31

Graph - Extension Functions#

zeGraphCreateExt#

Added in version 1.17

ZE_APIEXPORT ze_result_t ZE_APICALL zeGraphCreateExt(ze_context_handle_t hContext, const void *pNext, ze_graph_handle_t *phGraph)#

Creates a new graph object.

Parameters:

  • hContext – [in] handle of the context

  • pNext – [in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext)

  • phGraph – [out] pointer to handle of the graph object created

Returns:

zeGraphGetPrimaryCommandListExt#

Added in version 1.17

ZE_APIEXPORT ze_result_t ZE_APICALL zeGraphGetPrimaryCommandListExt(ze_graph_handle_t hGraph, ze_command_list_handle_t *phCommandList)#

Returns the primary command list associated with a graph capture session.

  • The returned command list is the command list that initiated capture for the graph during its recording stage.

  • This function can be called while the graph is being recorded and after capture has ended.

Parameters:

  • hGraph – [in] handle of the graph

  • phCommandList – [out] pointer to the primary command list handle associated with the graph

Returns:

zeGraphSetDestructionCallbackExt#

Added in version 1.17

ZE_APIEXPORT ze_result_t ZE_APICALL zeGraphSetDestructionCallbackExt(ze_graph_handle_t hGraph, zex_mem_graph_free_callback_fn_t pfnCallback, void *pUserData, const void *pNext)#

Registers a host callback that is invoked when a graph is destroyed.

  • Callbacks may be registered while a graph is being recorded or after executable graph instances have been created from it.

  • Multiple callbacks may be registered for the same graph.

  • All registered callbacks are invoked when the graph is destroyed.

  • The callback must not call Level Zero APIs that use the graph being destroyed.

Parameters:

  • hGraph – [in] handle of the graph

  • pfnCallback – [in] callback function to invoke when the graph is destroyed

  • pUserData – [in][optional] user data to pass to the callback

  • pNext – [in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext)

Returns:

zeGraphInstantiateExt#

Added in version 1.17

ZE_APIEXPORT ze_result_t ZE_APICALL zeGraphInstantiateExt(ze_graph_handle_t hGraph, const void *pNext, ze_executable_graph_handle_t *phExecutableGraph)#

Creates an executable graph object from a recorded graph.

  • Multiple executable graph objects may be created from a single recorded graph.

  • Recorded regular events (not counter-based) are shared between executable graph instances; the application is responsible for avoiding data races during concurrent execution of multiple graph instances.

  • Recorded internal counter-based events (i.e. without ZEX_COUNTER_BASED_EVENT_FLAG_GRAPH_EXTERNAL) may be used only for synchronization within the graph. Their state is tied to the underlying execution queue and is not shared between executable graph instances.

  • Recorded external counter-based events (i.e. with ZEX_COUNTER_BASED_EVENT_FLAG_GRAPH_EXTERNAL) may be used to synchronize the graph with device commands submitted outside the graph (for example, before or after zeCommandListAppendGraphExt) and with the host. External counter-based events may incur additional overhead compared to internal counter-based events.

  • Resources used in captured commands (e.g. buffers passed to kernels as arguments) are shared between instances; the application is responsible for avoiding data races during concurrent execution.

  • The function returns ZE_RESULT_ERROR_INVALID_GRAPH when the recorded graph is invalid, for example when it contains forks that were never joined back to the primary command list.

  • The function returns ZE_RESULT_ERROR_INVALID_ARGUMENT when graph capture has not been ended with zeCommandListEndGraphCaptureExt.

Parameters:

  • hGraph – [in] handle of the recorded graph

  • pNext – [in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext)

  • phExecutableGraph – [out] pointer to handle of the executable graph

Returns:

zeGraphIsEmptyExt#

Added in version 1.17

ZE_APIEXPORT ze_result_t ZE_APICALL zeGraphIsEmptyExt(ze_graph_handle_t hGraph)#

Queries whether a graph is empty.

  • The function returns ZE_RESULT_QUERY_TRUE when the graph contains no operations.

  • The function returns ZE_RESULT_QUERY_FALSE when the graph contains recorded operations.

  • The function returns ZE_RESULT_ERROR_INVALID_GRAPH when the recorded graph is invalid.

Parameters:

hGraph – [in] handle of the graph

Returns:

zeGraphDumpContentsExt#

Added in version 1.17

ZE_APIEXPORT ze_result_t ZE_APICALL zeGraphDumpContentsExt(ze_graph_handle_t hGraph, const char *filePath, const void *pNext)#

Writes a DOT description of a recorded graph to disk.

  • The generated DOT output captures the graph structure and recorded append operations.

  • Kernel node output includes kernel names, argument lists, and argument types and values.

Parameters:

  • hGraph – [in] handle of the graph

  • filePath – [in] path where the DOT file is written

  • pNext – [in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext)

Returns:

zeGraphDestroyExt#

Added in version 1.17

ZE_APIEXPORT ze_result_t ZE_APICALL zeGraphDestroyExt(ze_graph_handle_t hGraph)#

Destroys a recorded graph object.

  • All executable graph instances created from the recorded graph must be destroyed before this function is called.

  • After destruction, the handle becomes invalid and must not be used in further API calls.

Parameters:

hGraph – [in][release] handle of the graph to destroy

Returns:

zeGraphPauseCaptureExt#

Added in version 1.18

ZE_APIEXPORT ze_result_t ZE_APICALL zeGraphPauseCaptureExt(ze_graph_handle_t hGraph)#

Pauses recording to the specified graph. Affected immediate command lists (both primary command lists and child command lists from which graph was recording) can be reused for any purpose during this pause without affecting the paused recording.

Parameters:

hGraph – [in] handle to the graph to pause capture

Returns:

zeGraphResumeCaptureExt#

Added in version 1.18

ZE_APIEXPORT ze_result_t ZE_APICALL zeGraphResumeCaptureExt(ze_graph_handle_t hGraph)#

Resumes capturing commands to the graph after a pause.

Parameters:

hGraph – [in] handle to the graph to resume capture

Returns:

zeGraphGetIdExt#

Added in version 1.18

ZE_APIEXPORT ze_result_t ZE_APICALL zeGraphGetIdExt(ze_graph_handle_t hGraph, uint64_t *pGraphId)#

Gets monotonically increasing, process-unique ID of the graph.

Parameters:

  • hGraph – [in] handle to the graph

  • pGraphId – [out] pointer to the memory where the graph ID will be written

Returns: