This section describes the graph management types & functions of HIP runtime API. More...

Collaboration diagram for Graph Management:

Classes
struct	hipHostNodeParams

struct	hipKernelNodeParams

struct	hipMemsetParams

Typedefs
typedef struct ihipGraph *	hipGraph_t

typedef struct hipGraphNode *	hipGraphNode_t

typedef struct hipGraphExec *	hipGraphExec_t

typedef enum hipGraphNodeType	hipGraphNodeType

typedef void(*	hipHostFn_t) (void *userData)

typedef struct hipHostNodeParams	hipHostNodeParams

typedef struct hipKernelNodeParams	hipKernelNodeParams

typedef struct hipMemsetParams	hipMemsetParams

typedef enum hipGraphExecUpdateResult	hipGraphExecUpdateResult

typedef enum hipStreamCaptureMode	hipStreamCaptureMode

typedef enum hipStreamCaptureStatus	hipStreamCaptureStatus

Enumerations
enum	hipGraphNodeType { hipGraphNodeTypeKernel = 1, hipGraphNodeTypeMemcpy = 2, hipGraphNodeTypeMemset = 3, hipGraphNodeTypeHost = 4, hipGraphNodeTypeGraph = 5, hipGraphNodeTypeEmpty = 6, hipGraphNodeTypeWaitEvent = 7, hipGraphNodeTypeEventRecord = 8, hipGraphNodeTypeMemcpy1D = 9, hipGraphNodeTypeMemcpyFromSymbol = 10, hipGraphNodeTypeMemcpyToSymbol = 11, hipGraphNodeTypeCount }

enum	hipGraphExecUpdateResult { hipGraphExecUpdateSuccess = 0x0, hipGraphExecUpdateError = 0x1, hipGraphExecUpdateErrorTopologyChanged = 0x2, hipGraphExecUpdateErrorNodeTypeChanged = 0x3, hipGraphExecUpdateErrorFunctionChanged, hipGraphExecUpdateErrorParametersChanged, hipGraphExecUpdateErrorNotSupported, hipGraphExecUpdateErrorUnsupportedFunctionChange = 0x7 }

enum	hipStreamCaptureMode { hipStreamCaptureModeGlobal = 0, hipStreamCaptureModeThreadLocal, hipStreamCaptureModeRelaxed }

enum	hipStreamCaptureStatus { hipStreamCaptureStatusNone = 0, hipStreamCaptureStatusActive, hipStreamCaptureStatusInvalidated }

Functions
hipError_t	hipStreamBeginCapture (hipStream_t stream, hipStreamCaptureMode mode)
	Begins graph capture on a stream. More...

hipError_t	hipStreamEndCapture (hipStream_t stream, hipGraph_t *pGraph)
	Ends capture on a stream, returning the captured graph. More...

hipError_t	hipGraphCreate (hipGraph_t *pGraph, unsigned int flags)
	Creates a graph. More...

hipError_t	hipGraphDestroy (hipGraph_t graph)
	Destroys a graph. More...

hipError_t	hipGraphExecDestroy (hipGraphExec_t pGraphExec)
	Destroys an executable graph. More...

hipError_t	hipGraphInstantiate (hipGraphExec_t pGraphExec, hipGraph_t graph, hipGraphNode_t pErrorNode, char *pLogBuffer, size_t bufferSize)
	Creates an executable graph from a graph. More...

hipError_t	hipGraphLaunch (hipGraphExec_t graphExec, hipStream_t stream)
	launches an executable graph in a stream More...

hipError_t	hipGraphAddKernelNode (hipGraphNode_t pGraphNode, hipGraph_t graph, const hipGraphNode_t pDependencies, size_t numDependencies, const hipKernelNodeParams *pNodeParams)
	Creates a kernel execution node and adds it to a graph. More...

hipError_t	hipGraphAddMemcpyNode (hipGraphNode_t pGraphNode, hipGraph_t graph, const hipGraphNode_t pDependencies, size_t numDependencies, const hipMemcpy3DParms *pCopyParams)
	Creates a memcpy node and adds it to a graph. More...

