API Reference ¶

hipError_t hipRuntimeGetVersion(int *runtimeVersion)¶

Returns the approximate HIP Runtime version.

See also

hipDriverGetVersion

Warning

The version definition of HIP runtime is different from CUDA. On AMD platform, the function returns HIP runtime version, while on NVIDIA platform, it returns CUDA runtime version. And there is no mapping/correlation between HIP version and CUDA version.

Parameters:

runtimeVersion – [out]

Returns:

hipError_t hipDeviceGet(hipDevice_t *device, int ordinal)¶

Returns a handle to a compute device.

Parameters:

device – [out]
ordinal – [in]

Returns:

hipError_t hipDeviceComputeCapability(int *major, int *minor, hipDevice_t device)¶

Returns the compute capability of the device.

Parameters:

major – [out]
minor – [out]
device – [in]

Returns:

hipError_t hipDeviceGetName(char *name, int len, hipDevice_t device)¶

Returns an identifer string for the device.

Parameters:

name – [out]
len – [in]
device – [in]

Returns:

hipSuccess, hipErrorInvalidDevice, hipErrorInvalidValue, hipErrorNotInitialized, hipErrorDeinitialized

hipError_t hipDeviceGetUuid(hipUUID *uuid, hipDevice_t device)¶

Returns an UUID for the device.[BETA].

Parameters:

uuid – [out]
device – [in] This API is marked as beta, meaning, while this is feature complete, it is still open to changes and may have outstanding issues.

Returns:

hipError_t hipDeviceGetP2PAttribute(int *value, hipDeviceP2PAttr attr, int srcDevice, int dstDevice)¶

Returns a value for attr of link between two devices.

Parameters:

value – [out]
attr – [in]
srcDevice – [in]
dstDevice – [in]

Returns:

hipError_t hipDeviceGetPCIBusId(char *pciBusId, int len, int device)¶

Returns a PCI Bus Id string for the device, overloaded to take int device ID.

Parameters:

pciBusId – [out]
len – [in]
device – [in]

Returns:

hipSuccess, hipErrorInvalidDevice, hipErrorInvalidValue

hipError_t hipDeviceGetByPCIBusId(int *device, const char *pciBusId)¶

Returns a handle to a compute device.

Parameters:

device – [out] handle
PCI – [in] Bus ID

Returns:

hipError_t hipDeviceTotalMem(size_t *bytes, hipDevice_t device)¶

Returns the total amount of memory on the device.

Parameters:

bytes – [out]
device – [in]

Returns:

hipSetDevice, hipDeviceReset

hipError_t hipDeviceSynchronize(void)¶

Waits on all active streams on current device.

When this command is invoked, the host thread gets blocked until all the commands associated with streams associated with the device. HIP does not support multiple blocking modes (yet!).

See also

Returns:: hipSuccess

hipError_t hipDeviceReset(void)¶

The state of current device is discarded and updated to a fresh state.

Calling this function deletes all streams created, memory allocated, kernels running, events created. Make sure that no other thread is using the device or streams, memory, kernels, events associated with the current device.

See also

hipDeviceSynchronize

Returns:: hipSuccess

hipError_t hipSetDevice(int deviceId)¶

Set default device to be used for subsequent hip API calls from this thread.

Sets device as the default device for the calling host thread. Valid device id’s are 0… (hipGetDeviceCount()-1).

Many HIP APIs implicitly use the “default device” :

Any device memory subsequently allocated from this host thread (using hipMalloc) will be allocated on device.
Any streams or events created from this host thread will be associated with device.
Any kernels launched from this host thread (using hipLaunchKernel) will be executed on device (unless a specific stream is specified, in which case the device associated with that stream will be used).

This function may be called from any host thread. Multiple host threads may use the same device. This function does no synchronization with the previous or new device, and has very little runtime overhead. Applications can use hipSetDevice to quickly switch the default device before making a HIP runtime call which uses the default device.

The default device is stored in thread-local-storage for each thread. Thread-pool implementations may inherit the default device of the previous thread. A good practice is to always call hipSetDevice at the start of HIP coding sequency to establish a known standard device.

See also

hipGetDevice, hipGetDeviceCount

Parameters:

deviceId – [in] Valid device in range 0…hipGetDeviceCount().

Returns:

hipSuccess, hipErrorInvalidDevice, #hipErrorDeviceAlreadyInUse

hipError_t hipGetDevice(int *deviceId)¶

Return the default device id for the calling host thread.

HIP maintains an default device for each thread using thread-local-storage. This device is used implicitly for HIP runtime APIs called by this thread. hipGetDevice returns in * device the default device for the calling host thread.

See also

hipSetDevice, hipGetDevicesizeBytes

Parameters:

device – [out] *device is written with the default device

Returns:

hipSuccess, hipErrorInvalidDevice, hipErrorInvalidValue

hipError_t hipGetDeviceCount(int *count)¶

Return number of compute-capable devices.

Returns in *count the number of devices that have ability to run compute commands. If there are no such devices, then hipGetDeviceCount will return hipErrorNoDevice. If 1 or more devices can be found, then hipGetDeviceCount returns hipSuccess.

Parameters:

[output] – count Returns number of compute-capable devices.

Returns:

hipSuccess, hipErrorNoDevice

hipError_t hipDeviceGetAttribute(int *pi, hipDeviceAttribute_t attr, int deviceId)¶

Query for a specific device attribute.

Parameters:

pi – [out] pointer to value to return
attr – [in] attribute to query
deviceId – [in] which device to query for information

Returns:

hipSuccess, hipErrorInvalidDevice, hipErrorInvalidValue

hipError_t hipDeviceGetDefaultMemPool(hipMemPool_t *mem_pool, int device)¶

Returns the default memory pool of the specified device.

Warning

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

Parameters:

mem_pool – [out] Default memory pool to return
device – [in] Device index for query the default memory pool

Returns:

#chipSuccess, hipErrorInvalidDevice, hipErrorInvalidValue, hipErrorNotSupported

hipError_t hipDeviceSetMemPool(int device, hipMemPool_t mem_pool)¶

Sets the current memory pool of a device.

The memory pool must be local to the specified device. hipMallocAsync allocates from the current mempool of the provided stream’s device. By default, a device’s current memory pool is its default memory pool.

Note

Use hipMallocFromPoolAsync for asynchronous memory allocations from a device different than the one the stream runs on.

Warning

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

Parameters:

device – [in] Device index for the update
mem_pool – [in] Memory pool for update as the current on the specified device

Returns:

hipSuccess, hipErrorInvalidValue, hipErrorInvalidDevice, hipErrorNotSupported

hipError_t hipDeviceGetMemPool(hipMemPool_t *mem_pool, int device)¶

Gets the current memory pool for the specified device.

Returns the last pool provided to hipDeviceSetMemPool for this device or the device’s default memory pool if hipDeviceSetMemPool has never been called. By default the current mempool is the default mempool for a device, otherwise the returned pool must have been set with hipDeviceSetMemPool.

Warning

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

Parameters:

mem_pool – [out] Current memory pool on the specified device
device – [in] Device index to query the current memory pool

Returns:

hipSuccess, hipErrorInvalidValue, hipErrorNotSupported

hipError_t hipGetDeviceProperties(hipDeviceProp_t *prop, int deviceId)¶

Returns device properties.

Bug:

HCC always returns 0 for maxThreadsPerMultiProcessor

HCC always returns 0 for regsPerBlock

HCC always returns 0 for l2CacheSize

Populates hipGetDeviceProperties with information for the specified device.

Parameters:

prop – [out] written with device properties
deviceId – [in] which device to query for information

Returns:

hipSuccess, hipErrorUnsupportedLimit, hipErrorInvalidValue

hipError_t hipDeviceSetCacheConfig(hipFuncCache_t cacheConfig)¶

Set L1/Shared cache partition.

Parameters:

cacheConfig – [in]

Returns:

hipSuccess, hipErrorNotInitialized Note: AMD devices and some Nvidia GPUS do not support reconfigurable cache. This hint is ignored on those architectures.

hipError_t hipDeviceGetCacheConfig(hipFuncCache_t *cacheConfig)¶

Get Cache configuration for a specific Device.

Parameters:

cacheConfig – [out]

Returns:

hipSuccess, hipErrorNotInitialized Note: AMD devices and some Nvidia GPUS do not support reconfigurable cache. This hint is ignored on those architectures.

hipError_t hipDeviceGetLimit(size_t *pValue, enum hipLimit_t limit)¶

Get Resource limits of current device.

Parameters:

pValue – [out]
limit – [in]

Returns:

hipSuccess, hipErrorUnsupportedLimit, hipErrorInvalidValue Note: Currently, only hipLimitMallocHeapSize is available

hipError_t hipDeviceSetLimit(enum hipLimit_t limit, size_t value)¶

Set Resource limits of current device.

Parameters:

limit – [in]
value – [in]

Returns:

hipError_t hipDeviceGetSharedMemConfig(hipSharedMemConfig *pConfig)¶

Returns bank width of shared memory for current device.

Note: AMD devices and some Nvidia GPUS do not support shared cache banking, and the hint is ignored on those architectures.

Parameters:

pConfig – [out]

Returns:

hipSuccess, hipErrorInvalidValue, hipErrorNotInitialized

hipError_t hipGetDeviceFlags(unsigned int *flags)¶

Gets the flags set for current device.

Parameters:

flags – [out]

Returns:

hipSuccess, hipErrorInvalidDevice, hipErrorInvalidValue

hipError_t hipDeviceSetSharedMemConfig(hipSharedMemConfig config)¶

The bank width of shared memory on current device is set.

Note: AMD devices and some Nvidia GPUS do not support shared cache banking, and the hint is ignored on those architectures.

Parameters:

config – [in]

Returns:

hipSuccess, hipErrorInvalidValue, hipErrorNotInitialized

hipError_t hipSetDeviceFlags(unsigned flags)¶

The current device behavior is changed according the flags passed.

hipDeviceMapHost : Allow mapping host memory. On ROCM, this is always allowed and the flag is ignored. hipDeviceLmemResizeToMax :

Warning

ROCm silently ignores this flag.

Parameters:

flags – [in] The schedule flags impact how HIP waits for the completion of a command running on a device. hipDeviceScheduleSpin : HIP runtime will actively spin in the thread which submitted the work until the command completes. This offers the lowest latency, but will consume a CPU core and may increase power. hipDeviceScheduleYield : The HIP runtime will yield the CPU to system so that other tasks can use it. This may increase latency to detect the completion but will consume less power and is friendlier to other tasks in the system. hipDeviceScheduleBlockingSync : On ROCm platform, this is a synonym for hipDeviceScheduleYield. hipDeviceScheduleAuto : Use a hueristic to select between Spin and Yield modes. If the number of HIP contexts is greater than the number of logical processors in the system, use Spin scheduling. Else use Yield scheduling.

Returns:

hipSuccess, hipErrorInvalidDevice, hipErrorSetOnActiveProcess

hipError_t hipChooseDevice(int *device, const hipDeviceProp_t *prop)¶

Device which matches hipDeviceProp_t is returned.

Parameters:

device – [out] ID
device – [in] properties pointer

Returns:

hipSuccess, hipErrorInvalidConfiguration, hipErrorInvalidValue

hipError_t hipExtGetLinkTypeAndHopCount(int device1, int device2, uint32_t *linktype, uint32_t *hopcount)¶

Returns the link type and hop count between two devices.

Queries and returns the HSA link type and the hop count between the two specified devices.

Parameters:

device1 – [in] Ordinal for device1
device2 – [in] Ordinal for device2
linktype – [out] Returns the link type (See hsa_amd_link_info_type_t) between the two devices
hopcount – [out] Returns the hop count between the two devices

Returns:

hipSuccess, #hipInvalidDevice, hipErrorRuntimeOther

hipError_t hipIpcGetMemHandle(hipIpcMemHandle_t *handle, void *devPtr)¶

Gets an interprocess memory handle for an existing device memory allocation.

Takes a pointer to the base of an existing device memory allocation created with hipMalloc and exports it for use in another process. This is a lightweight operation and may be called multiple times on an allocation without adverse effects.

If a region of memory is freed with hipFree and a subsequent call to hipMalloc returns memory with the same device address, hipIpcGetMemHandle will return a unique handle for the new memory.

Parameters:

handle – - Pointer to user allocated hipIpcMemHandle to return the handle in.
devPtr – - Base pointer to previously allocated device memory

Returns:

hipSuccess, hipErrorInvalidHandle, hipErrorOutOfMemory, hipErrorMapFailed,

hipError_t hipIpcOpenMemHandle(void **devPtr, hipIpcMemHandle_t handle, unsigned int flags)¶

Opens an interprocess memory handle exported from another process and returns a device pointer usable in the local process.

Maps memory exported from another process with hipIpcGetMemHandle into the current device address space. For contexts on different devices hipIpcOpenMemHandle can attempt to enable peer access between the devices as if the user called hipDeviceEnablePeerAccess. This behavior is controlled by the hipIpcMemLazyEnablePeerAccess flag. hipDeviceCanAccessPeer can determine if a mapping is possible.

Contexts that may open hipIpcMemHandles are restricted in the following way. hipIpcMemHandles from each device in a given process may only be opened by one context per device per other process.

Memory returned from hipIpcOpenMemHandle must be freed with hipIpcCloseMemHandle.

Calling hipFree on an exported memory region before calling hipIpcCloseMemHandle in the importing context will result in undefined behavior.

Note

During multiple processes, using the same memory handle opened by the current context, there is no guarantee that the same device poiter will be returned in *devPtr. This is diffrent from CUDA.

Parameters:

devPtr – - Returned device pointer
handle – - hipIpcMemHandle to open
flags – - Flags for this operation. Must be specified as hipIpcMemLazyEnablePeerAccess

Returns:

hipSuccess, hipErrorMapFailed, hipErrorInvalidHandle, hipErrorTooManyPeers

hipError_t hipIpcCloseMemHandle(void *devPtr)¶

Close memory mapped with hipIpcOpenMemHandle.

Unmaps memory returnd by hipIpcOpenMemHandle. The original allocation in the exporting process as well as imported mappings in other processes will be unaffected.

Any resources used to enable peer access will be freed if this is the last mapping using them.

Parameters:

devPtr – - Device pointer returned by hipIpcOpenMemHandle

Returns:

hipSuccess, hipErrorMapFailed, hipErrorInvalidHandle,

hipError_t hipIpcGetEventHandle(hipIpcEventHandle_t *handle, hipEvent_t event)¶

Gets an opaque interprocess handle for an event.

This opaque handle may be copied into other processes and opened with hipIpcOpenEventHandle. Then hipEventRecord, hipEventSynchronize, hipStreamWaitEvent and hipEventQuery may be used in either process. Operations on the imported event after the exported event has been freed with hipEventDestroy will result in undefined behavior.

Parameters:

handle – [out] Pointer to hipIpcEventHandle to return the opaque event handle
event – [in] Event allocated with hipEventInterprocess and hipEventDisableTiming flags

Returns:

hipError_t hipIpcOpenEventHandle(hipEvent_t *event, hipIpcEventHandle_t handle)¶

Opens an interprocess event handles.

Opens an interprocess event handle exported from another process with cudaIpcGetEventHandle. The returned hipEvent_t behaves like a locally created event with the hipEventDisableTiming flag specified. This event need be freed with hipEventDestroy. Operations on the imported event after the exported event has been freed with hipEventDestroy will result in undefined behavior. If the function is called within the same process where handle is returned by hipIpcGetEventHandle, it will return hipErrorInvalidContext.

Parameters:

event – [out] Pointer to hipEvent_t to return the event
handle – [in] The opaque interprocess handle to open

Returns:

hipSuccess, hipErrorInvalidValue, hipErrorInvalidContext

hipError_t hipFuncSetAttribute(const void *func, hipFuncAttribute attr, int value)¶

Set attribute for a specific function.

Note: AMD devices and some Nvidia GPUS do not support shared cache banking, and the hint is ignored on those architectures.

Parameters:

func; – [in]
attr; – [in]
value; – [in]

Returns:

hipSuccess, hipErrorInvalidDeviceFunction, hipErrorInvalidValue

hipError_t hipFuncSetCacheConfig(const void *func, hipFuncCache_t config)¶

Set Cache configuration for a specific function.

Parameters:

config; – [in]

Returns:

hipSuccess, hipErrorNotInitialized Note: AMD devices and some Nvidia GPUS do not support reconfigurable cache. This hint is ignored on those architectures.

hipError_t hipFuncSetSharedMemConfig(const void *func, hipSharedMemConfig config)¶

Set shared memory configuation for a specific function.

Note: AMD devices and some Nvidia GPUS do not support shared cache banking, and the hint is ignored on those architectures.

Parameters:

func – [in]
config – [in]

Returns:

hipSuccess, hipErrorInvalidDeviceFunction, hipErrorInvalidValue

hipError_t hipGetLastError(void)¶

Return last error returned by any HIP runtime API call and resets the stored error code to hipSuccess.

Returns the last error that has been returned by any of the runtime calls in the same host thread, and then resets the saved error to hipSuccess.

See also

hipGetErrorString, hipGetLastError, hipPeakAtLastError, hipError_t

Returns:: return code from last HIP called from the active host thread

hipError_t hipPeekAtLastError(void)¶

Return last error returned by any HIP runtime API call.

Returns the last error that has been returned by any of the runtime calls in the same host thread. Unlike hipGetLastError, this function does not reset the saved error code.

See also

hipGetErrorString, hipGetLastError, hipPeakAtLastError, hipError_t

Returns:: hipSuccess

const char *hipGetErrorName(hipError_t hip_error)¶

Return hip error as text string form.

See also

hipGetErrorString, hipGetLastError, hipPeakAtLastError, hipError_t

Parameters:

hip_error – Error code to convert to name.

Returns:

const char pointer to the NULL-terminated error name

const char *hipGetErrorString(hipError_t hipError)¶

Return handy text string message to explain the error which occurred.

See also

hipGetErrorName, hipGetLastError, hipPeakAtLastError, hipError_t

Parameters:

hipError – Error code to convert to string.

Returns:

const char pointer to the NULL-terminated error string

hipError_t hipDrvGetErrorName(hipError_t hipError, const char **errorString)¶

Return hip error as text string form.

See also

hipGetErrorName, hipGetLastError, hipPeakAtLastError, hipError_t

Parameters:

hipError – [in] Error code to convert to string.
const – [out] char pointer to the NULL-terminated error string

Returns:

hipError_t hipDrvGetErrorString(hipError_t hipError, const char **errorString)¶

Return handy text string message to explain the error which occurred.

See also

hipGetErrorName, hipGetLastError, hipPeakAtLastError, hipError_t

Parameters:

hipError – [in] Error code to convert to string.
const – [out] char pointer to the NULL-terminated error string

Returns:

hipError_t hipStreamCreate(hipStream_t *stream)¶

Create an asynchronous stream.

Create a new asynchronous stream. stream returns an opaque handle that can be used to reference the newly created stream in subsequent hipStream* commands. The stream is allocated on the heap and will remain allocated even if the handle goes out-of-scope. To release the memory used by the stream, applicaiton must call hipStreamDestroy.

Parameters:

stream – [inout] Valid pointer to hipStream_t. This function writes the memory with the newly created stream.

Returns:

Returns:

hipError_t hipStreamCreateWithFlags(hipStream_t *stream, unsigned int flags)¶

