HIP: Heterogenous-computing Interface for Portability
Classes | Typedefs | Enumerations | Functions
Graph Management

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

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

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

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.