hipError_t	hipGraphAddMemcpyNode1D (hipGraphNode_t pGraphNode, hipGraph_t graph, const hipGraphNode_t pDependencies, size_t numDependencies, void dst, const void src, size_t count, hipMemcpyKind kind)
	Creates a 1D memcpy node and adds it to a graph. More...

hipError_t	hipGraphAddMemsetNode (hipGraphNode_t pGraphNode, hipGraph_t graph, const hipGraphNode_t pDependencies, size_t numDependencies, const hipMemsetParams *pMemsetParams)
	Creates a memset node and adds it to a graph. More...

hipError_t	hipGraphGetNodes (hipGraph_t graph, hipGraphNode_t nodes, size_t numNodes)
	Returns graph nodes. More...

hipError_t	hipGraphGetRootNodes (hipGraph_t graph, hipGraphNode_t pRootNodes, size_t pNumRootNodes)
	Returns graph's root nodes. More...

hipError_t	hipGraphKernelNodeGetParams (hipGraphNode_t node, hipKernelNodeParams *pNodeParams)
	Gets kernel node's parameters. More...

hipError_t	hipGraphKernelNodeSetParams (hipGraphNode_t node, const hipKernelNodeParams *pNodeParams)
	Sets a kernel node's parameters. More...

hipError_t	hipGraphMemcpyNodeGetParams (hipGraphNode_t node, hipMemcpy3DParms *pNodeParams)
	Gets a memcpy node's parameters. More...

hipError_t	hipGraphMemcpyNodeSetParams (hipGraphNode_t node, const hipMemcpy3DParms *pNodeParams)
	Sets a memcpy node's parameters. More...

hipError_t	hipGraphMemsetNodeGetParams (hipGraphNode_t node, hipMemsetParams *pNodeParams)
	Gets a memset node's parameters. More...

hipError_t	hipGraphMemsetNodeSetParams (hipGraphNode_t node, const hipMemsetParams *pNodeParams)
	Sets a memset node's parameters. More...

hipError_t	hipGraphExecKernelNodeSetParams (hipGraphExec_t hGraphExec, hipGraphNode_t node, const hipKernelNodeParams *pNodeParams)
	Sets the parameters for a kernel node in the given graphExec. More...

hipError_t	hipGraphAddDependencies (hipGraph_t graph, const hipGraphNode_t from, const hipGraphNode_t to, size_t numDependencies)
	Adds dependency edges to a graph. More...

hipError_t	hipGraphAddEmptyNode (hipGraphNode_t pGraphNode, hipGraph_t graph, const hipGraphNode_t pDependencies, size_t numDependencies)
	Creates an empty node and adds it to a graph. More...

Detailed Description

This section describes the graph management types & functions of HIP runtime API.

Typedef Documentation

◆ hipGraph_t

typedef struct ihipGraph* hipGraph_t

An opaque value that represents a hip graph

◆ hipGraphExec_t

typedef struct hipGraphExec* hipGraphExec_t

An opaque value that represents a hip graph Exec

◆ hipGraphNode_t

typedef struct hipGraphNode* hipGraphNode_t

An opaque value that represents a hip graph node

Enumeration Type Documentation

◆ hipGraphExecUpdateResult

enum hipGraphExecUpdateResult

Enumerator
hipGraphExecUpdateSuccess	The update succeeded.
hipGraphExecUpdateError	The update failed for an unexpected reason which is described in the return value of the function
hipGraphExecUpdateErrorTopologyChanged	The update failed because the topology changed.
hipGraphExecUpdateErrorNodeTypeChanged	The update failed because a node type changed.
hipGraphExecUpdateErrorFunctionChanged	The update failed because the function of a kernel node changed.
hipGraphExecUpdateErrorParametersChanged	The update failed because the parameters changed in a way that is not supported.
hipGraphExecUpdateErrorNotSupported	The update failed because something about the node is not supported.

◆ hipGraphNodeType

enum hipGraphNodeType