Create an asynchronous stream.

Create a new asynchronous stream. stream returns an opaque handle that can be used to reference the newly created stream in subsequent hipStream* commands. The stream is allocated on the heap and will remain allocated even if the handle goes out-of-scope. To release the memory used by the stream, applicaiton must call hipStreamDestroy. Flags controls behavior of the stream. See hipStreamDefault, hipStreamNonBlocking.

Parameters:

stream – [inout] Pointer to new stream
flags – [in] to control stream creation.

Returns:

hipError_t hipStreamCreateWithPriority(hipStream_t *stream, unsigned int flags, int priority)¶

Create an asynchronous stream with the specified priority.

Create a new asynchronous stream with the specified priority. stream returns an opaque handle that can be used to reference the newly created stream in subsequent hipStream* commands. The stream is allocated on the heap and will remain allocated even if the handle goes out-of-scope. To release the memory used by the stream, applicaiton must call hipStreamDestroy. Flags controls behavior of the stream. See hipStreamDefault, hipStreamNonBlocking.

Parameters:

stream – [inout] Pointer to new stream
flags – [in] to control stream creation.
priority – [in] of the stream. Lower numbers represent higher priorities.

Returns:

hipSuccess hipErrorInvalidHandle

hipError_t hipDeviceGetStreamPriorityRange(int *leastPriority, int *greatestPriority)¶

Returns numerical values that correspond to the least and greatest stream priority.

Returns in *leastPriority and *greatestPriority the numerical values that correspond to the least and greatest stream priority respectively. Stream priorities follow a convention where lower numbers imply greater priorities. The range of meaningful stream priorities is given by [*greatestPriority, *leastPriority]. If the user attempts to create a stream with a priority value that is outside the the meaningful range as specified by this API, the priority is automatically clamped to within the valid range.

Parameters:

leastPriority – [inout] pointer in which value corresponding to least priority is returned.
greatestPriority – [inout] pointer in which value corresponding to greatest priority is returned.

hipError_t hipStreamDestroy(hipStream_t stream)¶

Destroys the specified stream.

If commands are still executing on the specified stream, some may complete execution before the queue is deleted.

The queue may be destroyed while some commands are still inflight, or may wait for all commands queued to the stream before destroying it.

Parameters:

stream – [inout] Valid pointer to hipStream_t. This function writes the memory with the newly created stream.

Returns:

hipError_t hipStreamQuery(hipStream_t stream)¶

Return hipSuccess if all of the operations in the specified stream have completed, or hipErrorNotReady if not.

This is thread-safe and returns a snapshot of the current state of the queue. However, if other host threads are sending work to the stream, the status may change immediately after the function is called. It is typically used for debug.

Parameters:

stream – [in] stream to query

Returns:

hipSuccess, hipErrorNotReady, hipErrorInvalidHandle

hipError_t hipStreamSynchronize(hipStream_t stream)¶

Wait for all commands in stream to complete.

This command is host-synchronous : the host will block until the specified stream is empty.

This command follows standard null-stream semantics. Specifically, specifying the null stream will cause the command to wait for other streams on the same device to complete all pending operations.

This command honors the hipDeviceLaunchBlocking flag, which controls whether the wait is active or blocking.

Parameters:

stream – [in] stream identifier.

Returns:

hipSuccess, hipErrorInvalidHandle

hipError_t hipStreamWaitEvent(hipStream_t stream, hipEvent_t event, unsigned int flags)¶

Make the specified compute stream wait for an event.

This function inserts a wait operation into the specified stream. All future work submitted to stream will wait until event reports completion before beginning execution.

This function only waits for commands in the current stream to complete. Notably,, this function does not impliciy wait for commands in the default stream to complete, even if the specified stream is created with hipStreamNonBlocking = 0.

Parameters:

stream – [in] stream to make wait.
event – [in] event to wait on
flags – [in] control operation [must be 0]

Returns:

hipSuccess, hipErrorInvalidHandle

hipError_t hipStreamGetFlags(hipStream_t stream, unsigned int *flags)¶

Return flags associated with this stream.

Return flags associated with this stream in *flags.

See also

hipStreamCreateWithFlags

Parameters:

stream – [in] stream to be queried
flags – [inout] Pointer to an unsigned integer in which the stream’s flags are returned

Returns:

hipSuccess, hipErrorInvalidValue, hipErrorInvalidHandle

Returns:

hipSuccess hipErrorInvalidValue hipErrorInvalidHandle

hipError_t hipStreamGetPriority(hipStream_t stream, int *priority)¶

Query the priority of a stream.

Query the priority of a stream. The priority is returned in in priority.

See also

hipStreamCreateWithFlags

Parameters:

stream – [in] stream to be queried
priority – [inout] Pointer to an unsigned integer in which the stream’s priority is returned

Returns:

hipSuccess, hipErrorInvalidValue, hipErrorInvalidHandle

Returns:

hipSuccess hipErrorInvalidValue hipErrorInvalidHandle

hipError_t hipExtStreamCreateWithCUMask(hipStream_t *stream, uint32_t cuMaskSize, const uint32_t *cuMask)¶

Create an asynchronous stream with the specified CU mask.

Create a new asynchronous stream with the specified CU mask. stream returns an opaque handle that can be used to reference the newly created stream in subsequent hipStream* commands. The stream is allocated on the heap and will remain allocated even if the handle goes out-of-scope. To release the memory used by the stream, application must call hipStreamDestroy.

Parameters:

stream – [inout] Pointer to new stream
cuMaskSize – [in] Size of CU mask bit array passed in.
cuMask – [in] Bit-vector representing the CU mask. Each active bit represents using one CU. The first 32 bits represent the first 32 CUs, and so on. If its size is greater than physical CU number (i.e., multiProcessorCount member of hipDeviceProp_t), the extra elements are ignored. It is user’s responsibility to make sure the input is meaningful.

Returns:

hipSuccess, hipErrorInvalidHandle, hipErrorInvalidValue

hipError_t hipExtStreamGetCUMask(hipStream_t stream, uint32_t cuMaskSize, uint32_t *cuMask)¶

Get CU mask associated with an asynchronous stream.

Parameters:

stream – [in] stream to be queried
cuMaskSize – [in] number of the block of memories (uint32_t *) allocated by user
cuMask – [out] Pointer to a pre-allocated block of memories (uint32_t *) in which the stream’s CU mask is returned. The CU mask is returned in a chunck of 32 bits where each active bit represents one active CU

Returns:

hipSuccess, hipErrorInvalidHandle, hipErrorInvalidValue

hipError_t hipStreamAddCallback(hipStream_t stream, hipStreamCallback_t callback, void *userData, unsigned int flags)¶

Adds a callback to be called on the host after all currently enqueued items in the stream have completed. For each hipStreamAddCallback call, a callback will be executed exactly once. The callback will block later work in the stream until it is finished.

Parameters:

stream – [in] - Stream to add callback to
callback – [in] - The function to call once preceding stream operations are complete
userData – [in] - User specified data to be passed to the callback function
flags – [in] - Reserved for future use, must be 0

Returns:

hipSuccess, hipErrorInvalidHandle, hipErrorNotSupported

hipError_t hipStreamWaitValue32 (hipStream_t stream, void *ptr, uint32_t value, unsigned int flags, uint32_t mask __dparm(0xFFFFFFFF))

Enqueues a wait command to the stream.[BETA].

Enqueues a wait command to the stream, all operations enqueued on this stream after this, will not execute until the defined wait condition is true.

hipStreamWaitValueGte: waits until *ptr&mask >= value hipStreamWaitValueEq : waits until *ptr&mask == value hipStreamWaitValueAnd: waits until ((*ptr&mask) & value) != 0 hipStreamWaitValueNor: waits until ~((*ptr&mask) | (value&mask)) != 0

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

Note

when using ‘hipStreamWaitValueNor’, mask is applied on both ‘value’ and ‘*ptr’.

Note

Support for hipStreamWaitValue32 can be queried using ‘hipDeviceGetAttribute()’ and ‘hipDeviceAttributeCanUseStreamWaitValue’ flag.

Parameters:

stream – [in] - Stream identifier
ptr – [in] - Pointer to memory object allocated using ‘hipMallocSignalMemory’ flag
value – [in] - Value to be used in compare operation
flags – [in] - Defines the compare operation, supported values are hipStreamWaitValueGte hipStreamWaitValueEq, hipStreamWaitValueAnd and hipStreamWaitValueNor
mask – [in] - Mask to be applied on value at memory before it is compared with value, default value is set to enable every bit

Returns:

hipError_t hipStreamWaitValue64 (hipStream_t stream, void *ptr, uint64_t value, unsigned int flags, uint64_t mask __dparm(0xFFFFFFFFFFFFFFFF))

Enqueues a wait command to the stream.[BETA].

Enqueues a wait command to the stream, all operations enqueued on this stream after this, will not execute until the defined wait condition is true.

hipStreamWaitValueGte: waits until *ptr&mask >= value hipStreamWaitValueEq : waits until *ptr&mask == value hipStreamWaitValueAnd: waits until ((*ptr&mask) & value) != 0 hipStreamWaitValueNor: waits until ~((*ptr&mask) | (value&mask)) != 0

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

Note

when using ‘hipStreamWaitValueNor’, mask is applied on both ‘value’ and ‘*ptr’.

Note

Support for hipStreamWaitValue64 can be queried using ‘hipDeviceGetAttribute()’ and ‘hipDeviceAttributeCanUseStreamWaitValue’ flag.

Parameters:

stream – [in] - Stream identifier
ptr – [in] - Pointer to memory object allocated using ‘hipMallocSignalMemory’ flag
value – [in] - Value to be used in compare operation
flags – [in] - Defines the compare operation, supported values are hipStreamWaitValueGte hipStreamWaitValueEq, hipStreamWaitValueAnd and hipStreamWaitValueNor.
mask – [in] - Mask to be applied on value at memory before it is compared with value default value is set to enable every bit

Returns:

hipError_t hipStreamWriteValue32(hipStream_t stream, void *ptr, uint32_t value, unsigned int flags)¶

Enqueues a write command to the stream.[BETA].

Enqueues a write command to the stream, write operation is performed after all earlier commands on this stream have completed the execution.

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

Parameters:

stream – [in] - Stream identifier
ptr – [in] - Pointer to a GPU accessible memory object
value – [in] - Value to be written
flags – [in] - reserved, ignored for now, will be used in future releases

Returns:

hipError_t hipStreamWriteValue64(hipStream_t stream, void *ptr, uint64_t value, unsigned int flags)¶

Enqueues a write command to the stream.[BETA].

Enqueues a write command to the stream, write operation is performed after all earlier commands on this stream have completed the execution.

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

Parameters:

stream – [in] - Stream identifier
ptr – [in] - Pointer to a GPU accessible memory object
value – [in] - Value to be written
flags – [in] - reserved, ignored for now, will be used in future releases

Returns:

hipSuccess, hipErrorNotInitialized, hipErrorInvalidValue, hipErrorLaunchFailure, hipErrorOutOfMemory

hipError_t hipEventCreateWithFlags(hipEvent_t *event, unsigned flags)¶

Create an event with the specified flags.

Parameters:

event – [inout] Returns the newly created event.
flags – [in] Flags to control event behavior. Valid values are hipEventDefault, hipEventBlockingSync, hipEventDisableTiming, hipEventInterprocess hipEventDefault : Default flag. The event will use active synchronization and will support timing. Blocking synchronization provides lowest possible latency at the expense of dedicating a CPU to poll on the event. hipEventBlockingSync : The event will use blocking synchronization : if hipEventSynchronize is called on this event, the thread will block until the event completes. This can increase latency for the synchroniation but can result in lower power and more resources for other CPU threads. hipEventDisableTiming : Disable recording of timing information. Events created with this flag would not record profiling data and provide best performance if used for synchronization. hipEventInterprocess : The event can be used as an interprocess event. hipEventDisableTiming flag also must be set when hipEventInterprocess flag is set.

Returns:

hipError_t hipEventCreate(hipEvent_t *event)¶

Create an event

Parameters:

event – [inout] Returns the newly created event.

Returns:

hipSuccess, hipErrorNotInitialized, hipErrorInvalidValue, hipErrorLaunchFailure, hipErrorOutOfMemory

hipError_t hipEventRecord(hipEvent_t event, hipStream_t stream)¶

Record an event in the specified stream.

hipEventQuery() or hipEventSynchronize() must be used to determine when the event transitions from “recording” (after hipEventRecord() is called) to “recorded” (when timestamps are set, if requested).

Events which are recorded in a non-NULL stream will transition to from recording to “recorded” state when they reach the head of the specified stream, after all previous commands in that stream have completed executing.

If hipEventRecord() has been previously called on this event, then this call will overwrite any existing state in event.

If this function is called on an event that is currently being recorded, results are undefined

either outstanding recording may save state into the event, and the order is not guaranteed.

Parameters:

event – [in] event to record.
stream – [in] stream in which to record event.

Returns:

hipSuccess, hipErrorInvalidValue, hipErrorNotInitialized, hipErrorInvalidHandle, hipErrorLaunchFailure

hipError_t hipEventDestroy(hipEvent_t event)¶

Destroy the specified event.

Releases memory associated with the event. If the event is recording but has not completed recording when hipEventDestroy() is called, the function will return immediately and the completion_future resources will be released later, when the hipDevice is synchronized.

Parameters:

event – [in] Event to destroy.

Returns:

hipSuccess, hipErrorNotInitialized, hipErrorInvalidValue, hipErrorLaunchFailure

Returns:

hipSuccess, hipErrorInvalidValue, hipErrorNotInitialized, hipErrorInvalidHandle, hipErrorLaunchFailure

hipError_t hipEventSynchronize(hipEvent_t event)¶

Wait for an event to complete.

This function will block until the event is ready, waiting for all previous work in the stream specified when event was recorded with hipEventRecord().

If hipEventRecord() has not been called on event, this function returns immediately.

TODO-hip- This function needs to support hipEventBlockingSync parameter.

Parameters:

event – [in] Event on which to wait.

Returns:

hipError_t hipEventElapsedTime(float *ms, hipEvent_t start, hipEvent_t stop)¶

Return the elapsed time between two events.

Computes the elapsed time between two events. Time is computed in ms, with a resolution of approximately 1 us.

Events which are recorded in a NULL stream will block until all commands on all other streams complete execution, and then record the timestamp.

Events which are recorded in a non-NULL stream will record their timestamp when they reach the head of the specified stream, after all previous commands in that stream have completed executing. Thus the time that the event recorded may be significantly after the host calls hipEventRecord().

If hipEventRecord() has not been called on either event, then hipErrorInvalidHandle is returned. If hipEventRecord() has been called on both events, but the timestamp has not yet been recorded on one or both events (that is, hipEventQuery() would return hipErrorNotReady on at least one of the events), then hipErrorNotReady is returned.

Parameters:

ms – [out] : Return time between start and stop in ms.
start – [in] : Start event.
stop – [in] : Stop event.

Returns:

hipSuccess, hipErrorInvalidValue, hipErrorNotReady, hipErrorInvalidHandle, hipErrorNotInitialized, hipErrorLaunchFailure

hipError_t hipEventQuery(hipEvent_t event)¶

Query event status.

Query the status of the specified event. This function will return hipSuccess if all commands in the appropriate stream (specified to hipEventRecord()) have completed. If that work has not completed, or if hipEventRecord() was not called on the event, then hipErrorNotReady is returned.

Parameters:

event – [in] Event to query.

Returns:

hipSuccess, hipErrorNotReady, hipErrorInvalidHandle, hipErrorInvalidValue, hipErrorNotInitialized, hipErrorLaunchFailure

hipError_t hipPointerGetAttributes(hipPointerAttribute_t *attributes, const void *ptr)¶

Return attributes for the specified pointer.

See also

hipPointerGetAttribute

Parameters:

attributes – [out] attributes for the specified pointer
ptr – [in] pointer to get attributes for

Returns:

hipSuccess, hipErrorInvalidDevice, hipErrorInvalidValue

hipError_t hipPointerGetAttribute(void *data, hipPointer_attribute attribute, hipDeviceptr_t ptr)¶

Returns information about the specified pointer.[BETA].

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

See also

hipPointerGetAttributes

Parameters:

data – [inout] returned pointer attribute value
atribute – [in] attribute to query for
ptr – [in] pointer to get attributes for

Returns:

hipSuccess, hipErrorInvalidDevice, hipErrorInvalidValue

hipError_t hipDrvPointerGetAttributes(unsigned int numAttributes, hipPointer_attribute *attributes, void **data, hipDeviceptr_t ptr)¶

Returns information about the specified pointer.[BETA].

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

See also

hipPointerGetAttribute

Parameters:

numAttributes – [in] number of attributes to query for
attributes – [in] attributes to query for
data – [inout] a two-dimensional containing pointers to memory locations where the result of each attribute query will be written to
ptr – [in] pointer to get attributes for

Returns:

hipSuccess, hipErrorInvalidDevice, hipErrorInvalidValue

hipError_t hipImportExternalSemaphore(hipExternalSemaphore_t *extSem_out, const hipExternalSemaphoreHandleDesc *semHandleDesc)¶

Imports an external semaphore.

See also

Parameters:

extSem_out – [out] External semaphores to be waited on
semHandleDesc – [in] Semaphore import handle descriptor

Returns:

hipSuccess, hipErrorInvalidDevice, hipErrorInvalidValue

hipError_t hipSignalExternalSemaphoresAsync(const hipExternalSemaphore_t *extSemArray, const hipExternalSemaphoreSignalParams *paramsArray, unsigned int numExtSems, hipStream_t stream)¶

Signals a set of external semaphore objects.

See also

Parameters:

extSem_out – [in] External semaphores to be waited on
paramsArray – [in] Array of semaphore parameters
numExtSems – [in] Number of semaphores to wait on
stream – [in] Stream to enqueue the wait operations in

Returns:

hipSuccess, hipErrorInvalidDevice, hipErrorInvalidValue

hipError_t hipWaitExternalSemaphoresAsync(const hipExternalSemaphore_t *extSemArray, const hipExternalSemaphoreWaitParams *paramsArray, unsigned int numExtSems, hipStream_t stream)¶

Waits on a set of external semaphore objects.

See also

Parameters:

extSem_out – [in] External semaphores to be waited on
paramsArray – [in] Array of semaphore parameters
numExtSems – [in] Number of semaphores to wait on
stream – [in] Stream to enqueue the wait operations in

Returns:

hipSuccess, hipErrorInvalidDevice, hipErrorInvalidValue

hipError_t hipDestroyExternalSemaphore(hipExternalSemaphore_t extSem)¶

Destroys an external semaphore object and releases any references to the underlying resource. Any outstanding signals or waits must have completed before the semaphore is destroyed.

See also

Parameters:

extSem – [in] handle to an external memory object

Returns:

hipSuccess, hipErrorInvalidDevice, hipErrorInvalidValue

hipError_t hipImportExternalMemory(hipExternalMemory_t *extMem_out, const hipExternalMemoryHandleDesc *memHandleDesc)¶

Imports an external memory object.

See also

Parameters:

extMem_out – [out] Returned handle to an external memory object
memHandleDesc – [in] Memory import handle descriptor

Returns:

hipSuccess, hipErrorInvalidDevice, hipErrorInvalidValue

hipError_t hipExternalMemoryGetMappedBuffer(void **devPtr, hipExternalMemory_t extMem, const hipExternalMemoryBufferDesc *bufferDesc)¶