Enumerator
hipGraphNodeTypeKernel	GPU kernel node.
hipGraphNodeTypeMemcpy	Memcpy 3D node.
hipGraphNodeTypeMemset	Memset 1D node.
hipGraphNodeTypeHost	Host (executable) node.
hipGraphNodeTypeGraph	Node which executes an embedded graph.
hipGraphNodeTypeEmpty	Empty (no-op) node.
hipGraphNodeTypeWaitEvent	External event wait node.
hipGraphNodeTypeEventRecord	External event record node.
hipGraphNodeTypeMemcpy1D	Memcpy 1D node.
hipGraphNodeTypeMemcpyFromSymbol	MemcpyFromSymbol node.
hipGraphNodeTypeMemcpyToSymbol	MemcpyToSymbol node.

◆ hipStreamCaptureStatus

enum hipStreamCaptureStatus

Enumerator
hipStreamCaptureStatusNone	Stream is not capturing.
hipStreamCaptureStatusActive	Stream is actively capturing.
hipStreamCaptureStatusInvalidated	Stream is part of a capture sequence that has been invalidated, but not terminated

Function Documentation

◆ hipGraphAddDependencies()

hipError_t hipGraphAddDependencies	(	hipGraph_t	graph,
		const hipGraphNode_t *	from,
		const hipGraphNode_t *	to,
		size_t	numDependencies
	)

Adds dependency edges to a graph.

Parameters

[in]	graph	- instance of the graph to add dependencies.
[in]	from	- pointer to the graph nodes with dependenties to add from.
[in]	to	- pointer to the graph nodes to add dependenties to.
[in]	numDependencies	- the number of dependencies to add.

Returns: hipSuccess, hipErrorInvalidValue

Warning: : This API is marked as beta, meaning, while this is feature complete, it is still open to changes and may have outstanding issues.

◆ hipGraphAddEmptyNode()

hipError_t hipGraphAddEmptyNode	(	hipGraphNode_t *	pGraphNode,
		hipGraph_t	graph,
		const hipGraphNode_t *	pDependencies,
		size_t	numDependencies
	)

Creates an empty node and adds it to a graph.

Parameters

[out]	pGraphNode	- pointer to the graph node to create and add to the graph.
[in,out]	graph	- instane of the graph the node is add to.
[in]	pDependencies	- const pointer to the node dependenties.
[in]	numDependencies	- the number of dependencies.

Returns: hipSuccess, hipErrorInvalidValue

Warning: : This API is marked as beta, meaning, while this is feature complete, it is still open to changes and may have outstanding issues.

◆ hipGraphAddKernelNode()

hipError_t hipGraphAddKernelNode	(	hipGraphNode_t *	pGraphNode,
		hipGraph_t	graph,
		const hipGraphNode_t *	pDependencies,
		size_t	numDependencies,
		const hipKernelNodeParams *	pNodeParams
	)

Creates a kernel execution node and adds it to a graph.

Parameters

[out]	pGraphNode	- pointer to graph node to create.
[in,out]	graph	- instance of graph to add the created node.
[in]	pDependencies	- pointer to the dependencies on the kernel execution node.
[in]	numDependencies	- the number of the dependencies.
[in]	pNodeParams	- pointer to the parameters to the kernel execution node on the GPU.

Returns: hipSuccess, hipErrorInvalidValue, #hipErrorInvalidDeviceFunction

Warning: : This API is marked as beta, meaning, while this is feature complete, it is still open to changes and may have outstanding issues.

◆ hipGraphAddMemcpyNode()

hipError_t hipGraphAddMemcpyNode	(	hipGraphNode_t *	pGraphNode,
		hipGraph_t	graph,
		const hipGraphNode_t *	pDependencies,
		size_t	numDependencies,
		const hipMemcpy3DParms *	pCopyParams
	)

Creates a memcpy node and adds it to a graph.

Parameters

[out]	pGraphNode	- pointer to graph node to create.
[in,out]	graph	- instance of graph to add the created node.
[in]	pDependencies	- const pointer to the dependencies on the kernel execution node.
[in]	numDependencies	- the number of the dependencies.
[in]	pCopyParams	- const pointer to the parameters for the memory copy.

Returns: hipSuccess, hipErrorInvalidValue

Warning: : This API is marked as beta, meaning, while this is feature complete, it is still open to changes and may have outstanding issues.

◆ hipGraphAddMemcpyNode1D()

hipError_t hipGraphAddMemcpyNode1D	(	hipGraphNode_t *	pGraphNode,
		hipGraph_t	graph,
		const hipGraphNode_t *	pDependencies,
		size_t	numDependencies,
		void *	dst,
		const void *	src,
		size_t	count,
		hipMemcpyKind	kind
	)

Creates a 1D memcpy node and adds it to a graph.

Parameters

[out]	pGraphNode	- pointer to graph node to create.
[in,out]	graph	- instance of the graph to add the created node.
[in]	pDependencies	- const pointer to the dependencies on the kernel execution node.
[in]	numDependencies	- the number of the dependencies.
[in]	dst	- pointer to memory address to the destination.
[in]	src	- pointer to memory address to the source.
[in]	count	- the size of the memory to copy.
[in]	kind	- the type of memory copy.

Returns: hipSuccess, hipErrorInvalidValue

Warning: : This API is marked as beta, meaning, while this is feature complete, it is still open to changes and may have outstanding issues.

◆ hipGraphAddMemsetNode()

hipError_t hipGraphAddMemsetNode	(	hipGraphNode_t *	pGraphNode,
		hipGraph_t	graph,
		const hipGraphNode_t *	pDependencies,
		size_t	numDependencies,
		const hipMemsetParams *	pMemsetParams
	)

Creates a memset node and adds it to a graph.

Parameters

[out]	pGraphNode	- pointer to the graph node to create.
[in,out]	graph	- instance of the graph to add the created node.
[in]	pDependencies	- const pointer to the dependencies on the kernel execution node.
[in]	numDependencies	- the number of the dependencies.
[in]	pMemsetParams	- const pointer to the parameters for the memory set.

Returns: hipSuccess, hipErrorInvalidValue

Warning: : This API is marked as beta, meaning, while this is feature complete, it is still open to changes and may have outstanding issues.

◆ hipGraphCreate()

hipError_t hipGraphCreate	(	hipGraph_t *	pGraph,
		unsigned int	flags
	)

Creates a graph.

Parameters

[out]	pGraph	- pointer to graph to create.
[in]	flags	- flags for graph creation, must be 0.

Returns: hipSuccess.

Warning: : This API is marked as beta, meaning, while this is feature complete, it is still open to changes and may have outstanding issues.

◆ hipGraphDestroy()

hipError_t hipGraphDestroy ( hipGraph_t graph )

Destroys a graph.

Parameters

[in] graph - instance of graph to destroy.

Returns: hipSuccess.

Warning: : This API is marked as beta, meaning, while this is feature complete, it is still open to changes and may have outstanding issues.

◆ hipGraphExecDestroy()

hipError_t hipGraphExecDestroy ( hipGraphExec_t pGraphExec )

Destroys an executable graph.

Parameters

[in] pGraphExec - instance of executable graph to destry.

Returns: hipSuccess.

Warning: : This API is marked as beta, meaning, while this is feature complete, it is still open to changes and may have outstanding issues.

◆ hipGraphExecKernelNodeSetParams()

hipError_t hipGraphExecKernelNodeSetParams	(	hipGraphExec_t	hGraphExec,
		hipGraphNode_t	node,
		const hipKernelNodeParams *	pNodeParams
	)

Sets the parameters for a kernel node in the given graphExec.

Parameters

[in]	hGraphExec	- instance of the executable graph with the node.
[in]	node	- instance of the node to set parameters to.
[in]	pNodeParams	- const pointer to the kernel node parameters.

Returns: hipSuccess, hipErrorInvalidValue

Warning: : This API is marked as beta, meaning, while this is feature complete, it is still open to changes and may have outstanding issues.