Maps a buffer onto an imported memory object.

See also

Parameters:

devPtr – [out] Returned device pointer to buffer
extMem – [in] Handle to external memory object
bufferDesc – [in] Buffer descriptor

Returns:

hipSuccess, hipErrorInvalidDevice, hipErrorInvalidValue

hipError_t hipDestroyExternalMemory(hipExternalMemory_t extMem)¶

Destroys an external memory object.

See also

Parameters:

extMem – [in] External memory object to be destroyed

Returns:

hipSuccess, hipErrorInvalidDevice, hipErrorInvalidValue

hipError_t hipMalloc(void **ptr, size_t size)¶

Allocate memory on the default accelerator.

If size is 0, no memory is allocated, *ptr returns nullptr, and hipSuccess is returned.

Parameters:

ptr – [out] Pointer to the allocated memory
size – [in] Requested memory size

Returns:

hipSuccess, hipErrorOutOfMemory, hipErrorInvalidValue (bad context, null *ptr)

hipError_t hipExtMallocWithFlags(void **ptr, size_t sizeBytes, unsigned int flags)¶

Allocate memory on the default accelerator.

If size is 0, no memory is allocated, *ptr returns nullptr, and hipSuccess is returned.

Parameters:

ptr – [out] Pointer to the allocated memory
size – [in] Requested memory size
flags – [in] Type of memory allocation

Returns:

hipSuccess, hipErrorOutOfMemory, hipErrorInvalidValue (bad context, null *ptr)

hipError_t hipMallocHost(void **ptr, size_t size)¶

Allocate pinned host memory [Deprecated].

If size is 0, no memory is allocated, *ptr returns nullptr, and hipSuccess is returned.

Deprecated:: use hipHostMalloc() instead

Parameters:

ptr – [out] Pointer to the allocated host pinned memory
size – [in] Requested memory size

Returns:

hipError_t hipMemAllocHost(void **ptr, size_t size)¶

Allocate pinned host memory [Deprecated].

If size is 0, no memory is allocated, *ptr returns nullptr, and hipSuccess is returned.

Deprecated:: use hipHostMalloc() instead

Parameters:

ptr – [out] Pointer to the allocated host pinned memory
size – [in] Requested memory size

Returns:

hipSetDeviceFlags, hipHostFree

hipError_t hipHostMalloc(void **ptr, size_t size, unsigned int flags)¶

Allocate device accessible page locked host memory.

If size is 0, no memory is allocated, *ptr returns nullptr, and hipSuccess is returned.

See also

Parameters:

ptr – [out] Pointer to the allocated host pinned memory
size – [in] Requested memory size
flags – [in] Type of host memory allocation

Returns:

hipSuccess, hipErrorMemoryAllocation, hipErrorNotSupported, hipErrorInvalidValue

hipError_t hipMallocManaged (void **dev_ptr, size_t size, unsigned int flags __dparm(hipMemAttachGlobal))

Allocates memory that will be automatically managed by HIP.

Parameters:

dev_ptr – [out] - pointer to allocated device memory
size – [in] - requested allocation size in bytes
flags – [in] - must be either hipMemAttachGlobal or hipMemAttachHost (defaults to hipMemAttachGlobal)

Returns:

hipError_t hipMemPrefetchAsync (const void *dev_ptr, size_t count, int device, hipStream_t stream __dparm(0))

Prefetches memory to the specified destination device using HIP.

Parameters:

dev_ptr – [in] pointer to be prefetched
count – [in] size in bytes for prefetching
device – [in] destination device to prefetch to
stream – [in] stream to enqueue prefetch operation

Returns:

hipError_t hipMemAdvise(const void *dev_ptr, size_t count, hipMemoryAdvise advice, int device)¶

Advise about the usage of a given memory range to HIP.

Parameters:

dev_ptr – [in] pointer to memory to set the advice for
count – [in] size in bytes of the memory range
advice – [in] advice to be applied for the specified memory range
device – [in] device to apply the advice for

Returns:

hipError_t hipMemRangeGetAttribute(void *data, size_t data_size, hipMemRangeAttribute attribute, const void *dev_ptr, size_t count)¶

Query an attribute of a given memory range in HIP.

Parameters:

data – [inout] a pointer to a memory location where the result of each attribute query will be written to
data_size – [in] the size of data
attribute – [in] the attribute to query
dev_ptr – [in] start of the range to query
count – [in] size of the range to query

Returns:

hipError_t hipMemRangeGetAttributes(void **data, size_t *data_sizes, hipMemRangeAttribute *attributes, size_t num_attributes, const void *dev_ptr, size_t count)¶

Query attributes of a given memory range in HIP.

Parameters:

data – [inout] a two-dimensional array containing pointers to memory locations where the result of each attribute query will be written to
data_sizes – [in] an array, containing the sizes of each result
attributes – [in] the attribute to query
num_attributes – [in] an array of attributes to query (numAttributes and the number of attributes in this array should match)
dev_ptr – [in] start of the range to query
count – [in] size of the range to query

Returns:

hipError_t hipStreamAttachMemAsync (hipStream_t stream, void *dev_ptr, size_t length __dparm(0), unsigned int flags __dparm(hipMemAttachSingle))

Attach memory to a stream asynchronously in HIP.

Parameters:

stream – [in] - stream in which to enqueue the attach operation
dev_ptr – [in] - pointer to memory (must be a pointer to managed memory or to a valid host-accessible region of system-allocated memory)
length – [in] - length of memory (defaults to zero)
flags – [in] - must be one of hipMemAttachGlobal, hipMemAttachHost or hipMemAttachSingle (defaults to hipMemAttachSingle)

Returns:

hipSuccess, hipErrorInvalidValue, hipErrorNotSupported, hipErrorOutOfMemory

hipError_t hipMallocAsync(void **dev_ptr, size_t size, hipStream_t stream)¶

Allocates memory with stream ordered semantics.

Inserts a memory allocation operation into stream. A pointer to the allocated memory is returned immediately in *dptr. The allocation must not be accessed until the the allocation operation completes. The allocation comes from the memory pool associated with the stream’s device.

Note

The default memory pool of a device contains device memory from that device.

Note

Basic stream ordering allows future work submitted into the same stream to use the allocation. Stream query, stream synchronize, and HIP events can be used to guarantee that the allocation operation completes before work submitted in a separate stream runs.

Note

During stream capture, this function results in the creation of an allocation node. In this case, the allocation is owned by the graph instead of the memory pool. The memory pool’s properties are used to set the node’s creation parameters.

Warning

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

Parameters:

dev_ptr – [out] Returned device pointer of memory allocation
size – [in] Number of bytes to allocate
stream – [in] The stream establishing the stream ordering contract and the memory pool to allocate from

Returns:

hipError_t hipFreeAsync(void *dev_ptr, hipStream_t stream)¶

Frees memory with stream ordered semantics.

Inserts a free operation into stream. The allocation must not be used after stream execution reaches the free. After this API returns, accessing the memory from any subsequent work launched on the GPU or querying its pointer attributes results in undefined behavior.

Note

During stream capture, this function results in the creation of a free node and must therefore be passed the address of a graph allocation.

Warning

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

Parameters:

dev_ptr – [in] Pointer to device memory to free
stream – [in] The stream, where the destruciton will occur according to the execution order

Returns:

hipSuccess, hipErrorInvalidValue, hipErrorNotSupported

hipError_t hipMemPoolTrimTo(hipMemPool_t mem_pool, size_t min_bytes_to_hold)¶

Releases freed memory back to the OS.

Releases memory back to the OS until the pool contains fewer than min_bytes_to_keep reserved bytes, or there is no more memory that the allocator can safely release. The allocator cannot release OS allocations that back outstanding asynchronous allocations. The OS allocations may happen at different granularity from the user allocations.

Note

: Allocations that have not been freed count as outstanding.

Note

: Allocations that have been asynchronously freed but whose completion has not been observed on the host (eg. by a synchronize) can count as outstanding.

Warning

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

Parameters:

mem_pool – [in] The memory pool to trim allocations
min_bytes_to_hold – [in] If the pool has less than min_bytes_to_hold reserved, then the TrimTo operation is a no-op. Otherwise the memory pool will contain at least min_bytes_to_hold bytes reserved after the operation.

Returns:

hipError_t hipMemPoolSetAttribute(hipMemPool_t mem_pool, hipMemPoolAttr attr, void *value)¶

Sets attributes of a memory pool.

Supported attributes are:

hipMemPoolAttrReleaseThreshold: (value type = cuuint64_t) Amount of reserved memory in bytes to hold onto before trying to release memory back to the OS. When more than the release threshold bytes of memory are held by the memory pool, the allocator will try to release memory back to the OS on the next call to stream, event or context synchronize. (default 0)
hipMemPoolReuseFollowEventDependencies: (value type = int) Allow hipMallocAsync to use memory asynchronously freed in another stream as long as a stream ordering dependency of the allocating stream on the free action exists. HIP events and null stream interactions can create the required stream ordered dependencies. (default enabled)
hipMemPoolReuseAllowOpportunistic: (value type = int) Allow reuse of already completed frees when there is no dependency between the free and allocation. (default enabled)
hipMemPoolReuseAllowInternalDependencies: (value type = int) Allow hipMallocAsync to insert new stream dependencies in order to establish the stream ordering required to reuse a piece of memory released by hipFreeAsync (default enabled).

Warning

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

Parameters:

mem_pool – [in] The memory pool to modify
attr – [in] The attribute to modify
value – [in] Pointer to the value to assign

Returns:

hipError_t hipMemPoolGetAttribute(hipMemPool_t mem_pool, hipMemPoolAttr attr, void *value)¶

Gets attributes of a memory pool.

Supported attributes are:

hipMemPoolAttrReleaseThreshold: (value type = cuuint64_t) Amount of reserved memory in bytes to hold onto before trying to release memory back to the OS. When more than the release threshold bytes of memory are held by the memory pool, the allocator will try to release memory back to the OS on the next call to stream, event or context synchronize. (default 0)
hipMemPoolReuseFollowEventDependencies: (value type = int) Allow hipMallocAsync to use memory asynchronously freed in another stream as long as a stream ordering dependency of the allocating stream on the free action exists. HIP events and null stream interactions can create the required stream ordered dependencies. (default enabled)
hipMemPoolReuseAllowOpportunistic: (value type = int) Allow reuse of already completed frees when there is no dependency between the free and allocation. (default enabled)
hipMemPoolReuseAllowInternalDependencies: (value type = int) Allow hipMallocAsync to insert new stream dependencies in order to establish the stream ordering required to reuse a piece of memory released by hipFreeAsync (default enabled).

Warning

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

Parameters:

mem_pool – [in] The memory pool to get attributes of
attr – [in] The attribute to get
value – [in] Retrieved value

Returns:

hipError_t hipMemPoolSetAccess(hipMemPool_t mem_pool, const hipMemAccessDesc *desc_list, size_t count)¶

Controls visibility of the specified pool between devices.

Warning

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

Parameters:

mem_pool – [in] Memory pool for acccess change
desc_list – [in] Array of access descriptors. Each descriptor instructs the access to enable for a single gpu
count – [in] Number of descriptors in the map array.

Returns:

hipError_t hipMemPoolGetAccess(hipMemAccessFlags *flags, hipMemPool_t mem_pool, hipMemLocation *location)¶

Returns the accessibility of a pool from a device.

Returns the accessibility of the pool’s memory from the specified location.

Warning

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

Parameters:

flags – [out] Accessibility of the memory pool from the specified location/device
mem_pool – [in] Memory pool being queried
location – [in] Location/device for memory pool access

Returns:

hipSuccess, hipErrorInvalidValue, hipErrorNotSupported

hipError_t hipMemPoolCreate(hipMemPool_t *mem_pool, const hipMemPoolProps *pool_props)¶

Creates a memory pool.

Creates a HIP memory pool and returns the handle in mem_pool. The pool_props determines the properties of the pool such as the backing device and IPC capabilities.

By default, the memory pool will be accessible from the device it is allocated on.

Note

Specifying hipMemHandleTypeNone creates a memory pool that will not support IPC.

Warning

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

Parameters:

mem_pool – [out] Contains createed memory pool
pool_props – [in] Memory pool properties

Returns:

hipError_t hipMemPoolDestroy(hipMemPool_t mem_pool)¶

Destroys the specified memory pool.

If any pointers obtained from this pool haven’t been freed or the pool has free operations that haven’t completed when hipMemPoolDestroy is invoked, the function will return immediately and the resources associated with the pool will be released automatically once there are no more outstanding allocations.

Destroying the current mempool of a device sets the default mempool of that device as the current mempool for that device.

Note

A device’s default memory pool cannot be destroyed.

Warning

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

Parameters:

mem_pool – [in] Memory pool for destruction

Returns:

hipSuccess, hipErrorInvalidValue, hipErrorNotSupported, hipErrorOutOfMemory

hipError_t hipMallocFromPoolAsync(void **dev_ptr, size_t size, hipMemPool_t mem_pool, hipStream_t stream)¶

Allocates memory from a specified pool with stream ordered semantics.

Inserts an allocation operation into stream. A pointer to the allocated memory is returned immediately in dev_ptr. The allocation must not be accessed until the the allocation operation completes. The allocation comes from the specified memory pool.

Basic stream ordering allows future work submitted into the same stream to use the allocation. Stream query, stream synchronize, and HIP events can be used to guarantee that the allocation operation completes before work submitted in a separate stream runs.

Note

The specified memory pool may be from a device different than that of the specified stream.

Note

During stream capture, this function results in the creation of an allocation node. In this case, the allocation is owned by the graph instead of the memory pool. The memory pool’s properties are used to set the node’s creation parameters.

Warning

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

Parameters:

dev_ptr – [out] Returned device pointer
size – [in] Number of bytes to allocate
mem_pool – [in] The pool to allocate from
stream – [in] The stream establishing the stream ordering semantic

Returns:

hipError_t hipMemPoolExportToShareableHandle(void *shared_handle, hipMemPool_t mem_pool, hipMemAllocationHandleType handle_type, unsigned int flags)¶

Exports a memory pool to the requested handle type.

Given an IPC capable mempool, create an OS handle to share the pool with another process. A recipient process can convert the shareable handle into a mempool with hipMemPoolImportFromShareableHandle. Individual pointers can then be shared with the hipMemPoolExportPointer and hipMemPoolImportPointer APIs. The implementation of what the shareable handle is and how it can be transferred is defined by the requested handle type.

See also

hipMemPoolImportFromShareableHandle

Note

: To create an IPC capable mempool, create a mempool with a hipMemAllocationHandleType other than hipMemHandleTypeNone.

Warning

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

Parameters:

shared_handle – [out] Pointer to the location in which to store the requested handle
mem_pool – [in] Pool to export
handle_type – [in] The type of handle to create
flags – [in] Must be 0

Returns:

hipSuccess, hipErrorInvalidValue, hipErrorOutOfMemory

hipError_t hipMemPoolImportFromShareableHandle(hipMemPool_t *mem_pool, void *shared_handle, hipMemAllocationHandleType handle_type, unsigned int flags)¶

Imports a memory pool from a shared handle.

Specific allocations can be imported from the imported pool with hipMemPoolImportPointer.

See also

hipMemPoolExportToShareableHandle

Note

Imported memory pools do not support creating new allocations. As such imported memory pools may not be used in hipDeviceSetMemPool or hipMallocFromPoolAsync calls.

Warning

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

Parameters:

mem_pool – [out] Returned memory pool
shared_handle – [in] OS handle of the pool to open
handle_type – [in] The type of handle being imported
flags – [in] Must be 0

Returns:

hipSuccess, hipErrorInvalidValue, hipErrorOutOfMemory

hipError_t hipMemPoolExportPointer(hipMemPoolPtrExportData *export_data, void *dev_ptr)¶

Export data to share a memory pool allocation between processes.

Constructs export_data for sharing a specific allocation from an already shared memory pool. The recipient process can import the allocation with the hipMemPoolImportPointer api. The data is not a handle and may be shared through any IPC mechanism.

See also

hipMemPoolImportPointer

Warning

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

Parameters:

export_data – [out] Returned export data
dev_ptr – [in] Pointer to memory being exported

Returns:

hipSuccess, hipErrorInvalidValue, hipErrorOutOfMemory

hipError_t hipMemPoolImportPointer(void **dev_ptr, hipMemPool_t mem_pool, hipMemPoolPtrExportData *export_data)¶

Import a memory pool allocation from another process.

Returns in dev_ptr a pointer to the imported memory. The imported memory must not be accessed before the allocation operation completes in the exporting process. The imported memory must be freed from all importing processes before being freed in the exporting process. The pointer may be freed with hipFree or hipFreeAsync. If hipFreeAsync is used, the free must be completed on the importing process before the free operation on the exporting process.

See also

hipMemPoolExportPointer

Note

The hipFreeAsync api may be used in the exporting process before the hipFreeAsync operation completes in its stream as long as the hipFreeAsync in the exporting process specifies a stream with a stream dependency on the importing process’s hipFreeAsync.

Warning

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

Parameters:

dev_ptr – [out] Pointer to imported memory
mem_pool – [in] Memory pool from which to import a pointer
export_data – [in] Data specifying the memory to import

Returns:

hipSuccess, hipErrorInvalidValue, hipErrorNotInitialized, hipErrorOutOfMemory

hipError_t hipHostAlloc(void **ptr, size_t size, unsigned int flags)¶

Allocate device accessible page locked host memory [Deprecated].

If size is 0, no memory is allocated, *ptr returns nullptr, and hipSuccess is returned.

Deprecated:: use hipHostMalloc() instead

Parameters:

ptr – [out] Pointer to the allocated host pinned memory
size – [in] Requested memory size
flags – [in] Type of host memory allocation

Returns:

hipSetDeviceFlags, hipHostMalloc

hipError_t hipHostGetDevicePointer(void **devPtr, void *hstPtr, unsigned int flags)¶

Get Device pointer from Host Pointer allocated through hipHostMalloc.

See also

Parameters:

dstPtr – [out] Device Pointer mapped to passed host pointer
hstPtr – [in] Host Pointer allocated through hipHostMalloc
flags – [in] Flags to be passed for extension

Returns:

hipSuccess, hipErrorInvalidValue, hipErrorOutOfMemory

hipError_t hipHostGetFlags(unsigned int *flagsPtr, void *hostPtr)¶

Return flags associated with host pointer.

See also

hipHostMalloc

Parameters:

flagsPtr – [out] Memory location to store flags
hostPtr – [in] Host Pointer allocated through hipHostMalloc

Returns:

hipError_t hipHostRegister(void *hostPtr, size_t sizeBytes, unsigned int flags)¶

Register host memory so it can be accessed from the current device.

Flags:

hipHostRegisterDefault Memory is Mapped and Portable
hipHostRegisterPortable Memory is considered registered by all contexts. HIP only supports one context so this is always assumed true.
hipHostRegisterMapped Map the allocation into the address space for the current device. The device pointer can be obtained with hipHostGetDevicePointer.

After registering the memory, use hipHostGetDevicePointer to obtain the mapped device pointer. On many systems, the mapped device pointer will have a different value than the mapped host pointer. Applications must use the device pointer in device code, and the host pointer in device code.

On some systems, registered memory is pinned. On some systems, registered memory may not be actually be pinned but uses OS or hardware facilities to all GPU access to the host memory.

Developers are strongly encouraged to register memory blocks which are aligned to the host cache-line size. (typically 64-bytes but can be obtains from the CPUID instruction).

If registering non-aligned pointers, the application must take care when register pointers from the same cache line on different devices. HIP’s coarse-grained synchronization model does not guarantee correct results if different devices write to different parts of the same cache block - typically one of the writes will “win” and overwrite data from the other registered memory region.

Parameters:

hostPtr – [out] Pointer to host memory to be registered.
sizeBytes – [in] size of the host memory
flags. – [in] See below.

Returns:

hipError_t hipHostUnregister(void *hostPtr)¶

Un-register host pointer.

See also

hipHostRegister

Parameters:

hostPtr – [in] Host pointer previously registered with hipHostRegister

Returns:

Error code

hipError_t hipMallocPitch(void **ptr, size_t *pitch, size_t width, size_t height)¶

Allocates at least width (in bytes) * height bytes of linear memory Padding may occur to ensure alighnment requirements are met for the given row The change in width size due to padding will be returned in *pitch. Currently the alignment is set to 128 bytes

If size is 0, no memory is allocated, *ptr returns nullptr, and hipSuccess is returned.

Parameters:

ptr – [out] Pointer to the allocated device memory
pitch – [out] Pitch for allocation (in bytes)
width – [in] Requested pitched allocation width (in bytes)
height – [in] Requested pitched allocation height

Returns:

Error code

hipError_t hipMemAllocPitch(hipDeviceptr_t *dptr, size_t *pitch, size_t widthInBytes, size_t height, unsigned int elementSizeBytes)¶

Allocates at least width (in bytes) * height bytes of linear memory Padding may occur to ensure alighnment requirements are met for the given row The change in width size due to padding will be returned in *pitch. Currently the alignment is set to 128 bytes

If size is 0, no memory is allocated, ptr returns nullptr, and hipSuccess is returned. The intended usage of pitch is as a separate parameter of the allocation, used to compute addresses within the 2D array. Given the row and column of an array element of type T, the address is computed as: T pElement = (T*)((char*)BaseAddress + Row * Pitch) + Column;

Parameters:

dptr – [out] Pointer to the allocated device memory
pitch – [out] Pitch for allocation (in bytes)
width – [in] Requested pitched allocation width (in bytes)
height – [in] Requested pitched allocation height

Returns:

Error code

hipError_t hipFree(void *ptr)¶

Free memory allocated by the hcc hip memory allocation API. This API performs an implicit hipDeviceSynchronize() call. If pointer is NULL, the hip runtime is initialized and hipSuccess is returned.

Parameters:

ptr – [in] Pointer to memory to be freed

Returns:

hipSuccess, hipErrorDeinitialized, hipErrorNotInitialized, hipErrorInvalidContext, hipErrorInvalidValue

Returns:

hipErrorInvalidDevicePointer (if pointer is invalid, including host pointers allocated with hipHostMalloc)

hipError_t hipFreeHost(void *ptr)¶

Free memory allocated by the hcc hip host memory allocation API. [Deprecated].

Deprecated:: use hipHostFree() instead

Parameters:

ptr – [in] Pointer to memory to be freed

Returns:

hipSuccess, hipErrorInvalidValue (if pointer is invalid, including device pointers allocated with hipMalloc)

hipError_t hipHostFree(void *ptr)¶

Free memory allocated by the hcc hip host memory allocation API This API performs an implicit hipDeviceSynchronize() call. If pointer is NULL, the hip runtime is initialized and hipSuccess is returned.

Parameters:

ptr – [in] Pointer to memory to be freed

Returns:

hipSuccess, hipErrorInvalidValue (if pointer is invalid, including device pointers allocated with hipMalloc)

hipError_t hipMemcpy(void *dst, const void *src, size_t sizeBytes, hipMemcpyKind kind)¶

Copy data from src to dst.

It supports memory from host to device, device to host, device to device and host to host The src and dst must not overlap.