◆ hipGraphGetNodes()

hipError_t hipGraphGetNodes	(	hipGraph_t	graph,
		hipGraphNode_t *	nodes,
		size_t *	numNodes
	)

Returns graph nodes.

Parameters

[in]	graph	- instance of graph to get the nodes.
[out]	nodes	- pointer to the graph nodes.
[out]	numNodes	- the number of graph nodes.

Returns: hipSuccess, hipErrorInvalidValue

Warning: : This API is marked as beta, meaning, while this is feature complete, it is still open to changes and may have outstanding issues.

◆ hipGraphGetRootNodes()

hipError_t hipGraphGetRootNodes	(	hipGraph_t	graph,
		hipGraphNode_t *	pRootNodes,
		size_t *	pNumRootNodes
	)

Returns graph's root nodes.

Parameters

[in]	graph	- instance of the graph to get the nodes.
[out]	pRootNodes	- pointer to the graph's root nodes.
[out]	pNumRootNodes	- the number of graph's root nodes.

Returns: hipSuccess, hipErrorInvalidValue

Warning: : This API is marked as beta, meaning, while this is feature complete, it is still open to changes and may have outstanding issues.

◆ hipGraphInstantiate()

hipError_t hipGraphInstantiate	(	hipGraphExec_t *	pGraphExec,
		hipGraph_t	graph,
		hipGraphNode_t *	pErrorNode,
		char *	pLogBuffer,
		size_t	bufferSize
	)

Creates an executable graph from a graph.

Parameters

[out]	pGraphExec	- pointer to instantiated executable graph to create.
[in]	graph	- instance of graph to instantiate.
[out]	pErrorNode	- pointer to error node in case error occured in graph instantiation, it could modify the correponding node.
[out]	pLogBuffer	- pointer to log buffer.
[in]	bufferSize	- the size of log buffer.

Returns: hipSuccess, #hipErrorOutOfMemory.

Warning: : This API is marked as beta, meaning, while this is feature complete, it is still open to changes and may have outstanding issues.

◆ hipGraphKernelNodeGetParams()

hipError_t hipGraphKernelNodeGetParams	(	hipGraphNode_t	node,
		hipKernelNodeParams *	pNodeParams
	)

Gets kernel node's parameters.

Parameters

[in]	node	- instance of the node to get parameters from.
[out]	pNodeParams	- pointer to the parameters

Returns: hipSuccess, hipErrorInvalidValue

Warning: : This API is marked as beta, meaning, while this is feature complete, it is still open to changes and may have outstanding issues.

◆ hipGraphKernelNodeSetParams()

hipError_t hipGraphKernelNodeSetParams	(	hipGraphNode_t	node,
		const hipKernelNodeParams *	pNodeParams
	)

Sets a kernel node's parameters.

Parameters

[in]	node	- instance of the node to set parameters to.
[in]	pNodeParams	- const pointer to the parameters.

Returns: hipSuccess, hipErrorInvalidValue

Warning: : This API is marked as beta, meaning, while this is feature complete, it is still open to changes and may have outstanding issues.

◆ hipGraphLaunch()

hipError_t hipGraphLaunch	(	hipGraphExec_t	graphExec,
		hipStream_t	stream
	)

launches an executable graph in a stream

Parameters

[in]	graphExec	- instance of executable graph to launch.
[in]	stream	- instance of stream in which to launch executable graph.

Returns: hipSuccess, #hipErrorOutOfMemory, #hipErrorInvalidHandle, hipErrorInvalidValue

Warning: : This API is marked as beta, meaning, while this is feature complete, it is still open to changes and may have outstanding issues.

◆ hipGraphMemcpyNodeGetParams()

hipError_t hipGraphMemcpyNodeGetParams	(	hipGraphNode_t	node,
		hipMemcpy3DParms *	pNodeParams
	)

Gets a memcpy node's parameters.

Parameters

[in]	node	- instance of the node to get parameters from.
[out]	pNodeParams	- pointer to the parameters.

Returns: hipSuccess, hipErrorInvalidValue

Warning: : This API is marked as beta, meaning, while this is feature complete, it is still open to changes and may have outstanding issues.

◆ hipGraphMemcpyNodeSetParams()

hipError_t hipGraphMemcpyNodeSetParams	(	hipGraphNode_t	node,
		const hipMemcpy3DParms *	pNodeParams
	)

Sets a memcpy node's parameters.

Parameters

[in]	node	- instance of the node to set parameters to.
[in]	pNodeParams	- const pointer to the parameters.

Returns: hipSuccess, hipErrorInvalidValue

Warning: : This API is marked as beta, meaning, while this is feature complete, it is still open to changes and may have outstanding issues.

◆ hipGraphMemsetNodeGetParams()

hipError_t hipGraphMemsetNodeGetParams	(	hipGraphNode_t	node,
		hipMemsetParams *	pNodeParams
	)

Gets a memset node's parameters.

Parameters

[in]	node	- instane of the node to get parameters from.
[out]	pNodeParams	- pointer to the parameters.

Returns: hipSuccess, hipErrorInvalidValue

Warning: : This API is marked as beta, meaning, while this is feature complete, it is still open to changes and may have outstanding issues.

◆ hipGraphMemsetNodeSetParams()

hipError_t hipGraphMemsetNodeSetParams	(	hipGraphNode_t	node,
		const hipMemsetParams *	pNodeParams
	)

Sets a memset node's parameters.

Parameters

[in]	node	- instance of the node to set parameters to.
[out]	pNodeParams	- pointer to the parameters.

Returns: hipSuccess, hipErrorInvalidValue

Warning: : This API is marked as beta, meaning, while this is feature complete, it is still open to changes and may have outstanding issues.

◆ hipStreamBeginCapture()

hipError_t hipStreamBeginCapture	(	hipStream_t	stream,
		hipStreamCaptureMode	mode
	)

Begins graph capture on a stream.

Parameters

[in]	stream	- Stream to initiate capture.
[in]	mode	- Controls the interaction of this capture sequence with other API calls that are not safe.

Returns: hipSuccess, hipErrorInvalidValue

Warning: : This API is marked as beta, meaning, while this is feature complete, it is still open to changes and may have outstanding issues.

◆ hipStreamEndCapture()

hipError_t hipStreamEndCapture	(	hipStream_t	stream,
		hipGraph_t *	pGraph
	)

Ends capture on a stream, returning the captured graph.

Parameters

[in]	stream	- Stream to end capture.
[out]	pGraph	- returns the graph captured.

Returns: hipSuccess, hipErrorInvalidValue

Warning: : This API is marked as beta, meaning, while this is feature complete, it is still open to changes and may have outstanding issues.

Classes

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ hipGraph_t

◆ hipGraphExec_t

◆ hipGraphNode_t

Enumeration Type Documentation

◆ hipGraphExecUpdateResult

◆ hipGraphNodeType

◆ hipStreamCaptureStatus

Function Documentation

◆ hipGraphAddDependencies()

◆ hipGraphAddEmptyNode()

◆ hipGraphAddKernelNode()

◆ hipGraphAddMemcpyNode()

◆ hipGraphAddMemcpyNode1D()

◆ hipGraphAddMemsetNode()

◆ hipGraphCreate()

◆ hipGraphDestroy()

◆ hipGraphExecDestroy()

◆ hipGraphExecKernelNodeSetParams()

◆ hipGraphGetNodes()

◆ hipGraphGetRootNodes()

◆ hipGraphInstantiate()

◆ hipGraphKernelNodeGetParams()

◆ hipGraphKernelNodeSetParams()

◆ hipGraphLaunch()

◆ hipGraphMemcpyNodeGetParams()

◆ hipGraphMemcpyNodeSetParams()

◆ hipGraphMemsetNodeGetParams()

◆ hipGraphMemsetNodeSetParams()

◆ hipStreamBeginCapture()

◆ hipStreamEndCapture()