For hipMemcpy, the copy is always performed by the current device (set by hipSetDevice). For multi-gpu or peer-to-peer configurations, it is recommended to set the current device to the device where the src data is physically located. For optimal peer-to-peer copies, the copy device must be able to access the src and dst pointers (by calling hipDeviceEnablePeerAccess with copy agent as the current device and src/dest as the peerDevice argument. if this is not done, the hipMemcpy will still work, but will perform the copy using a staging buffer on the host. Calling hipMemcpy with dst and src pointers that do not match the hipMemcpyKind results in undefined behavior.

See also

hipArrayCreate, hipArrayDestroy, hipArrayGetDescriptor, hipMemAlloc, hipMemAllocHost, hipMemAllocPitch, hipMemcpy2D, hipMemcpy2DAsync, hipMemcpy2DUnaligned, hipMemcpyAtoA, hipMemcpyAtoD, hipMemcpyAtoH, hipMemcpyAtoHAsync, hipMemcpyDtoA, hipMemcpyDtoD, hipMemcpyDtoDAsync, hipMemcpyDtoH, hipMemcpyDtoHAsync, hipMemcpyHtoA, hipMemcpyHtoAAsync, hipMemcpyHtoDAsync, hipMemFree, hipMemFreeHost, hipMemGetAddressRange, hipMemGetInfo, hipMemHostAlloc, hipMemHostGetDevicePointer

Parameters:

dst – [out] Data being copy to
src – [in] Data being copy from
sizeBytes – [in] Data size in bytes
copyType – [in] Memory copy type

Returns:

hipSuccess, hipErrorInvalidValue, #hipErrorMemoryFree, #hipErrorUnknowni

hipError_t hipMemcpyWithStream(void *dst, const void *src, size_t sizeBytes, hipMemcpyKind kind, hipStream_t stream)¶

hipError_t hipMemcpyHtoD(hipDeviceptr_t dst, void *src, size_t sizeBytes)¶

Copy data from Host to Device.

See also

hipArrayCreate, hipArrayDestroy, hipArrayGetDescriptor, hipMemAlloc, hipMemAllocHost, hipMemAllocPitch, hipMemcpy2D, hipMemcpy2DAsync, hipMemcpy2DUnaligned, hipMemcpyAtoA, hipMemcpyAtoD, hipMemcpyAtoH, hipMemcpyAtoHAsync, hipMemcpyDtoA, hipMemcpyDtoD, hipMemcpyDtoDAsync, hipMemcpyDtoH, hipMemcpyDtoHAsync, hipMemcpyHtoA, hipMemcpyHtoAAsync, hipMemcpyHtoDAsync, hipMemFree, hipMemFreeHost, hipMemGetAddressRange, hipMemGetInfo, hipMemHostAlloc, hipMemHostGetDevicePointer

Parameters:

dst – [out] Data being copy to
src – [in] Data being copy from
sizeBytes – [in] Data size in bytes

Returns:

hipError_t hipMemcpyDtoH(void *dst, hipDeviceptr_t src, size_t sizeBytes)¶

Copy data from Device to Host.

See also

hipArrayCreate, hipArrayDestroy, hipArrayGetDescriptor, hipMemAlloc, hipMemAllocHost, hipMemAllocPitch, hipMemcpy2D, hipMemcpy2DAsync, hipMemcpy2DUnaligned, hipMemcpyAtoA, hipMemcpyAtoD, hipMemcpyAtoH, hipMemcpyAtoHAsync, hipMemcpyDtoA, hipMemcpyDtoD, hipMemcpyDtoDAsync, hipMemcpyDtoH, hipMemcpyDtoHAsync, hipMemcpyHtoA, hipMemcpyHtoAAsync, hipMemcpyHtoDAsync, hipMemFree, hipMemFreeHost, hipMemGetAddressRange, hipMemGetInfo, hipMemHostAlloc, hipMemHostGetDevicePointer

Parameters:

dst – [out] Data being copy to
src – [in] Data being copy from
sizeBytes – [in] Data size in bytes

Returns:

hipSuccess, hipErrorDeinitialized, hipErrorNotInitialized, hipErrorInvalidContext, hipErrorInvalidValue

hipError_t hipMemcpyDtoD(hipDeviceptr_t dst, hipDeviceptr_t src, size_t sizeBytes)¶

Copy data from Device to Device.

See also

hipArrayCreate, hipArrayDestroy, hipArrayGetDescriptor, hipMemAlloc, hipMemAllocHost, hipMemAllocPitch, hipMemcpy2D, hipMemcpy2DAsync, hipMemcpy2DUnaligned, hipMemcpyAtoA, hipMemcpyAtoD, hipMemcpyAtoH, hipMemcpyAtoHAsync, hipMemcpyDtoA, hipMemcpyDtoD, hipMemcpyDtoDAsync, hipMemcpyDtoH, hipMemcpyDtoHAsync, hipMemcpyHtoA, hipMemcpyHtoAAsync, hipMemcpyHtoDAsync, hipMemFree, hipMemFreeHost, hipMemGetAddressRange, hipMemGetInfo, hipMemHostAlloc, hipMemHostGetDevicePointer

Parameters:

dst – [out] Data being copy to
src – [in] Data being copy from
sizeBytes – [in] Data size in bytes

Returns:

hipSuccess, hipErrorDeinitialized, hipErrorNotInitialized, hipErrorInvalidContext, hipErrorInvalidValue

hipError_t hipMemcpyHtoDAsync(hipDeviceptr_t dst, void *src, size_t sizeBytes, hipStream_t stream)¶

Copy data from Host to Device asynchronously.

See also

hipArrayCreate, hipArrayDestroy, hipArrayGetDescriptor, hipMemAlloc, hipMemAllocHost, hipMemAllocPitch, hipMemcpy2D, hipMemcpy2DAsync, hipMemcpy2DUnaligned, hipMemcpyAtoA, hipMemcpyAtoD, hipMemcpyAtoH, hipMemcpyAtoHAsync, hipMemcpyDtoA, hipMemcpyDtoD, hipMemcpyDtoDAsync, hipMemcpyDtoH, hipMemcpyDtoHAsync, hipMemcpyHtoA, hipMemcpyHtoAAsync, hipMemcpyHtoDAsync, hipMemFree, hipMemFreeHost, hipMemGetAddressRange, hipMemGetInfo, hipMemHostAlloc, hipMemHostGetDevicePointer

Parameters:

dst – [out] Data being copy to
src – [in] Data being copy from
sizeBytes – [in] Data size in bytes

Returns:

hipSuccess, hipErrorDeinitialized, hipErrorNotInitialized, hipErrorInvalidContext, hipErrorInvalidValue

hipError_t hipMemcpyDtoHAsync(void *dst, hipDeviceptr_t src, size_t sizeBytes, hipStream_t stream)¶

Copy data from Device to Host asynchronously.

See also

hipArrayCreate, hipArrayDestroy, hipArrayGetDescriptor, hipMemAlloc, hipMemAllocHost, hipMemAllocPitch, hipMemcpy2D, hipMemcpy2DAsync, hipMemcpy2DUnaligned, hipMemcpyAtoA, hipMemcpyAtoD, hipMemcpyAtoH, hipMemcpyAtoHAsync, hipMemcpyDtoA, hipMemcpyDtoD, hipMemcpyDtoDAsync, hipMemcpyDtoH, hipMemcpyDtoHAsync, hipMemcpyHtoA, hipMemcpyHtoAAsync, hipMemcpyHtoDAsync, hipMemFree, hipMemFreeHost, hipMemGetAddressRange, hipMemGetInfo, hipMemHostAlloc, hipMemHostGetDevicePointer

Parameters:

dst – [out] Data being copy to
src – [in] Data being copy from
sizeBytes – [in] Data size in bytes

Returns:

hipSuccess, hipErrorDeinitialized, hipErrorNotInitialized, hipErrorInvalidContext, hipErrorInvalidValue

hipError_t hipMemcpyDtoDAsync(hipDeviceptr_t dst, hipDeviceptr_t src, size_t sizeBytes, hipStream_t stream)¶

Copy data from Device to Device asynchronously.

See also

hipArrayCreate, hipArrayDestroy, hipArrayGetDescriptor, hipMemAlloc, hipMemAllocHost, hipMemAllocPitch, hipMemcpy2D, hipMemcpy2DAsync, hipMemcpy2DUnaligned, hipMemcpyAtoA, hipMemcpyAtoD, hipMemcpyAtoH, hipMemcpyAtoHAsync, hipMemcpyDtoA, hipMemcpyDtoD, hipMemcpyDtoDAsync, hipMemcpyDtoH, hipMemcpyDtoHAsync, hipMemcpyHtoA, hipMemcpyHtoAAsync, hipMemcpyHtoDAsync, hipMemFree, hipMemFreeHost, hipMemGetAddressRange, hipMemGetInfo, hipMemHostAlloc, hipMemHostGetDevicePointer

Parameters:

dst – [out] Data being copy to
src – [in] Data being copy from
sizeBytes – [in] Data size in bytes

Returns:

hipSuccess, hipErrorDeinitialized, hipErrorNotInitialized, hipErrorInvalidContext, hipErrorInvalidValue

hipError_t hipModuleGetGlobal(hipDeviceptr_t *dptr, size_t *bytes, hipModule_t hmod, const char *name)¶

Returns a global pointer from a module. Returns in *dptr and *bytes the pointer and size of the global of name name located in module hmod. If no variable of that name exists, it returns hipErrorNotFound. Both parameters dptr and bytes are optional. If one of them is NULL, it is ignored and hipSuccess is returned.

Parameters:

dptr – [out] Returns global device pointer
bytes – [out] Returns global size in bytes
hmod – [in] Module to retrieve global from
name – [in] Name of global to retrieve

Returns:

hipSuccess, hipErrorInvalidValue, hipErrorNotFound, hipErrorInvalidContext

hipError_t hipGetSymbolAddress(void **devPtr, const void *symbol)¶

Gets device pointer associated with symbol on the device.

Parameters:

devPtr – [out] pointer to the device associated the symbole
symbol – [in] pointer to the symbole of the device

Returns:

hipError_t hipGetSymbolSize(size_t *size, const void *symbol)¶

Gets the size of the given symbol on the device.

Parameters:

symbol – [in] pointer to the device symbole
size – [out] pointer to the size

Returns:

hipError_t hipMemcpyToSymbol (const void *symbol, const void *src, size_t sizeBytes, size_t offset __dparm(0), hipMemcpyKind kind __dparm(hipMemcpyHostToDevice))

Copies data to the given symbol on the device. Symbol HIP APIs allow a kernel to define a device-side data symbol which can be accessed on the host side. The symbol can be in __constant or device space. Note that the symbol name needs to be encased in the HIP_SYMBOL macro. This also applies to hipMemcpyFromSymbol, hipGetSymbolAddress, and hipGetSymbolSize. For detail usage, see the example at https://github.com/ROCm-Developer-Tools/HIP/blob/rocm-5.0.x/docs/markdown/hip_porting_guide.md.

Parameters:

symbol – [out] pointer to the device symbole
src – [in] pointer to the source address
sizeBytes – [in] size in bytes to copy
offset – [in] offset in bytes from start of symbole
kind – [in] type of memory transfer

Returns:

hipError_t hipMemcpyToSymbolAsync (const void *symbol, const void *src, size_t sizeBytes, size_t offset, hipMemcpyKind kind, hipStream_t stream __dparm(0))

Copies data to the given symbol on the device asynchronously.

Parameters:

symbol – [out] pointer to the device symbole
src – [in] pointer to the source address
sizeBytes – [in] size in bytes to copy
offset – [in] offset in bytes from start of symbole
kind – [in] type of memory transfer
stream – [in] stream identifier

Returns:

hipError_t hipMemcpyFromSymbol (void *dst, const void *symbol, size_t sizeBytes, size_t offset __dparm(0), hipMemcpyKind kind __dparm(hipMemcpyDeviceToHost))

Copies data from the given symbol on the device.

Parameters:

dptr – [out] Returns pointer to destinition memory address
symbol – [in] pointer to the symbole address on the device
sizeBytes – [in] size in bytes to copy
offset – [in] offset in bytes from the start of symbole
kind – [in] type of memory transfer

Returns:

hipError_t hipMemcpyFromSymbolAsync (void *dst, const void *symbol, size_t sizeBytes, size_t offset, hipMemcpyKind kind, hipStream_t stream __dparm(0))

Copies data from the given symbol on the device asynchronously.

Parameters:

dptr – [out] Returns pointer to destinition memory address
symbol – [in] pointer to the symbole address on the device
sizeBytes – [in] size in bytes to copy
offset – [in] offset in bytes from the start of symbole
kind – [in] type of memory transfer
stream – [in] stream identifier

Returns:

hipSuccess, hipErrorInvalidValue, hipErrorNotInitialized

hipError_t hipMemcpyAsync (void *dst, const void *src, size_t sizeBytes, hipMemcpyKind kind, hipStream_t stream __dparm(0))

Copy data from src to dst asynchronously.

For multi-gpu or peer-to-peer configurations, it is recommended to use a stream which is a attached to the device where the src data is physically located. For optimal peer-to-peer copies, the copy device must be able to access the src and dst pointers (by calling hipDeviceEnablePeerAccess with copy agent as the current device and src/dest as the peerDevice argument. if this is not done, the hipMemcpy will still work, but will perform the copy using a staging buffer on the host.

See also

hipMemcpy, hipMemcpy2D, hipMemcpyToArray, hipMemcpy2DToArray, hipMemcpyFromArray, hipMemcpy2DFromArray, hipMemcpyArrayToArray, hipMemcpy2DArrayToArray, hipMemcpyToSymbol, hipMemcpyFromSymbol, hipMemcpy2DAsync, hipMemcpyToArrayAsync, hipMemcpy2DToArrayAsync, hipMemcpyFromArrayAsync, hipMemcpy2DFromArrayAsync, hipMemcpyToSymbolAsync, hipMemcpyFromSymbolAsync

Warning

If host or dest are not pinned, the memory copy will be performed synchronously. For best performance, use hipHostMalloc to allocate host memory that is transferred asynchronously.

Warning

on HCC hipMemcpyAsync does not support overlapped H2D and D2H copies. For hipMemcpy, the copy is always performed by the device associated with the specified stream.

Parameters:

dst – [out] Data being copy to
src – [in] Data being copy from
sizeBytes – [in] Data size in bytes
accelerator_view – [in] Accelerator view which the copy is being enqueued

Returns:

hipSuccess, hipErrorInvalidValue, #hipErrorMemoryFree, hipErrorUnknown

hipError_t hipMemset(void *dst, int value, size_t sizeBytes)¶

Fills the first sizeBytes bytes of the memory area pointed to by dest with the constant byte value value.

Parameters:

dst – [out] Data being filled
constant – [in] value to be set
sizeBytes – [in] Data size in bytes

Returns:

hipError_t hipMemsetD8(hipDeviceptr_t dest, unsigned char value, size_t count)¶

Fills the first sizeBytes bytes of the memory area pointed to by dest with the constant byte value value.

Parameters:

dst – [out] Data ptr to be filled
constant – [in] value to be set
number – [in] of values to be set

Returns:

hipSuccess, hipErrorInvalidValue, hipErrorNotInitialized

hipError_t hipMemsetD8Async (hipDeviceptr_t dest, unsigned char value, size_t count, hipStream_t stream __dparm(0))

Fills the first sizeBytes bytes of the memory area pointed to by dest with the constant byte value value.

hipMemsetD8Async() is asynchronous with respect to the host, so the call may return before the memset is complete. The operation can optionally be associated to a stream by passing a non-zero stream argument. If stream is non-zero, the operation may overlap with operations in other streams.

Parameters:

dst – [out] Data ptr to be filled
constant – [in] value to be set
number – [in] of values to be set
stream – [in] - Stream identifier

Returns:

hipSuccess, hipErrorInvalidValue, hipErrorNotInitialized

hipError_t hipMemsetD16(hipDeviceptr_t dest, unsigned short value, size_t count)¶

Fills the first sizeBytes bytes of the memory area pointed to by dest with the constant short value value.

Parameters:

dst – [out] Data ptr to be filled
constant – [in] value to be set
number – [in] of values to be set

Returns:

hipSuccess, hipErrorInvalidValue, hipErrorNotInitialized

hipError_t hipMemsetD16Async (hipDeviceptr_t dest, unsigned short value, size_t count, hipStream_t stream __dparm(0))

Fills the first sizeBytes bytes of the memory area pointed to by dest with the constant short value value.

hipMemsetD16Async() is asynchronous with respect to the host, so the call may return before the memset is complete. The operation can optionally be associated to a stream by passing a non-zero stream argument. If stream is non-zero, the operation may overlap with operations in other streams.

Parameters:

dst – [out] Data ptr to be filled
constant – [in] value to be set
number – [in] of values to be set
stream – [in] - Stream identifier

Returns:

hipSuccess, hipErrorInvalidValue, hipErrorNotInitialized

hipError_t hipMemsetD32(hipDeviceptr_t dest, int value, size_t count)¶

Fills the memory area pointed to by dest with the constant integer value for specified number of times.

Parameters:

dst – [out] Data being filled
constant – [in] value to be set
number – [in] of values to be set

Returns:

hipSuccess, hipErrorInvalidValue, hipErrorNotInitialized

hipError_t hipMemsetAsync (void *dst, int value, size_t sizeBytes, hipStream_t stream __dparm(0))

Fills the first sizeBytes bytes of the memory area pointed to by dev with the constant byte value value.

hipMemsetAsync() is asynchronous with respect to the host, so the call may return before the memset is complete. The operation can optionally be associated to a stream by passing a non-zero stream argument. If stream is non-zero, the operation may overlap with operations in other streams.

Parameters:

dst – [out] Pointer to device memory
value – [in] - Value to set for each byte of specified memory
sizeBytes – [in] - Size in bytes to set
stream – [in] - Stream identifier

Returns:

hipSuccess, hipErrorInvalidValue, #hipErrorMemoryFree

hipError_t hipMemsetD32Async (hipDeviceptr_t dst, int value, size_t count, hipStream_t stream __dparm(0))

Fills the memory area pointed to by dev with the constant integer value for specified number of times.

hipMemsetD32Async() is asynchronous with respect to the host, so the call may return before the memset is complete. The operation can optionally be associated to a stream by passing a non-zero stream argument. If stream is non-zero, the operation may overlap with operations in other streams.

Parameters:

dst – [out] Pointer to device memory
value – [in] - Value to set for each byte of specified memory
count – [in] - number of values to be set
stream – [in] - Stream identifier

Returns:

hipSuccess, hipErrorInvalidValue, #hipErrorMemoryFree

hipError_t hipMemset2D(void *dst, size_t pitch, int value, size_t width, size_t height)¶

Fills the memory area pointed to by dst with the constant value.

Parameters:

dst – [out] Pointer to device memory
pitch – [in] - data size in bytes
value – [in] - constant value to be set
width – [in]
height – [in]

Returns:

hipSuccess, hipErrorInvalidValue, #hipErrorMemoryFree

hipError_t hipMemset2DAsync (void *dst, size_t pitch, int value, size_t width, size_t height, hipStream_t stream __dparm(0))

Fills asynchronously the memory area pointed to by dst with the constant value.

Parameters:

dst – [in] Pointer to device memory
pitch – [in] - data size in bytes
value – [in] - constant value to be set
width – [in]
height – [in]
stream – [in]

Returns:

hipSuccess, hipErrorInvalidValue, #hipErrorMemoryFree

hipError_t hipMemset3D(hipPitchedPtr pitchedDevPtr, int value, hipExtent extent)¶

Fills synchronously the memory area pointed to by pitchedDevPtr with the constant value.

Parameters:

pitchedDevPtr – [in]
value – [in] - constant value to be set
extent – [in]

Returns:

hipSuccess, hipErrorInvalidValue, #hipErrorMemoryFree

hipError_t hipMemset3DAsync (hipPitchedPtr pitchedDevPtr, int value, hipExtent extent, hipStream_t stream __dparm(0))

Fills asynchronously the memory area pointed to by pitchedDevPtr with the constant value.

Parameters:

pitchedDevPtr – [in]
value – [in] - constant value to be set
extent – [in]
stream – [in]

Returns:

hipSuccess, hipErrorInvalidValue, #hipErrorMemoryFree

hipError_t hipMemGetInfo(size_t *free, size_t *total)¶

Query memory info. Return snapshot of free memory, and total allocatable memory on the device.

Returns in *free a snapshot of the current free memory.

Warning

On HCC, the free memory only accounts for memory allocated by this process and may be optimistic.

Returns:: hipSuccess, hipErrorInvalidDevice, hipErrorInvalidValue

hipError_t hipMemPtrGetInfo(void *ptr, size_t *size)¶

hipError_t hipMallocArray (hipArray **array, const hipChannelFormatDesc *desc, size_t width, size_t height __dparm(0), unsigned int flags __dparm(hipArrayDefault))

Allocate an array on the device.

Parameters:

array – [out] Pointer to allocated array in device memory
desc – [in] Requested channel format
width – [in] Requested array allocation width
height – [in] Requested array allocation height
flags – [in] Requested properties of allocated array

Returns:

hipSuccess, hipErrorInvalidValue, hipErrorNotInitialized

hipError_t hipArrayCreate(hipArray **pHandle, const HIP_ARRAY_DESCRIPTOR *pAllocateArray)¶

hipError_t hipArrayDestroy(hipArray *array)¶

hipError_t hipArray3DCreate(hipArray **array, const HIP_ARRAY3D_DESCRIPTOR *pAllocateArray)¶

hipError_t hipMalloc3D(hipPitchedPtr *pitchedDevPtr, hipExtent extent)¶

hipError_t hipFreeArray(hipArray *array)¶

Frees an array on the device.

Parameters:

array – [in] Pointer to array to free

Returns:

hipError_t hipFreeMipmappedArray(hipMipmappedArray_t mipmappedArray)¶

Frees a mipmapped array on the device.

Parameters:

mipmappedArray – [in] - Pointer to mipmapped array to free

Returns:

hipError_t hipMalloc3DArray(hipArray **array, const struct hipChannelFormatDesc *desc, struct hipExtent extent, unsigned int flags)¶

Allocate an array on the device.

Parameters:

array – [out] Pointer to allocated array in device memory
desc – [in] Requested channel format
extent – [in] Requested array allocation width, height and depth
flags – [in] Requested properties of allocated array

Returns:

hipSuccess, hipErrorInvalidValue, hipErrorMemoryAllocation

hipError_t hipMallocMipmappedArray (hipMipmappedArray_t *mipmappedArray, const struct hipChannelFormatDesc *desc, struct hipExtent extent, unsigned int numLevels, unsigned int flags __dparm(0))

Allocate a mipmapped array on the device.

Parameters:

mipmappedArray – [out] - Pointer to allocated mipmapped array in device memory
desc – [in] - Requested channel format
extent – [in] - Requested allocation size (width field in elements)
numLevels – [in] - Number of mipmap levels to allocate
flags – [in] - Flags for extensions

Returns:

hipError_t hipGetMipmappedArrayLevel(hipArray_t *levelArray, hipMipmappedArray_const_t mipmappedArray, unsigned int level)¶

Gets a mipmap level of a HIP mipmapped array.

Parameters:

levelArray – [out] - Returned mipmap level HIP array
mipmappedArray – [in] - HIP mipmapped array
level – [in] - Mipmap level

Returns:

hipSuccess, hipErrorInvalidValue, hipErrorInvalidPitchValue, hipErrorInvalidDevicePointer, hipErrorInvalidMemcpyDirection

hipError_t hipMemcpy2D(void *dst, size_t dpitch, const void *src, size_t spitch, size_t width, size_t height, hipMemcpyKind kind)¶

Copies data between host and device.

Parameters:

dst – [in] Destination memory address
dpitch – [in] Pitch of destination memory
src – [in] Source memory address
spitch – [in] Pitch of source memory
width – [in] Width of matrix transfer (columns in bytes)
height – [in] Height of matrix transfer (rows)
kind – [in] Type of transfer

Returns:

hipError_t hipMemcpyParam2D(const hip_Memcpy2D *pCopy)¶

Copies memory for 2D arrays.

Parameters:

pCopy – [in] Parameters for the memory copy

Returns:

hipSuccess, hipErrorInvalidValue, hipErrorInvalidPitchValue, hipErrorInvalidDevicePointer, hipErrorInvalidMemcpyDirection

hipError_t hipMemcpyParam2DAsync (const hip_Memcpy2D *pCopy, hipStream_t stream __dparm(0))

Copies memory for 2D arrays.

Parameters:

pCopy – [in] Parameters for the memory copy
stream – [in] Stream to use

Returns:

hipSuccess, hipErrorInvalidValue, hipErrorInvalidPitchValue, hipErrorInvalidDevicePointer, hipErrorInvalidMemcpyDirection

hipError_t hipMemcpy2DAsync (void *dst, size_t dpitch, const void *src, size_t spitch, size_t width, size_t height, hipMemcpyKind kind, hipStream_t stream __dparm(0))

Copies data between host and device.

Parameters:

dst – [in] Destination memory address
dpitch – [in] Pitch of destination memory
src – [in] Source memory address
spitch – [in] Pitch of source memory
width – [in] Width of matrix transfer (columns in bytes)
height – [in] Height of matrix transfer (rows)
kind – [in] Type of transfer
stream – [in] Stream to use

Returns:

hipSuccess, hipErrorInvalidValue, hipErrorInvalidPitchValue, hipErrorInvalidDevicePointer, hipErrorInvalidMemcpyDirection

hipError_t hipMemcpy2DToArray(hipArray *dst, size_t wOffset, size_t hOffset, const void *src, size_t spitch, size_t width, size_t height, hipMemcpyKind kind)¶

Copies data between host and device.

Parameters:

dst – [in] Destination memory address
wOffset – [in] Destination starting X offset
hOffset – [in] Destination starting Y offset
src – [in] Source memory address
spitch – [in] Pitch of source memory
width – [in] Width of matrix transfer (columns in bytes)
height – [in] Height of matrix transfer (rows)
kind – [in] Type of transfer

Returns:

hipSuccess, hipErrorInvalidValue, hipErrorInvalidPitchValue, hipErrorInvalidDevicePointer, hipErrorInvalidMemcpyDirection

hipError_t hipMemcpy2DToArrayAsync (hipArray *dst, size_t wOffset, size_t hOffset, const void *src, size_t spitch, size_t width, size_t height, hipMemcpyKind kind, hipStream_t stream __dparm(0))

Copies data between host and device.

Parameters:

dst – [in] Destination memory address
wOffset – [in] Destination starting X offset
hOffset – [in] Destination starting Y offset
src – [in] Source memory address
spitch – [in] Pitch of source memory
width – [in] Width of matrix transfer (columns in bytes)
height – [in] Height of matrix transfer (rows)
kind – [in] Type of transfer
stream – [in] Accelerator view which the copy is being enqueued

Returns:

hipSuccess, hipErrorInvalidValue, hipErrorInvalidPitchValue, hipErrorInvalidDevicePointer, hipErrorInvalidMemcpyDirection

hipError_t hipMemcpyToArray(hipArray *dst, size_t wOffset, size_t hOffset, const void *src, size_t count, hipMemcpyKind kind)¶

Copies data between host and device.

Parameters:

dst – [in] Destination memory address
wOffset – [in] Destination starting X offset
hOffset – [in] Destination starting Y offset
src – [in] Source memory address
count – [in] size in bytes to copy
kind – [in] Type of transfer

Returns:

hipSuccess, hipErrorInvalidValue, hipErrorInvalidPitchValue, hipErrorInvalidDevicePointer, hipErrorInvalidMemcpyDirection

hipError_t hipMemcpyFromArray(void *dst, hipArray_const_t srcArray, size_t wOffset, size_t hOffset, size_t count, hipMemcpyKind kind)¶

Copies data between host and device.

Parameters:

dst – [in] Destination memory address
srcArray – [in] Source memory address
woffset – [in] Source starting X offset
hOffset – [in] Source starting Y offset
count – [in] Size in bytes to copy
kind – [in] Type of transfer

Returns:

hipSuccess, hipErrorInvalidValue, hipErrorInvalidPitchValue, hipErrorInvalidDevicePointer, hipErrorInvalidMemcpyDirection

hipError_t hipMemcpy2DFromArray(void *dst, size_t dpitch, hipArray_const_t src, size_t wOffset, size_t hOffset, size_t width, size_t height, hipMemcpyKind kind)¶

Copies data between host and device.

Parameters:

dst – [in] Destination memory address
dpitch – [in] Pitch of destination memory
src – [in] Source memory address
wOffset – [in] Source starting X offset
hOffset – [in] Source starting Y offset
width – [in] Width of matrix transfer (columns in bytes)
height – [in] Height of matrix transfer (rows)
kind – [in] Type of transfer

Returns:

hipSuccess, hipErrorInvalidValue, hipErrorInvalidPitchValue, hipErrorInvalidDevicePointer, hipErrorInvalidMemcpyDirection

hipError_t hipMemcpy2DFromArrayAsync (void *dst, size_t dpitch, hipArray_const_t src, size_t wOffset, size_t hOffset, size_t width, size_t height, hipMemcpyKind kind, hipStream_t stream __dparm(0))

Copies data between host and device asynchronously.

Parameters:

dst – [in] Destination memory address
dpitch – [in] Pitch of destination memory
src – [in] Source memory address
wOffset – [in] Source starting X offset
hOffset – [in] Source starting Y offset
width – [in] Width of matrix transfer (columns in bytes)
height – [in] Height of matrix transfer (rows)
kind – [in] Type of transfer
stream – [in] Accelerator view which the copy is being enqueued

Returns:

hipSuccess, hipErrorInvalidValue, hipErrorInvalidPitchValue, hipErrorInvalidDevicePointer, hipErrorInvalidMemcpyDirection

hipError_t hipMemcpyAtoH(void *dst, hipArray *srcArray, size_t srcOffset, size_t count)¶

Copies data between host and device.

Parameters:

dst – [in] Destination memory address
srcArray – [in] Source array
srcoffset – [in] Offset in bytes of source array
count – [in] Size of memory copy in bytes

Returns:

hipSuccess, hipErrorInvalidValue, hipErrorInvalidPitchValue, hipErrorInvalidDevicePointer, hipErrorInvalidMemcpyDirection

hipError_t hipMemcpyHtoA(hipArray *dstArray, size_t dstOffset, const void *srcHost, size_t count)¶

Copies data between host and device.

Parameters:

dstArray – [in] Destination memory address
dstOffset – [in] Offset in bytes of destination array
srcHost – [in] Source host pointer
count – [in] Size of memory copy in bytes

Returns:

hipSuccess, hipErrorInvalidValue, hipErrorInvalidPitchValue, hipErrorInvalidDevicePointer, hipErrorInvalidMemcpyDirection

hipError_t hipMemcpy3D(const struct hipMemcpy3DParms *p)¶

Copies data between host and device.

Parameters:

p – [in] 3D memory copy parameters

Returns:

hipSuccess, hipErrorInvalidValue, hipErrorInvalidPitchValue, hipErrorInvalidDevicePointer, hipErrorInvalidMemcpyDirection

hipError_t hipMemcpy3DAsync (const struct hipMemcpy3DParms *p, hipStream_t stream __dparm(0))

Copies data between host and device asynchronously.

Parameters:

p – [in] 3D memory copy parameters
stream – [in] Stream to use

Returns:

hipSuccess, hipErrorInvalidValue, hipErrorInvalidPitchValue, hipErrorInvalidDevicePointer, hipErrorInvalidMemcpyDirection

hipError_t hipDrvMemcpy3D(const HIP_MEMCPY3D *pCopy)¶

Copies data between host and device.

Parameters:

pCopy – [in] 3D memory copy parameters

Returns:

hipSuccess, hipErrorInvalidValue, hipErrorInvalidPitchValue, hipErrorInvalidDevicePointer, hipErrorInvalidMemcpyDirection

hipError_t hipDrvMemcpy3DAsync(const HIP_MEMCPY3D *pCopy, hipStream_t stream)¶

Copies data between host and device asynchronously.

Parameters:

pCopy – [in] 3D memory copy parameters
stream – [in] Stream to use

Returns:

hipSuccess, hipErrorInvalidValue, hipErrorInvalidPitchValue, hipErrorInvalidDevicePointer, hipErrorInvalidMemcpyDirection

hipError_t hipDeviceCanAccessPeer(int *canAccessPeer, int deviceId, int peerDeviceId)¶

Determine if a device can access a peer’s memory.

Returns “1” in canAccessPeer if the specified device is capable of directly accessing memory physically located on peerDevice , or “0” if not.

Returns “0” in canAccessPeer if deviceId == peerDeviceId, and both are valid devices : a device is not a peer of itself.

Parameters:

canAccessPeer – [out] Returns the peer access capability (0 or 1)
device – [in] - device from where memory may be accessed.
peerDevice – [in] - device where memory is physically located

Returns:

hipSuccess,

Returns:

hipErrorInvalidDevice if deviceId or peerDeviceId are not valid devices

hipError_t hipDeviceEnablePeerAccess(int peerDeviceId, unsigned int flags)¶

Enable direct access from current device’s virtual address space to memory allocations physically located on a peer device.

Memory which already allocated on peer device will be mapped into the address space of the current device. In addition, all future memory allocations on peerDeviceId will be mapped into the address space of the current device when the memory is allocated. The peer memory remains accessible from the current device until a call to hipDeviceDisablePeerAccess or hipDeviceReset.

Parameters:

peerDeviceId – [in]
flags – [in] Returns hipSuccess, hipErrorInvalidDevice, hipErrorInvalidValue,

Returns:

hipErrorPeerAccessAlreadyEnabled if peer access is already enabled for this device.

hipError_t hipDeviceDisablePeerAccess(int peerDeviceId)¶

Disable direct access from current device’s virtual address space to memory allocations physically located on a peer device.

Returns hipErrorPeerAccessNotEnabled if direct access to memory on peerDevice has not yet been enabled from the current device.

Parameters:

peerDeviceId – [in]

Returns:

hipSuccess, hipErrorPeerAccessNotEnabled

hipError_t hipMemGetAddressRange(hipDeviceptr_t *pbase, size_t *psize, hipDeviceptr_t dptr)¶

Get information on memory allocations.

Parameters:

pbase – [out] - BAse pointer address
psize – [out] - Size of allocation
dptr- – [in] Device Pointer

Returns:

hipSuccess, hipErrorInvalidDevicePointer

hipError_t hipMemcpyPeer(void *dst, int dstDeviceId, const void *src, int srcDeviceId, size_t sizeBytes)¶

Copies memory from one device to memory on another device.

Parameters:

dst – [out] - Destination device pointer.
dstDeviceId – [in] - Destination device
src – [in] - Source device pointer
srcDeviceId – [in] - Source device
sizeBytes – [in] - Size of memory copy in bytes

Returns:

hipSuccess, hipErrorInvalidValue, hipErrorInvalidDevice

hipError_t hipMemcpyPeerAsync (void *dst, int dstDeviceId, const void *src, int srcDevice, size_t sizeBytes, hipStream_t stream __dparm(0))

Copies memory from one device to memory on another device.

Parameters:

dst – [out] - Destination device pointer.
dstDevice – [in] - Destination device
src – [in] - Source device pointer
srcDevice – [in] - Source device
sizeBytes – [in] - Size of memory copy in bytes
stream – [in] - Stream identifier

Returns:

hipSuccess, hipErrorInvalidValue, hipErrorInvalidDevice

hipError_t hipCtxCreate(hipCtx_t *ctx, unsigned int flags, hipDevice_t device)¶

Create a context and set it as current/ default context.

Parameters:

ctx – [out]
flags – [in]
associated – [in] device handle

Returns:

hipError_t hipCtxDestroy(hipCtx_t ctx)¶

Destroy a HIP context.

Parameters:

ctx – [in] Context to destroy

Returns:

hipError_t hipCtxPopCurrent(hipCtx_t *ctx)¶

Pop the current/default context and return the popped context.

Parameters:

ctx – [out]

Returns:

hipError_t hipCtxPushCurrent(hipCtx_t ctx)¶

Push the context to be set as current/ default context.

Parameters:

ctx – [in]

Returns:

hipError_t hipCtxSetCurrent(hipCtx_t ctx)¶

Set the passed context as current/default.

Parameters:

ctx – [in]

Returns:

hipError_t hipCtxGetCurrent(hipCtx_t *ctx)¶

Get the handle of the current/ default context.

Parameters:

ctx – [out]

Returns:

hipError_t hipCtxGetDevice(hipDevice_t *device)¶

Get the handle of the device associated with current/default context.

Parameters:

device – [out]

Returns:

hipError_t hipCtxGetApiVersion(hipCtx_t ctx, int *apiVersion)¶

Returns the approximate HIP api version.

Warning

The HIP feature set does not correspond to an exact CUDA SDK api revision. This function always set *apiVersion to 4 as an approximation though HIP supports some features which were introduced in later CUDA SDK revisions. HIP apps code should not rely on the api revision number here and should use arch feature flags to test device capabilities or conditional compilation.

Parameters:

ctx – [in] Context to check
apiVersion – [out]

Returns:

hipError_t hipCtxGetCacheConfig(hipFuncCache_t *cacheConfig)¶

Set Cache configuration for a specific function.

Warning

AMD devices and some Nvidia GPUS do not support reconfigurable cache. This hint is ignored on those architectures.

Parameters:

cacheConfiguration – [out]

Returns:

hipError_t hipCtxSetCacheConfig(hipFuncCache_t cacheConfig)¶

Set L1/Shared cache partition.

Warning

AMD devices and some Nvidia GPUS do not support reconfigurable cache. This hint is ignored on those architectures.

Parameters:

cacheConfiguration – [in]

Returns:

hipError_t hipCtxSetSharedMemConfig(hipSharedMemConfig config)¶

Set Shared memory bank configuration.

Warning

AMD devices and some Nvidia GPUS do not support shared cache banking, and the hint is ignored on those architectures.

Parameters:

sharedMemoryConfiguration – [in]

Returns:

hipError_t hipCtxGetSharedMemConfig(hipSharedMemConfig *pConfig)¶

Get Shared memory bank configuration.

Warning

AMD devices and some Nvidia GPUS do not support shared cache banking, and the hint is ignored on those architectures.

Parameters:

sharedMemoryConfiguration – [out]

Returns:

hipError_t hipCtxSynchronize(void)¶

Blocks until the default context has completed all preceding requested tasks.

Warning

This function waits for all streams on the default context to complete execution, and then returns.

Returns:: hipSuccess

hipError_t hipCtxGetFlags(unsigned int *flags)¶

Return flags used for creating default context.

Parameters:

flags – [out]

Returns:

hipSuccess, hipErrorInvalidDevice, hipErrorInvalidValue, hipErrorPeerAccessAlreadyEnabled

hipError_t hipCtxEnablePeerAccess(hipCtx_t peerCtx, unsigned int flags)¶

Enables direct access to memory allocations in a peer context.

Memory which already allocated on peer device will be mapped into the address space of the current device. In addition, all future memory allocations on peerDeviceId will be mapped into the address space of the current device when the memory is allocated. The peer memory remains accessible from the current device until a call to hipDeviceDisablePeerAccess or hipDeviceReset.

Warning

PeerToPeer support is experimental.

Parameters:

peerCtx – [in]
flags – [in]

Returns:

hipError_t hipCtxDisablePeerAccess(hipCtx_t peerCtx)¶

Disable direct access from current context’s virtual address space to memory allocations physically located on a peer context.Disables direct access to memory allocations in a peer context and unregisters any registered allocations.

Returns hipErrorPeerAccessNotEnabled if direct access to memory on peerDevice has not yet been enabled from the current device.

Warning

PeerToPeer support is experimental.

Parameters:

peerCtx – [in]

Returns:

hipSuccess, hipErrorPeerAccessNotEnabled

hipError_t hipDevicePrimaryCtxGetState(hipDevice_t dev, unsigned int *flags, int *active)¶

Get the state of the primary context.

Parameters:

Device – [in] to get primary context flags for
Pointer – [out] to store flags
Pointer – [out] to store context state; 0 = inactive, 1 = active

Returns:

hipError_t hipDevicePrimaryCtxRelease(hipDevice_t dev)¶

Release the primary context on the GPU.

Warning

This function return hipSuccess though doesn’t release the primaryCtx by design on HIP/HCC path.

Parameters:

Device – [in] which primary context is released

Returns:

hipError_t hipDevicePrimaryCtxRetain(hipCtx_t *pctx, hipDevice_t dev)¶

Retain the primary context on the GPU.

Parameters:

Returned – [out] context handle of the new context
Device – [in] which primary context is released

Returns:

hipError_t hipDevicePrimaryCtxReset(hipDevice_t dev)¶

Resets the primary context on the GPU.

Parameters:

Device – [in] which primary context is reset

Returns:

hipSuccess, hipErrorContextAlreadyInUse

hipError_t hipDevicePrimaryCtxSetFlags(hipDevice_t dev, unsigned int flags)¶

Set flags for the primary context.

Parameters:

Device – [in] for which the primary context flags are set
New – [in] flags for the device

Returns:

hipError_t hipModuleLoad(hipModule_t *module, const char *fname)¶

Loads code object from file into a hipModule_t.

Warning

File/memory resources allocated in this function are released only in hipModuleUnload.

Parameters:

fname – [in]
module – [out]

Returns:

hipSuccess, hipErrorInvalidValue, hipErrorInvalidContext, hipErrorFileNotFound, hipErrorOutOfMemory, hipErrorSharedObjectInitFailed, hipErrorNotInitialized

hipError_t hipModuleUnload(hipModule_t module)¶

Frees the module.

Parameters:

module – [in]

Returns:

hipSuccess, hipInvalidValue module is freed and the code objects associated with it are destroyed

hipError_t hipModuleGetFunction(hipFunction_t *function, hipModule_t module, const char *kname)¶

Function with kname will be extracted if present in module.

Parameters:

module – [in]
kname – [in]
function – [out]

Returns:

hipSuccess, hipErrorInvalidValue, hipErrorInvalidContext, hipErrorNotInitialized, hipErrorNotFound,

hipError_t hipFuncGetAttributes(struct hipFuncAttributes *attr, const void *func)¶

Find out attributes for a given function.

Parameters:

attr – [out]
func – [in]

Returns:

hipSuccess, hipErrorInvalidValue, hipErrorInvalidDeviceFunction

hipError_t hipFuncGetAttribute(int *value, hipFunction_attribute attrib, hipFunction_t hfunc)¶

Find out a specific attribute for a given function.

Parameters:

value – [out]
attrib – [in]
hfunc – [in]

Returns:

hipSuccess, hipErrorInvalidValue, hipErrorInvalidDeviceFunction

hipError_t hipModuleGetTexRef(textureReference **texRef, hipModule_t hmod, const char *name)¶

returns the handle of the texture reference with the name from the module.

Parameters:

hmod – [in]
name – [in]
texRef – [out]

Returns:

hipSuccess, hipErrorNotInitialized, hipErrorNotFound, hipErrorInvalidValue

hipError_t hipModuleLoadData(hipModule_t *module, const void *image)¶

builds module from code object which resides in host memory. Image is pointer to that location.

Parameters:

image – [in]
module – [out]

Returns:

hipSuccess, hipErrorNotInitialized, hipErrorOutOfMemory, hipErrorNotInitialized

hipError_t hipModuleLoadDataEx(hipModule_t *module, const void *image, unsigned int numOptions, hipJitOption *options, void **optionValues)¶

builds module from code object which resides in host memory. Image is pointer to that location. Options are not used. hipModuleLoadData is called.

Parameters:

image – [in]
module – [out]
number – [in] of options
options – [in] for JIT
option – [in] values for JIT

Returns:

hipSuccess, hipErrorNotInitialized, hipErrorOutOfMemory, hipErrorNotInitialized

hipError_t hipModuleLaunchKernel(hipFunction_t f, unsigned int gridDimX, unsigned int gridDimY, unsigned int gridDimZ, unsigned int blockDimX, unsigned int blockDimY, unsigned int blockDimZ, unsigned int sharedMemBytes, hipStream_t stream, void **kernelParams, void **extra)¶

launches kernel f with launch parameters and shared memory on stream with arguments passed to kernelparams or extra

Please note, HIP does not support kernel launch with total work items defined in dimension with size gridDim x blockDim >= 2^32. So gridDim.x * blockDim.x, gridDim.y * blockDim.y and gridDim.z * blockDim.z are always less than 2^32.

Warning

kernellParams argument is not yet implemented in HIP. Please use extra instead. Please refer to hip_porting_driver_api.md for sample usage.

Parameters:

f – [in] Kernel to launch.
gridDimX – [in] X grid dimension specified as multiple of blockDimX.
gridDimY – [in] Y grid dimension specified as multiple of blockDimY.
gridDimZ – [in] Z grid dimension specified as multiple of blockDimZ.
blockDimX – [in] X block dimensions specified in work-items
blockDimY – [in] Y grid dimension specified in work-items
blockDimZ – [in] Z grid dimension specified in work-items
sharedMemBytes – [in] Amount of dynamic shared memory to allocate for this kernel. The HIP-Clang compiler provides support for extern shared declarations.
stream – [in] Stream where the kernel should be dispatched. May be 0, in which case th default stream is used with associated synchronization rules.
kernelParams – [in]
extra – [in] Pointer to kernel arguments. These are passed directly to the kernel and must be in the memory layout and alignment expected by the kernel.

Returns:

hipSuccess, hipInvalidDevice, hipErrorNotInitialized, hipErrorInvalidValue

hipError_t hipLaunchCooperativeKernel(const void *f, dim3 gridDim, dim3 blockDimX, void **kernelParams, unsigned int sharedMemBytes, hipStream_t stream)¶

launches kernel f with launch parameters and shared memory on stream with arguments passed to kernelparams or extra, where thread blocks can cooperate and synchronize as they execute

Please note, HIP does not support kernel launch with total work items defined in dimension with size gridDim x blockDim >= 2^32.

Parameters:

f – [in] Kernel to launch.
gridDim – [in] Grid dimensions specified as multiple of blockDim.
blockDim – [in] Block dimensions specified in work-items
kernelParams – [in] A list of kernel arguments
sharedMemBytes – [in] Amount of dynamic shared memory to allocate for this kernel. The HIP-Clang compiler provides support for extern shared declarations.
stream – [in] Stream where the kernel should be dispatched. May be 0, in which case th default stream is used with associated synchronization rules.

Returns:

hipSuccess, hipInvalidDevice, hipErrorNotInitialized, hipErrorInvalidValue, hipErrorCooperativeLaunchTooLarge

hipError_t hipLaunchCooperativeKernelMultiDevice(hipLaunchParams *launchParamsList, int numDevices, unsigned int flags)¶

Launches kernels on multiple devices where thread blocks can cooperate and synchronize as they execute.

Parameters:

launchParamsList – [in] List of launch parameters, one per device.
numDevices – [in] Size of the launchParamsList array.
flags – [in] Flags to control launch behavior.

Returns:

hipSuccess, hipInvalidDevice, hipErrorNotInitialized, hipErrorInvalidValue, hipErrorCooperativeLaunchTooLarge

hipError_t hipExtLaunchMultiKernelMultiDevice(hipLaunchParams *launchParamsList, int numDevices, unsigned int flags)¶

Launches kernels on multiple devices and guarantees all specified kernels are dispatched on respective streams before enqueuing any other work on the specified streams from any other threads.

Parameters:

hipLaunchParams – List of launch parameters, one per device.
numDevices – [in] Size of the launchParamsList array.
flags – [in] Flags to control launch behavior.

Returns:

hipSuccess, hipInvalidDevice, hipErrorNotInitialized, hipErrorInvalidValue

hipError_t hipModuleOccupancyMaxPotentialBlockSize(int *gridSize, int *blockSize, hipFunction_t f, size_t dynSharedMemPerBlk, int blockSizeLimit)¶

determine the grid and block sizes to achieves maximum occupancy for a kernel

Please note, HIP does not support kernel launch with total work items defined in dimension with size gridDim x blockDim >= 2^32.

Parameters:

gridSize – [out] minimum grid size for maximum potential occupancy
blockSize – [out] block size for maximum potential occupancy
f – [in] kernel function for which occupancy is calulated
dynSharedMemPerBlk – [in] dynamic shared memory usage (in bytes) intended for each block
blockSizeLimit – [in] the maximum block size for the kernel, use 0 for no limit

Returns:

hipSuccess, hipInvalidDevice, hipErrorInvalidValue

hipError_t hipModuleOccupancyMaxPotentialBlockSizeWithFlags(int *gridSize, int *blockSize, hipFunction_t f, size_t dynSharedMemPerBlk, int blockSizeLimit, unsigned int flags)¶

determine the grid and block sizes to achieves maximum occupancy for a kernel

Please note, HIP does not support kernel launch with total work items defined in dimension with size gridDim x blockDim >= 2^32.

Parameters:

gridSize – [out] minimum grid size for maximum potential occupancy
blockSize – [out] block size for maximum potential occupancy
f – [in] kernel function for which occupancy is calulated
dynSharedMemPerBlk – [in] dynamic shared memory usage (in bytes) intended for each block
blockSizeLimit – [in] the maximum block size for the kernel, use 0 for no limit
flags – [in] Extra flags for occupancy calculation (only default supported)

Returns:

hipSuccess, hipInvalidDevice, hipErrorInvalidValue

hipError_t hipModuleOccupancyMaxActiveBlocksPerMultiprocessor(int *numBlocks, hipFunction_t f, int blockSize, size_t dynSharedMemPerBlk)¶

Returns occupancy for a device function.

Parameters:

numBlocks – [out] Returned occupancy
func – [in] Kernel function (hipFunction) for which occupancy is calulated
blockSize – [in] Block size the kernel is intended to be launched with
dynSharedMemPerBlk – [in] dynamic shared memory usage (in bytes) intended for each block

hipError_t hipModuleOccupancyMaxActiveBlocksPerMultiprocessorWithFlags(int *numBlocks, hipFunction_t f, int blockSize, size_t dynSharedMemPerBlk, unsigned int flags)¶

Returns occupancy for a device function.

Parameters:

numBlocks – [out] Returned occupancy
f – [in] Kernel function(hipFunction_t) for which occupancy is calulated
blockSize – [in] Block size the kernel is intended to be launched with
dynSharedMemPerBlk – [in] dynamic shared memory usage (in bytes) intended for each block
flags – [in] Extra flags for occupancy calculation (only default supported)

hipError_t hipOccupancyMaxActiveBlocksPerMultiprocessor(int *numBlocks, const void *f, int blockSize, size_t dynSharedMemPerBlk)¶

Returns occupancy for a device function.

Parameters:

numBlocks – [out] Returned occupancy
func – [in] Kernel function for which occupancy is calulated
blockSize – [in] Block size the kernel is intended to be launched with
dynSharedMemPerBlk – [in] dynamic shared memory usage (in bytes) intended for each block

hipError_t hipOccupancyMaxActiveBlocksPerMultiprocessorWithFlags (int *numBlocks, const void *f, int blockSize, size_t dynSharedMemPerBlk, unsigned int flags __dparm(hipOccupancyDefault))

Returns occupancy for a device function.

Parameters:

numBlocks – [out] Returned occupancy
f – [in] Kernel function for which occupancy is calulated
blockSize – [in] Block size the kernel is intended to be launched with
dynSharedMemPerBlk – [in] dynamic shared memory usage (in bytes) intended for each block
flags – [in] Extra flags for occupancy calculation (currently ignored)

hipError_t hipOccupancyMaxPotentialBlockSize(int *gridSize, int *blockSize, const void *f, size_t dynSharedMemPerBlk, int blockSizeLimit)¶

determine the grid and block sizes to achieves maximum occupancy for a kernel

Please note, HIP does not support kernel launch with total work items defined in dimension with size gridDim x blockDim >= 2^32.

Parameters:

gridSize – [out] minimum grid size for maximum potential occupancy
blockSize – [out] block size for maximum potential occupancy
f – [in] kernel function for which occupancy is calulated
dynSharedMemPerBlk – [in] dynamic shared memory usage (in bytes) intended for each block
blockSizeLimit – [in] the maximum block size for the kernel, use 0 for no limit

Returns:

hipSuccess, hipInvalidDevice, hipErrorInvalidValue

hipError_t hipProfilerStart()¶: Start recording of profiling information When using this API, start the profiler with profiling disabled. (—startdisabled)

Warning

: hipProfilerStart API is under development.

hipError_t hipProfilerStop()¶: Stop recording of profiling information. When using this API, start the profiler with profiling disabled. (—startdisabled)

Warning

: hipProfilerStop API is under development.

hipError_t hipConfigureCall (dim3 gridDim, dim3 blockDim, size_t sharedMem __dparm(0), hipStream_t stream __dparm(0))

Configure a kernel launch.

Please note, HIP does not support kernel launch with total work items defined in dimension with size gridDim x blockDim >= 2^32.

Parameters:

gridDim – [in] grid dimension specified as multiple of blockDim.
blockDim – [in] block dimensions specified in work-items
sharedMem – [in] Amount of dynamic shared memory to allocate for this kernel. The HIP-Clang compiler provides support for extern shared declarations.
stream – [in] Stream where the kernel should be dispatched. May be 0, in which case the default stream is used with associated synchronization rules.

Returns:

hipSuccess, hipInvalidDevice, hipErrorNotInitialized, hipErrorInvalidValue

hipError_t hipSetupArgument(const void *arg, size_t size, size_t offset)¶

Set a kernel argument.

Parameters:

arg – [in] Pointer the argument in host memory.
size – [in] Size of the argument.
offset – [in] Offset of the argument on the argument stack.

Returns:

hipSuccess, hipInvalidDevice, hipErrorNotInitialized, hipErrorInvalidValue

hipError_t hipLaunchByPtr(const void *func)¶

Launch a kernel.

Parameters:

func – [in] Kernel to launch.

Returns:

hipSuccess, hipInvalidDevice, hipErrorNotInitialized, hipErrorInvalidValue

hipError_t __hipPushCallConfiguration (dim3 gridDim, dim3 blockDim, size_t sharedMem __dparm(0), hipStream_t stream __dparm(0))

Push configuration of a kernel launch.

Please note, HIP does not support kernel launch with total work items defined in dimension with size gridDim x blockDim >= 2^32.

Parameters:

gridDim – [in] grid dimension specified as multiple of blockDim.
blockDim – [in] block dimensions specified in work-items
sharedMem – [in] Amount of dynamic shared memory to allocate for this kernel. The HIP-Clang compiler provides support for extern shared declarations.
stream – [in] Stream where the kernel should be dispatched. May be 0, in which case the default stream is used with associated synchronization rules.

Returns:

hipSuccess, hipInvalidDevice, hipErrorNotInitialized, hipErrorInvalidValue

hipError_t __hipPopCallConfiguration(dim3 *gridDim, dim3 *blockDim, size_t *sharedMem, hipStream_t *stream)¶

Pop configuration of a kernel launch.

Please note, HIP does not support kernel launch with total work items defined in dimension with size gridDim x blockDim >= 2^32.

Parameters:

gridDim – [out] grid dimension specified as multiple of blockDim.
blockDim – [out] block dimensions specified in work-items
sharedMem – [out] Amount of dynamic shared memory to allocate for this kernel. The HIP-Clang compiler provides support for extern shared declarations.
stream – [out] Stream where the kernel should be dispatched. May be 0, in which case the default stream is used with associated synchronization rules.

Returns:

hipSuccess, hipInvalidDevice, hipErrorNotInitialized, hipErrorInvalidValue

hipError_t hipLaunchKernel (const void *function_address, dim3 numBlocks, dim3 dimBlocks, void **args, size_t sharedMemBytes __dparm(0), hipStream_t stream __dparm(0))

C compliant kernel launch API.

Parameters:

function_address – [in] - kernel stub function pointer.
numBlocks – [in] - number of blocks
dimBlocks – [in] - dimension of a block
args – [in] - kernel arguments
sharedMemBytes – [in] - Amount of dynamic shared memory to allocate for this kernel. The HIP-Clang compiler provides support for extern shared declarations.
stream – [in] - Stream where the kernel should be dispatched. May be 0, in which case th default stream is used with associated synchronization rules.

Returns:

hipSuccess, hipErrorInvalidValue, hipInvalidDevice

hipError_t hipDrvMemcpy2DUnaligned(const hip_Memcpy2D *pCopy)¶

Copies memory for 2D arrays.

Parameters:

pCopy – - Parameters for the memory copy

Returns:

hipError_t hipExtLaunchKernel(const void *function_address, dim3 numBlocks, dim3 dimBlocks, void **args, size_t sharedMemBytes, hipStream_t stream, hipEvent_t startEvent, hipEvent_t stopEvent, int flags)¶

Launches kernel from the pointer address, with arguments and shared memory on stream.

Parameters:

function_address – [in] pointer to the Kernel to launch.
numBlocks – [in] number of blocks.
dimBlocks – [in] dimension of a block.
args – [in] pointer to kernel arguments.
sharedMemBytes – [in] Amount of dynamic shared memory to allocate for this kernel. HIP-Clang compiler provides support for extern shared declarations.
stream – [in] Stream where the kernel should be dispatched.
startEvent – [in] If non-null, specified event will be updated to track the start time of the kernel launch. The event must be created before calling this API.
stopEvent – [in] If non-null, specified event will be updated to track the stop time of the kernel launch. The event must be created before calling this API. May be 0, in which case the default stream is used with associated synchronization rules.
flags. – [in] The value of hipExtAnyOrderLaunch, signifies if kernel can be launched in any order.

Returns:

hipSuccess, hipInvalidDevice, hipErrorNotInitialized, hipErrorInvalidValue.

hipError_t hipBindTextureToMipmappedArray(const textureReference *tex, hipMipmappedArray_const_t mipmappedArray, const hipChannelFormatDesc *desc)¶

Binds a mipmapped array to a texture.

Parameters:

tex – [in] pointer to the texture reference to bind
mipmappedArray – [in] memory mipmapped array on the device
desc – [in] opointer to the channel format

Returns:

hipSuccess, hipErrorInvalidValue

hipError_t hipCreateTextureObject(hipTextureObject_t *pTexObject, const hipResourceDesc *pResDesc, const hipTextureDesc *pTexDesc, const struct hipResourceViewDesc *pResViewDesc)¶

Creates a texture object.

Note

3D liner filter isn’t supported on GFX90A boards, on which the API hipCreateTextureObject will return hipErrorNotSupported.

Parameters:

pTexObject – [out] pointer to the texture object to create
pResDesc – [in] pointer to resource descriptor
pTexDesc – [in] pointer to texture descriptor
pResViewDesc – [in] pointer to resource view descriptor

Returns:

hipSuccess, hipErrorInvalidValue, hipErrorNotSupported, hipErrorOutOfMemory

hipError_t hipDestroyTextureObject(hipTextureObject_t textureObject)¶

Destroys a texture object.

Parameters:

textureObject – [in] texture object to destroy

Returns:

hipSuccess, hipErrorInvalidValue

hipError_t hipGetChannelDesc(hipChannelFormatDesc *desc, hipArray_const_t array)¶

Gets the channel descriptor in an array.

Parameters:

desc – [in] pointer to channel format descriptor
array – [out] memory array on the device

Returns:

hipSuccess, hipErrorInvalidValue

hipError_t hipGetTextureObjectResourceDesc(hipResourceDesc *pResDesc, hipTextureObject_t textureObject)¶

Gets resource descriptor for the texture object.

Parameters:

pResDesc – [out] pointer to resource descriptor
textureObject – [in] texture object

Returns:

hipSuccess, hipErrorInvalidValue

hipError_t hipGetTextureObjectResourceViewDesc(struct hipResourceViewDesc *pResViewDesc, hipTextureObject_t textureObject)¶

Gets resource view descriptor for the texture object.

Parameters:

pResViewDesc – [out] pointer to resource view descriptor
textureObject – [in] texture object

Returns:

hipSuccess, hipErrorInvalidValue

hipError_t hipGetTextureObjectTextureDesc(hipTextureDesc *pTexDesc, hipTextureObject_t textureObject)¶

Gets texture descriptor for the texture object.

Parameters:

pTexDesc – [out] pointer to texture descriptor
textureObject – [in] texture object

Returns:

hipSuccess, hipErrorInvalidValue

hipError_t hipTexObjectCreate(hipTextureObject_t *pTexObject, const HIP_RESOURCE_DESC *pResDesc, const HIP_TEXTURE_DESC *pTexDesc, const HIP_RESOURCE_VIEW_DESC *pResViewDesc)¶

Creates a texture object.

Parameters:

pTexObject – [out] pointer to texture object to create
pResDesc – [in] pointer to resource descriptor
pTexDesc – [in] pointer to texture descriptor
pResViewDesc – [in] pointer to resource view descriptor

Returns:

hipSuccess, hipErrorInvalidValue

hipError_t hipTexObjectDestroy(hipTextureObject_t texObject)¶

Destroys a texture object.

Parameters:

texObject – [in] texture object to destroy

Returns:

hipSuccess, hipErrorInvalidValue

hipError_t hipTexObjectGetResourceDesc(HIP_RESOURCE_DESC *pResDesc, hipTextureObject_t texObject)¶

Gets resource descriptor of a texture object.

Parameters:

pResDesc – [out] pointer to resource descriptor
texObject – [in] texture object

Returns:

hipSuccess, hipErrorNotSupported, hipErrorInvalidValue

hipError_t hipTexObjectGetResourceViewDesc(HIP_RESOURCE_VIEW_DESC *pResViewDesc, hipTextureObject_t texObject)¶

Gets resource view descriptor of a texture object.

Parameters:

pResViewDesc – [out] pointer to resource view descriptor
texObject – [in] texture object

Returns:

hipSuccess, hipErrorNotSupported, hipErrorInvalidValue

hipError_t hipTexObjectGetTextureDesc(HIP_TEXTURE_DESC *pTexDesc, hipTextureObject_t texObject)¶

Gets texture descriptor of a texture object.

Parameters:

pTexDesc – [out] pointer to texture descriptor
texObject – [in] texture object

Returns:

hipSuccess, hipErrorNotSupported, hipErrorInvalidValue

hipError_t hipGetTextureReference(const textureReference **texref, const void *symbol)¶

Gets the texture reference related with the symbol.

Parameters:

texref – [out] texture reference
symbol – [in] pointer to the symbol related with the texture for the reference

Returns:

hipSuccess, hipErrorInvalidValue

hipError_t hipTexRefSetAddressMode(textureReference *texRef, int dim, enum hipTextureAddressMode am)¶

hipError_t hipTexRefSetArray(textureReference *tex, hipArray_const_t array, unsigned int flags)¶

hipError_t hipTexRefSetFilterMode(textureReference *texRef, enum hipTextureFilterMode fm)¶

hipError_t hipTexRefSetFlags(textureReference *texRef, unsigned int Flags)¶

hipError_t hipTexRefSetFormat(textureReference *texRef, hipArray_Format fmt, int NumPackedComponents)¶

hipError_t hipBindTexture (size_t *offset, const textureReference *tex, const void *devPtr, const hipChannelFormatDesc *desc, size_t size __dparm(UINT_MAX))

hipError_t hipBindTexture2D(size_t *offset, const textureReference *tex, const void *devPtr, const hipChannelFormatDesc *desc, size_t width, size_t height, size_t pitch)¶

hipError_t hipBindTextureToArray(const textureReference *tex, hipArray_const_t array, const hipChannelFormatDesc *desc)¶

hipError_t hipGetTextureAlignmentOffset(size_t *offset, const textureReference *texref)¶

hipError_t hipUnbindTexture(const textureReference *tex)¶

hipError_t hipTexRefGetAddress(hipDeviceptr_t *dev_ptr, const textureReference *texRef)¶

hipError_t hipTexRefGetAddressMode(enum hipTextureAddressMode *pam, const textureReference *texRef, int dim)¶

hipError_t hipTexRefGetFilterMode(enum hipTextureFilterMode *pfm, const textureReference *texRef)¶

hipError_t hipTexRefGetFlags(unsigned int *pFlags, const textureReference *texRef)¶

hipError_t hipTexRefGetFormat(hipArray_Format *pFormat, int *pNumChannels, const textureReference *texRef)¶

hipError_t hipTexRefGetMaxAnisotropy(int *pmaxAnsio, const textureReference *texRef)¶

hipError_t hipTexRefGetMipmapFilterMode(enum hipTextureFilterMode *pfm, const textureReference *texRef)¶

hipError_t hipTexRefGetMipmapLevelBias(float *pbias, const textureReference *texRef)¶

hipError_t hipTexRefGetMipmapLevelClamp(float *pminMipmapLevelClamp, float *pmaxMipmapLevelClamp, const textureReference *texRef)¶

hipError_t hipTexRefGetMipMappedArray(hipMipmappedArray_t *pArray, const textureReference *texRef)¶

hipError_t hipTexRefSetAddress(size_t *ByteOffset, textureReference *texRef, hipDeviceptr_t dptr, size_t bytes)¶

hipError_t hipTexRefSetAddress2D(textureReference *texRef, const HIP_ARRAY_DESCRIPTOR *desc, hipDeviceptr_t dptr, size_t Pitch)¶

hipError_t hipTexRefSetMaxAnisotropy(textureReference *texRef, unsigned int maxAniso)¶

hipError_t hipTexRefSetBorderColor(textureReference *texRef, float *pBorderColor)¶

hipError_t hipTexRefSetMipmapFilterMode(textureReference *texRef, enum hipTextureFilterMode fm)¶

hipError_t hipTexRefSetMipmapLevelBias(textureReference *texRef, float bias)¶

hipError_t hipTexRefSetMipmapLevelClamp(textureReference *texRef, float minMipMapLevelClamp, float maxMipMapLevelClamp)¶

hipError_t hipTexRefSetMipmappedArray(textureReference *texRef, struct hipMipmappedArray *mipmappedArray, unsigned int Flags)¶

hipError_t hipMipmappedArrayCreate(hipMipmappedArray_t *pHandle, HIP_ARRAY3D_DESCRIPTOR *pMipmappedArrayDesc, unsigned int numMipmapLevels)¶

hipError_t hipMipmappedArrayDestroy(hipMipmappedArray_t hMipmappedArray)¶

hipError_t hipMipmappedArrayGetLevel(hipArray_t *pLevelArray, hipMipmappedArray_t hMipMappedArray, unsigned int level)¶

const char *hipApiName(uint32_t id)¶

const char *hipKernelNameRef(const hipFunction_t f)¶

const char *hipKernelNameRefByPtr(const void *hostFunction, hipStream_t stream)¶

int hipGetStreamDeviceId(hipStream_t stream)¶

hipError_t hipStreamBeginCapture(hipStream_t stream, hipStreamCaptureMode mode)¶

Begins graph capture on a stream.

Warning

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

Parameters:

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

Returns:

hipError_t hipStreamEndCapture(hipStream_t stream, hipGraph_t *pGraph)¶

Ends capture on a stream, returning the captured graph.

Warning

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

Parameters:

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

Returns:

hipSuccess, hipErrorStreamCaptureImplicit

hipError_t hipStreamGetCaptureInfo(hipStream_t stream, hipStreamCaptureStatus *pCaptureStatus, unsigned long long *pId)¶

Get capture status of a stream.

Warning

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

Parameters:

stream – [in] - Stream under capture.
pCaptureStatus – [out] - returns current status of the capture.
pId – [out] - unique ID of the capture.

Returns:

hipError_t hipStreamGetCaptureInfo_v2 (hipStream_t stream, hipStreamCaptureStatus *captureStatus_out, unsigned long long *id_out __dparm(0), hipGraph_t *graph_out __dparm(0), const hipGraphNode_t **dependencies_out __dparm(0), size_t *numDependencies_out __dparm(0))

Get stream’s capture state.

Warning

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

Parameters:

stream – [in] - Stream under capture.
captureStatus_out – [out] - returns current status of the capture.
id_out – [out] - unique ID of the capture.
graph_out – [in] - returns the graph being captured into.
dependencies_out – [out] - returns pointer to an array of nodes.
numDependencies_out – [out] - returns size of the array returned in dependencies_out.

Returns:

hipSuccess, hipErrorInvalidValue, hipErrorStreamCaptureImplicit

hipError_t hipStreamIsCapturing(hipStream_t stream, hipStreamCaptureStatus *pCaptureStatus)¶

Get stream’s capture state.

Warning

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

Parameters:

stream – [in] - Stream under capture.
pCaptureStatus – [out] - returns current status of the capture.

Returns:

hipSuccess, hipErrorInvalidValue, hipErrorStreamCaptureImplicit

hipError_t hipStreamUpdateCaptureDependencies (hipStream_t stream, hipGraphNode_t *dependencies, size_t numDependencies, unsigned int flags __dparm(0))

Update the set of dependencies in a capturing stream.

Warning

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

Parameters:

stream – [in] - Stream under capture.
dependencies – [in] - pointer to an array of nodes to Add/Replace.
numDependencies – [in] - size of the array in dependencies.

Returns:

hipSuccess, hipErrorInvalidValue, hipErrorIllegalState

hipError_t hipLaunchHostFunc(hipStream_t stream, hipHostFn_t fn, void *userData)¶

Enqueues a host function call in a stream.

Warning

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

Parameters:

stream – [in] - stream to enqueue work to.
fn – [in] - function to call once operations enqueued preceeding are complete.
userData – [in] - User-specified data to be passed to the function.

Returns:

hipSuccess, hipErrorInvalidResourceHandle, hipErrorInvalidValue, hipErrorNotSupported

hipError_t hipThreadExchangeStreamCaptureMode(hipStreamCaptureMode *mode)¶

Swaps the stream capture mode of a thread.

Warning

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

Parameters:

mode – [in] - Pointer to mode value to swap with the current mode

Returns:

hipSuccess, hipErrorInvalidValue, hipErrorMemoryAllocation

hipError_t hipGraphCreate(hipGraph_t *pGraph, unsigned int flags)¶

Creates a graph.

Warning

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

Parameters:

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

Returns:

hipError_t hipGraphDestroy(hipGraph_t graph)¶

Destroys a graph.

Warning

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

Parameters:

graph – [in] - instance of graph to destroy.

Returns:

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

Adds dependency edges to a graph.

Warning

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

Parameters:

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

Returns:

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

Removes dependency edges from a graph.

Warning

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

Parameters:

graph – [in] - instance of the graph to remove dependencies.
from – [in] - Array of nodes that provide the dependencies.
to – [in] - Array of dependent nodes.
numDependencies – [in] - the number of dependencies to remove.

Returns:

hipError_t hipGraphGetEdges(hipGraph_t graph, hipGraphNode_t *from, hipGraphNode_t *to, size_t *numEdges)¶

Returns a graph’s dependency edges.

from and to may both be NULL, in which case this function only returns the number of edges in numEdges. Otherwise, numEdges entries will be filled in. If numEdges is higher than the actual number of edges, the remaining entries in from and to will be set to NULL, and the number of edges actually returned will be written to numEdges

Warning

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

Parameters:

graph – [in] - instance of the graph to get the edges from.
from – [out] - pointer to the graph nodes to return edge endpoints.
to – [out] - pointer to the graph nodes to return edge endpoints.
numEdges – [out] - returns number of edges.

Returns:

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

Returns graph nodes.

nodes may be NULL, in which case this function will return the number of nodes in numNodes. Otherwise, numNodes entries will be filled in. If numNodes is higher than the actual number of nodes, the remaining entries in nodes will be set to NULL, and the number of nodes actually obtained will be returned in numNodes.

Warning

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

Parameters:

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

Returns:

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

Returns graph’s root nodes.

pRootNodes may be NULL, in which case this function will return the number of root nodes in pNumRootNodes. Otherwise, pNumRootNodes entries will be filled in. If pNumRootNodes is higher than the actual number of root nodes, the remaining entries in pRootNodes will be set to NULL, and the number of nodes actually obtained will be returned in pNumRootNodes.

Warning

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

Parameters:

graph – [in] - instance of the graph to get the nodes.
pRootNodes – [out] - pointer to return the graph’s root nodes.
pNumRootNodes – [out] - returns the number of graph’s root nodes.

Returns:

hipError_t hipGraphNodeGetDependencies(hipGraphNode_t node, hipGraphNode_t *pDependencies, size_t *pNumDependencies)¶

Returns a node’s dependencies.

pDependencies may be NULL, in which case this function will return the number of dependencies in pNumDependencies. Otherwise, pNumDependencies entries will be filled in. If pNumDependencies is higher than the actual number of dependencies, the remaining entries in pDependencies will be set to NULL, and the number of nodes actually obtained will be returned in pNumDependencies.

Warning

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

Parameters:

node – [in] - graph node to get the dependencies from.
pDependencies – [out] - pointer to to return the dependencies.
pNumDependencies – [out] - returns the number of graph node dependencies.

Returns:

hipError_t hipGraphNodeGetDependentNodes(hipGraphNode_t node, hipGraphNode_t *pDependentNodes, size_t *pNumDependentNodes)¶

Returns a node’s dependent nodes.

DependentNodes may be NULL, in which case this function will return the number of dependent nodes in pNumDependentNodes. Otherwise, pNumDependentNodes entries will be filled in. If pNumDependentNodes is higher than the actual number of dependent nodes, the remaining entries in pDependentNodes will be set to NULL, and the number of nodes actually obtained will be returned in pNumDependentNodes.

Warning

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

Parameters:

node – [in] - graph node to get the Dependent nodes from.
pDependentNodes – [out] - pointer to return the graph dependent nodes.
pNumDependentNodes – [out] - returns the number of graph node dependent nodes.

Returns:

hipError_t hipGraphNodeGetType(hipGraphNode_t node, hipGraphNodeType *pType)¶

Returns a node’s type.

Warning

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

Parameters:

node – [in] - instance of the graph to add dependencies.
pType – [out] - pointer to the return the type

Returns:

hipError_t hipGraphDestroyNode(hipGraphNode_t node)¶

Remove a node from the graph.

Warning

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

Parameters:

node – [in] - graph node to remove

Returns:

hipSuccess, hipErrorInvalidValue, hipErrorMemoryAllocation

hipError_t hipGraphClone(hipGraph_t *pGraphClone, hipGraph_t originalGraph)¶

Clones a graph.

Warning

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

Parameters:

pGraphClone – [out] - Returns newly created cloned graph.
originalGraph – [in] - original graph to clone from.

Returns:

hipError_t hipGraphNodeFindInClone(hipGraphNode_t *pNode, hipGraphNode_t originalNode, hipGraph_t clonedGraph)¶

Finds a cloned version of a node.

Warning

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

Parameters:

pNode – [out] - Returns the cloned node.
originalNode – [in] - original node handle.
clonedGraph – [in] - Cloned graph to query.

Returns:

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

Creates an executable graph from a graph.

Warning

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

Parameters:

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

Returns:

hipError_t hipGraphInstantiateWithFlags(hipGraphExec_t *pGraphExec, hipGraph_t graph, unsigned long long flags)¶

Creates an executable graph from a graph.

Warning

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

Parameters:

pGraphExec – [out] - pointer to instantiated executable graph that is created.
graph – [in] - instance of graph to instantiate.
flags – [in] - Flags to control instantiation.

Returns:

hipError_t hipGraphLaunch(hipGraphExec_t graphExec, hipStream_t stream)¶

launches an executable graph in a stream

Warning

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

Parameters:

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

Returns:

hipError_t hipGraphUpload(hipGraphExec_t graphExec, hipStream_t stream)¶

uploads an executable graph in a stream

Warning

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

Parameters:

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

Returns:

hipSuccess, hipErrorGraphExecUpdateFailure

hipError_t hipGraphExecDestroy(hipGraphExec_t graphExec)¶

Destroys an executable graph.

Warning

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

Parameters:

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

Returns:

hipSuccess.

hipError_t hipGraphExecUpdate(hipGraphExec_t hGraphExec, hipGraph_t hGraph, hipGraphNode_t *hErrorNode_out, hipGraphExecUpdateResult *updateResult_out)¶

Check whether an executable graph can be updated with a graph and perform the update if * possible.

Warning

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

Parameters:

hGraphExec – [in] - instance of executable graph to update.
hGraph – [in] - graph that contains the updated parameters.
hErrorNode_out – [in] - node which caused the permissibility check to forbid the update.
updateResult_out – [in] - Whether the graph update was permitted.

Returns:

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.

Warning

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

Parameters:

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

Returns:

hipSuccess, hipErrorInvalidValue, hipErrorInvalidDeviceFunction

hipError_t hipGraphKernelNodeGetParams(hipGraphNode_t node, hipKernelNodeParams *pNodeParams)¶

Gets kernel node’s parameters.

Warning

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

Parameters:

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

Returns:

hipError_t hipGraphKernelNodeSetParams(hipGraphNode_t node, const hipKernelNodeParams *pNodeParams)¶

Sets a kernel node’s parameters.

Warning

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

Parameters:

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

Returns:

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

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

Warning

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

Parameters:

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

Returns:

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.

Warning

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

Parameters:

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

Returns:

hipError_t hipGraphMemcpyNodeGetParams(hipGraphNode_t node, hipMemcpy3DParms *pNodeParams)¶

Gets a memcpy node’s parameters.

Warning

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

Parameters:

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

Returns:

hipError_t hipGraphMemcpyNodeSetParams(hipGraphNode_t node, const hipMemcpy3DParms *pNodeParams)¶

Sets a memcpy node’s parameters.

Warning

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

Parameters:

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

Returns:

hipError_t hipGraphKernelNodeSetAttribute(hipGraphNode_t hNode, hipKernelNodeAttrID attr, const hipKernelNodeAttrValue *value)¶

Sets a node attribute.

Warning

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

Parameters:

hNode – [in] - instance of the node to set parameters to.
attr – [in] - the attribute node is set to.
value – [in] - const pointer to the parameters.

Returns:

hipError_t hipGraphKernelNodeGetAttribute(hipGraphNode_t hNode, hipKernelNodeAttrID attr, hipKernelNodeAttrValue *value)¶

Gets a node attribute.

Warning

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

Parameters:

hNode – [in] - instance of the node to set parameters to.
attr – [in] - the attribute node is set to.
value – [in] - const pointer to the parameters.

Returns:

hipError_t hipGraphExecMemcpyNodeSetParams(hipGraphExec_t hGraphExec, hipGraphNode_t node, hipMemcpy3DParms *pNodeParams)¶

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

Warning

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

Parameters:

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

Returns:

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.

Warning

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

Parameters:

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

Returns:

hipError_t hipGraphMemcpyNodeSetParams1D(hipGraphNode_t node, void *dst, const void *src, size_t count, hipMemcpyKind kind)¶

Sets a memcpy node’s parameters to perform a 1-dimensional copy.

Warning

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

Parameters:

node – [in] - instance of the node to set parameters to.
dst – [in] - pointer to memory address to the destination.
src – [in] - pointer to memory address to the source.
count – [in] - the size of the memory to copy.
kind – [in] - the type of memory copy.

Returns:

hipError_t hipGraphExecMemcpyNodeSetParams1D(hipGraphExec_t hGraphExec, hipGraphNode_t node, void *dst, const void *src, size_t count, hipMemcpyKind kind)¶

Sets the parameters for a memcpy node in the given graphExec to perform a 1-dimensional copy.

Warning

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

Parameters:

hGraphExec – [in] - instance of the executable graph with the node.
node – [in] - instance of the node to set parameters to.
dst – [in] - pointer to memory address to the destination.
src – [in] - pointer to memory address to the source.
count – [in] - the size of the memory to copy.
kind – [in] - the type of memory copy.

Returns:

hipError_t hipGraphAddMemcpyNodeFromSymbol(hipGraphNode_t *pGraphNode, hipGraph_t graph, const hipGraphNode_t *pDependencies, size_t numDependencies, void *dst, const void *symbol, size_t count, size_t offset, hipMemcpyKind kind)¶

Creates a memcpy node to copy from a symbol on the device and adds it to a graph.

Warning

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

Parameters:

pGraphNode – [out] - pointer to graph node to create.
graph – [in] - instance of graph to add the created node.
pDependencies – [in] - const pointer to the dependencies on the memcpy execution node.
numDependencies – [in] - the number of the dependencies.
dst – [in] - pointer to memory address to the destination.
symbol – [in] - Device symbol address.
count – [in] - the size of the memory to copy.
offset – [in] - Offset from start of symbol in bytes.
kind – [in] - the type of memory copy.

Returns:

hipError_t hipGraphMemcpyNodeSetParamsFromSymbol(hipGraphNode_t node, void *dst, const void *symbol, size_t count, size_t offset, hipMemcpyKind kind)¶

Sets a memcpy node’s parameters to copy from a symbol on the device.

Warning

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

Parameters:

node – [in] - instance of the node to set parameters to.
dst – [in] - pointer to memory address to the destination.
symbol – [in] - Device symbol address.
count – [in] - the size of the memory to copy.
offset – [in] - Offset from start of symbol in bytes.
kind – [in] - the type of memory copy.

Returns:

hipError_t hipGraphExecMemcpyNodeSetParamsFromSymbol(hipGraphExec_t hGraphExec, hipGraphNode_t node, void *dst, const void *symbol, size_t count, size_t offset, hipMemcpyKind kind)¶

Sets the parameters for a memcpy node in the given graphExec to copy from a symbol on the.

device.

Warning

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

Parameters:

hGraphExec – [in] - instance of the executable graph with the node.
node – [in] - instance of the node to set parameters to.
dst – [in] - pointer to memory address to the destination.
symbol – [in] - Device symbol address.
count – [in] - the size of the memory to copy.
offset – [in] - Offset from start of symbol in bytes.
kind – [in] - the type of memory copy.

Returns:

hipError_t hipGraphAddMemcpyNodeToSymbol(hipGraphNode_t *pGraphNode, hipGraph_t graph, const hipGraphNode_t *pDependencies, size_t numDependencies, const void *symbol, const void *src, size_t count, size_t offset, hipMemcpyKind kind)¶

Creates a memcpy node to copy to a symbol on the device and adds it to a graph.

Warning

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

Parameters:

pGraphNode – [out] - pointer to graph node to create.
graph – [in] - instance of graph to add the created node.
pDependencies – [in] - const pointer to the dependencies on the memcpy execution node.
numDependencies – [in] - the number of the dependencies.
symbol – [in] - Device symbol address.
src – [in] - pointer to memory address of the src.
count – [in] - the size of the memory to copy.
offset – [in] - Offset from start of symbol in bytes.
kind – [in] - the type of memory copy.

Returns:

hipError_t hipGraphMemcpyNodeSetParamsToSymbol(hipGraphNode_t node, const void *symbol, const void *src, size_t count, size_t offset, hipMemcpyKind kind)¶

Sets a memcpy node’s parameters to copy to a symbol on the device.

Warning

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

Parameters:

node – [in] - instance of the node to set parameters to.
symbol – [in] - Device symbol address.
src – [in] - pointer to memory address of the src.
count – [in] - the size of the memory to copy.
offset – [in] - Offset from start of symbol in bytes.
kind – [in] - the type of memory copy.

Returns:

hipError_t hipGraphExecMemcpyNodeSetParamsToSymbol(hipGraphExec_t hGraphExec, hipGraphNode_t node, const void *symbol, const void *src, size_t count, size_t offset, hipMemcpyKind kind)¶

Sets the parameters for a memcpy node in the given graphExec to copy to a symbol on the device.

Warning

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

Parameters:

hGraphExec – [in] - instance of the executable graph with the node.
node – [in] - instance of the node to set parameters to.
symbol – [in] - Device symbol address.
src – [in] - pointer to memory address of the src.
count – [in] - the size of the memory to copy.
offset – [in] - Offset from start of symbol in bytes.
kind – [in] - the type of memory copy.

Returns:

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.

Warning

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

Parameters:

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

Returns:

hipError_t hipGraphMemsetNodeGetParams(hipGraphNode_t node, hipMemsetParams *pNodeParams)¶

Gets a memset node’s parameters.

Warning

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

Parameters:

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

Returns:

hipError_t hipGraphMemsetNodeSetParams(hipGraphNode_t node, const hipMemsetParams *pNodeParams)¶

Sets a memset node’s parameters.

Warning

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

Parameters:

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

Returns:

hipError_t hipGraphExecMemsetNodeSetParams(hipGraphExec_t hGraphExec, hipGraphNode_t node, const hipMemsetParams *pNodeParams)¶

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

Warning

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

Parameters:

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

Returns:

hipError_t hipGraphAddHostNode(hipGraphNode_t *pGraphNode, hipGraph_t graph, const hipGraphNode_t *pDependencies, size_t numDependencies, const hipHostNodeParams *pNodeParams)¶

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

Warning

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

Parameters:

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

Returns:

hipError_t hipGraphHostNodeGetParams(hipGraphNode_t node, hipHostNodeParams *pNodeParams)¶

Returns a host node’s parameters.

Warning

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

Parameters:

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

Returns:

hipError_t hipGraphHostNodeSetParams(hipGraphNode_t node, const hipHostNodeParams *pNodeParams)¶

Sets a host node’s parameters.

Warning

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

Parameters:

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

Returns:

hipError_t hipGraphExecHostNodeSetParams(hipGraphExec_t hGraphExec, hipGraphNode_t node, const hipHostNodeParams *pNodeParams)¶

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

Warning

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

Parameters:

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

Returns:

hipError_t hipGraphAddChildGraphNode(hipGraphNode_t *pGraphNode, hipGraph_t graph, const hipGraphNode_t *pDependencies, size_t numDependencies, hipGraph_t childGraph)¶

Creates a child graph node and adds it to a graph.

Warning

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

Parameters:

pGraphNode – [out] - pointer to the graph node to create.
graph – [in] - instance of the graph to add the created node.
pDependencies – [in] - const pointer to the dependencies on the memset execution node.
numDependencies – [in] - the number of the dependencies.
childGraph – [in] - the graph to clone into this node

Returns:

hipError_t hipGraphChildGraphNodeGetGraph(hipGraphNode_t node, hipGraph_t *pGraph)¶

Gets a handle to the embedded graph of a child graph node.

Warning

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

Parameters:

node – [in] - instane of the node to get child graph.
pGraph – [out] - pointer to get the graph.

Returns:

hipError_t hipGraphExecChildGraphNodeSetParams(hipGraphExec_t hGraphExec, hipGraphNode_t node, hipGraph_t childGraph)¶

Updates node parameters in the child graph node in the given graphExec.

Warning

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

Parameters:

hGraphExec – [in] - instance of the executable graph with the node.
node – [in] - node from the graph which was used to instantiate graphExec.
childGraph – [in] - child graph with updated parameters.

Returns:

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.

Warning

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

Parameters:

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

Returns:

hipError_t hipGraphAddEventRecordNode(hipGraphNode_t *pGraphNode, hipGraph_t graph, const hipGraphNode_t *pDependencies, size_t numDependencies, hipEvent_t event)¶

Creates an event record node and adds it to a graph.

Warning

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

Parameters:

pGraphNode – [out] - pointer to the graph node to create and add to the graph.
graph – [in] - instane of the graph the node to be added.
pDependencies – [in] - const pointer to the node dependenties.
numDependencies – [in] - the number of dependencies.
event – [in] - Event for the node.

Returns:

hipError_t hipGraphEventRecordNodeGetEvent(hipGraphNode_t node, hipEvent_t *event_out)¶

Returns the event associated with an event record node.

Warning

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

Parameters:

node – [in] - instane of the node to get event from.
event_out – [out] - Pointer to return the event.

Returns:

hipError_t hipGraphEventRecordNodeSetEvent(hipGraphNode_t node, hipEvent_t event)¶

Sets an event record node’s event.

Warning

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

Parameters:

node – [in] - instane of the node to set event to.
event – [in] - pointer to the event.

Returns:

hipError_t hipGraphExecEventRecordNodeSetEvent(hipGraphExec_t hGraphExec, hipGraphNode_t hNode, hipEvent_t event)¶

Sets the event for an event record node in the given graphExec.

Warning

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

Parameters:

hGraphExec – [in] - instance of the executable graph with the node.
hNode – [in] - node from the graph which was used to instantiate graphExec.
event – [in] - pointer to the event.

Returns:

hipError_t hipGraphAddEventWaitNode(hipGraphNode_t *pGraphNode, hipGraph_t graph, const hipGraphNode_t *pDependencies, size_t numDependencies, hipEvent_t event)¶

Creates an event wait node and adds it to a graph.

Warning

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

Parameters:

pGraphNode – [out] - pointer to the graph node to create and add to the graph.
graph – [in] - instane of the graph the node to be added.
pDependencies – [in] - const pointer to the node dependenties.
numDependencies – [in] - the number of dependencies.
event – [in] - Event for the node.

Returns:

hipError_t hipGraphEventWaitNodeGetEvent(hipGraphNode_t node, hipEvent_t *event_out)¶

Returns the event associated with an event wait node.

Warning

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

Parameters:

node – [in] - instane of the node to get event from.
event_out – [out] - Pointer to return the event.

Returns:

hipError_t hipGraphEventWaitNodeSetEvent(hipGraphNode_t node, hipEvent_t event)¶

Sets an event wait node’s event.

Warning

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

Parameters:

node – [in] - instane of the node to set event to.
event – [in] - pointer to the event.

Returns:

hipError_t hipGraphExecEventWaitNodeSetEvent(hipGraphExec_t hGraphExec, hipGraphNode_t hNode, hipEvent_t event)¶

Sets the event for an event record node in the given graphExec.

Warning

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

Parameters:

hGraphExec – [in] - instance of the executable graph with the node.
hNode – [in] - node from the graph which was used to instantiate graphExec.
event – [in] - pointer to the event.

Returns:

hipError_t hipDeviceGetGraphMemAttribute(int device, hipGraphMemAttributeType attr, void *value)¶

Get the mem attribute for graphs.

Warning

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

Parameters:

device – [in] - device the attr is get for.
attr – [in] - attr to get.
value – [out] - value for specific attr.

Returns:

hipError_t hipDeviceSetGraphMemAttribute(int device, hipGraphMemAttributeType attr, void *value)¶

Set the mem attribute for graphs.

Warning

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

Parameters:

device – [in] - device the attr is set for.
attr – [in] - attr to set.
value – [in] - value for specific attr.

Returns:

hipError_t hipDeviceGraphMemTrim(int device)¶

Free unused memory on specific device used for graph back to OS.

Warning

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

Parameters:

device – [in] - device the memory is used for graphs

hipError_t hipUserObjectCreate(hipUserObject_t *object_out, void *ptr, hipHostFn_t destroy, unsigned int initialRefcount, unsigned int flags)¶

Create an instance of userObject to manage lifetime of a resource.

Warning

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

Parameters:

object_out – [out] - pointer to instace of userobj.
ptr – [in] - pointer to pass to destroy function.
destroy – [in] - destroy callback to remove resource.
initialRefcount – [in] - reference to resource.
flags – [in] - flags passed to API.

Returns:

hipError_t hipUserObjectRelease (hipUserObject_t object, unsigned int count __dparm(1))

Release number of references to resource.

Warning

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

Parameters:

object – [in] - pointer to instace of userobj.
count – [in] - reference to resource to be retained.

Returns:

hipError_t hipUserObjectRetain (hipUserObject_t object, unsigned int count __dparm(1))

Retain number of references to resource.

Warning

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

Parameters:

object – [in] - pointer to instace of userobj.
count – [in] - reference to resource to be retained.

Returns:

hipError_t hipGraphRetainUserObject (hipGraph_t graph, hipUserObject_t object, unsigned int count __dparm(1), unsigned int flags __dparm(0))

Retain user object for graphs.

Warning

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

Parameters:

graph – [in] - pointer to graph to retain the user object for.
object – [in] - pointer to instace of userobj.
count – [in] - reference to resource to be retained.
flags – [in] - flags passed to API.

Returns:

hipError_t hipGraphReleaseUserObject (hipGraph_t graph, hipUserObject_t object, unsigned int count __dparm(1))

Release user object from graphs.

Warning

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

Parameters:

graph – [in] - pointer to graph to retain the user object for.
object – [in] - pointer to instace of userobj.
count – [in] - reference to resource to be retained.

Returns: