Memory Management#

HIP Runtime API Reference: Memory Management
Memory Management
Collaboration diagram for Memory Management:

Modules

 External Resource Interoperability
 
 Managed Memory
 
 Stream Ordered Memory Allocator
 

Functions

hipError_t hipPointerSetAttribute (const void *value, hipPointer_attribute attribute, hipDeviceptr_t ptr)
 Sets information on the specified pointer.[BETA]. More...
 
hipError_t hipPointerGetAttributes (hipPointerAttribute_t *attributes, const void *ptr)
 Return attributes for the specified pointer. More...
 
hipError_t hipPointerGetAttribute (void *data, hipPointer_attribute attribute, hipDeviceptr_t ptr)
 Returns information about the specified pointer.[BETA]. More...
 
hipError_t hipDrvPointerGetAttributes (unsigned int numAttributes, hipPointer_attribute *attributes, void **data, hipDeviceptr_t ptr)
 Returns information about the specified pointer.[BETA]. More...
 
hipError_t hipMalloc (void **ptr, size_t size)
 Allocate memory on the default accelerator. More...
 
hipError_t hipExtMallocWithFlags (void **ptr, size_t sizeBytes, unsigned int flags)
 Allocate memory on the default accelerator. More...
 
hipError_t hipMallocHost (void **ptr, size_t size)
 Allocate pinned host memory [Deprecated]. More...
 
hipError_t hipMemAllocHost (void **ptr, size_t size)
 Allocate pinned host memory [Deprecated]. More...
 
hipError_t hipHostMalloc (void **ptr, size_t size, unsigned int flags)
 Allocates device accessible page locked (pinned) host memory. More...
 
hipError_t hipHostAlloc (void **ptr, size_t size, unsigned int flags)
 Allocate device accessible page locked host memory [Deprecated]. More...
 
hipError_t hipHostGetDevicePointer (void **devPtr, void *hstPtr, unsigned int flags)
 Get Device pointer from Host Pointer allocated through hipHostMalloc. More...
 
hipError_t hipHostGetFlags (unsigned int *flagsPtr, void *hostPtr)
 Return flags associated with host pointer. More...
 
hipError_t hipHostRegister (void *hostPtr, size_t sizeBytes, unsigned int flags)
 Register host memory so it can be accessed from the current device. More...
 
hipError_t hipHostUnregister (void *hostPtr)
 Un-register host pointer. More...
 
hipError_t hipMallocPitch (void **ptr, size_t *pitch, size_t width, size_t height)
 
hipError_t hipMemAllocPitch (hipDeviceptr_t *dptr, size_t *pitch, size_t widthInBytes, size_t height, unsigned int elementSizeBytes)
 
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. More...
 
hipError_t hipFreeHost (void *ptr)
 Free memory allocated by the hcc hip host memory allocation API [Deprecated]. More...
 
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. More...
 
hipError_t hipMemcpy (void *dst, const void *src, size_t sizeBytes, hipMemcpyKind kind)
 Copy data from src to dst. More...
 
hipError_t hipMemcpyWithStream (void *dst, const void *src, size_t sizeBytes, hipMemcpyKind kind, hipStream_t stream)
 Memory copy on the stream. It allows single or multiple devices to do memory copy on single or multiple streams. More...
 
hipError_t hipMemcpyHtoD (hipDeviceptr_t dst, void *src, size_t sizeBytes)
 Copy data from Host to Device. More...
 
hipError_t hipMemcpyDtoH (void *dst, hipDeviceptr_t src, size_t sizeBytes)
 Copy data from Device to Host. More...
 
hipError_t hipMemcpyDtoD (hipDeviceptr_t dst, hipDeviceptr_t src, size_t sizeBytes)
 Copy data from Device to Device. More...
 
hipError_t hipMemcpyHtoDAsync (hipDeviceptr_t dst, void *src, size_t sizeBytes, hipStream_t stream)
 Copy data from Host to Device asynchronously. More...
 
hipError_t hipMemcpyDtoHAsync (void *dst, hipDeviceptr_t src, size_t sizeBytes, hipStream_t stream)
 Copy data from Device to Host asynchronously. More...
 
hipError_t hipMemcpyDtoDAsync (hipDeviceptr_t dst, hipDeviceptr_t src, size_t sizeBytes, hipStream_t stream)
 Copy data from Device to Device asynchronously. More...
 
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. More...
 
hipError_t hipGetSymbolAddress (void **devPtr, const void *symbol)
 Gets device pointer associated with symbol on the device. More...
 
hipError_t hipGetSymbolSize (size_t *size, const void *symbol)
 Gets the size of the given symbol on the device. More...
 
hipError_t hipGetProcAddress (const char *symbol, void **pfn, int hipVersion, uint64_t flags, hipDriverProcAddressQueryResult *symbolStatus)
 Gets the symbol's function address. More...
 
hipError_t hipMemcpyToSymbol (const void *symbol, const void *src, size_t sizeBytes, size_t offset, hipMemcpyKind kind)
 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. More...
 
hipError_t hipMemcpyToSymbolAsync (const void *symbol, const void *src, size_t sizeBytes, size_t offset, hipMemcpyKind kind, hipStream_t stream)
 Copies data to the given symbol on the device asynchronously. More...
 
hipError_t hipMemcpyFromSymbol (void *dst, const void *symbol, size_t sizeBytes, size_t offset, hipMemcpyKind kind)
 Copies data from the given symbol on the device. More...
 
hipError_t hipMemcpyFromSymbolAsync (void *dst, const void *symbol, size_t sizeBytes, size_t offset, hipMemcpyKind kind, hipStream_t stream)
 Copies data from the given symbol on the device asynchronously. More...
 
hipError_t hipMemcpyAsync (void *dst, const void *src, size_t sizeBytes, hipMemcpyKind kind, hipStream_t stream)
 Copy data from src to dst asynchronously. More...
 
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. More...
 
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. More...
 
hipError_t hipMemsetD8Async (hipDeviceptr_t dest, unsigned char value, size_t count, hipStream_t stream)
 Fills the first sizeBytes bytes of the memory area pointed to by dest with the constant byte value value. More...
 
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. More...
 
hipError_t hipMemsetD16Async (hipDeviceptr_t dest, unsigned short value, size_t count, hipStream_t stream)
 Fills the first sizeBytes bytes of the memory area pointed to by dest with the constant short value value. More...
 
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. More...
 
hipError_t hipMemsetAsync (void *dst, int value, size_t sizeBytes, hipStream_t stream)
 Fills the first sizeBytes bytes of the memory area pointed to by dev with the constant byte value value. More...
 
hipError_t hipMemsetD32Async (hipDeviceptr_t dst, int value, size_t count, hipStream_t stream)
 Fills the memory area pointed to by dev with the constant integer value for specified number of times. More...
 
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. More...
 
hipError_t hipMemset2DAsync (void *dst, size_t pitch, int value, size_t width, size_t height, hipStream_t stream)
 Fills asynchronously the memory area pointed to by dst with the constant value. More...
 
hipError_t hipMemset3D (hipPitchedPtr pitchedDevPtr, int value, hipExtent extent)
 Fills synchronously the memory area pointed to by pitchedDevPtr with the constant value. More...
 
hipError_t hipMemset3DAsync (hipPitchedPtr pitchedDevPtr, int value, hipExtent extent, hipStream_t stream)
 Fills asynchronously the memory area pointed to by pitchedDevPtr with the constant value. More...
 
hipError_t hipMemGetInfo (size_t *free, size_t *total)
 Query memory info. More...
 
hipError_t hipMemPtrGetInfo (void *ptr, size_t *size)
 Get allocated memory size via memory pointer. More...
 
hipError_t hipMallocArray (hipArray_t *array, const hipChannelFormatDesc *desc, size_t width, size_t height, unsigned int flags)
 Allocate an array on the device. More...
 
hipError_t hipArrayCreate (hipArray_t *pHandle, const HIP_ARRAY_DESCRIPTOR *pAllocateArray)
 Create an array memory pointer on the device. More...
 
hipError_t hipArrayDestroy (hipArray_t array)
 Destroy an array memory pointer on the device. More...
 
hipError_t hipArray3DCreate (hipArray_t *array, const HIP_ARRAY3D_DESCRIPTOR *pAllocateArray)
 Create a 3D array memory pointer on the device. More...
 
hipError_t hipMalloc3D (hipPitchedPtr *pitchedDevPtr, hipExtent extent)
 Create a 3D memory pointer on the device. More...
 
hipError_t hipFreeArray (hipArray_t array)
 Frees an array on the device. More...
 
hipError_t hipMalloc3DArray (hipArray_t *array, const struct hipChannelFormatDesc *desc, struct hipExtent extent, unsigned int flags)
 Allocate an array on the device. More...
 
hipError_t hipArrayGetInfo (hipChannelFormatDesc *desc, hipExtent *extent, unsigned int *flags, hipArray_t array)
 Gets info about the specified array. More...
 
hipError_t hipArrayGetDescriptor (HIP_ARRAY_DESCRIPTOR *pArrayDescriptor, hipArray_t array)
 Gets a 1D or 2D array descriptor. More...
 
hipError_t hipArray3DGetDescriptor (HIP_ARRAY3D_DESCRIPTOR *pArrayDescriptor, hipArray_t array)
 Gets a 3D array descriptor. More...
 
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. More...
 
hipError_t hipMemcpyParam2D (const hip_Memcpy2D *pCopy)
 Copies memory for 2D arrays. More...
 
hipError_t hipMemcpyParam2DAsync (const hip_Memcpy2D *pCopy, hipStream_t stream)
 Copies memory for 2D arrays. More...
 
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)
 Copies data between host and device. More...
 
hipError_t hipMemcpy2DToArray (hipArray_t 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. More...
 
hipError_t hipMemcpy2DToArrayAsync (hipArray_t dst, size_t wOffset, size_t hOffset, const void *src, size_t spitch, size_t width, size_t height, hipMemcpyKind kind, hipStream_t stream)
 Copies data between host and device. More...
 
hipError_t hipMemcpyToArray (hipArray_t dst, size_t wOffset, size_t hOffset, const void *src, size_t count, hipMemcpyKind kind)
 Copies data between host and device. More...
 
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. More...
 
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. More...
 
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)
 Copies data between host and device asynchronously. More...
 
hipError_t hipMemcpyAtoH (void *dst, hipArray_t srcArray, size_t srcOffset, size_t count)
 Copies data between host and device. More...
 
hipError_t hipMemcpyHtoA (hipArray_t dstArray, size_t dstOffset, const void *srcHost, size_t count)
 Copies data between host and device. More...
 
hipError_t hipMemcpy3D (const struct hipMemcpy3DParms *p)
 Copies data between host and device. More...
 
hipError_t hipMemcpy3DAsync (const struct hipMemcpy3DParms *p, hipStream_t stream)
 Copies data between host and device asynchronously. More...
 
hipError_t hipDrvMemcpy3D (const HIP_MEMCPY3D *pCopy)
 Copies data between host and device. More...
 
hipError_t hipDrvMemcpy3DAsync (const HIP_MEMCPY3D *pCopy, hipStream_t stream)
 Copies data between host and device asynchronously. More...
 

Detailed Description



This section describes the memory management functions of HIP runtime API. The following CUDA APIs are not currently supported:

  • cudaMalloc3D
  • cudaMalloc3DArray
  • TODO - more 2D, 3D, array APIs here.

Function Documentation

◆ hipArray3DCreate()

hipError_t hipArray3DCreate ( hipArray_t array,
const HIP_ARRAY3D_DESCRIPTOR pAllocateArray 
)

Create a 3D array memory pointer on the device.

Parameters
[out]arrayPointer to the 3D array memory
[in]pAllocateArrayRequested array desciptor
Returns
hipSuccess, hipErrorInvalidValue, hipErrorNotSupported
See also
hipMallocArray, hipArrayDestroy, hipFreeArray

◆ hipArray3DGetDescriptor()

hipError_t hipArray3DGetDescriptor ( HIP_ARRAY3D_DESCRIPTOR pArrayDescriptor,
hipArray_t  array 
)

Gets a 3D array descriptor.

Parameters
[out]pArrayDescriptor- Returned 3D array descriptor
[in]array- 3D array to get descriptor of
Returns
hipSuccess, hipErrorDeinitialized, hipErrorNotInitialized, hipErrorInvalidContext, hipErrorInvalidValue hipErrorInvalidHandle, hipErrorContextIsDestroyed
See also
hipArray3DCreate, hipArrayCreate, hipArrayDestroy, hipArrayGetDescriptor, hipMemAlloc, hipMemAllocHost, hipMemAllocPitch, hipMemcpy2D, hipMemcpy2DAsync, hipMemcpy2DUnaligned, hipMemcpy3D, hipMemcpy3DAsync, hipMemcpyAtoA, hipMemcpyAtoD, hipMemcpyAtoH, hipMemcpyAtoHAsync, hipMemcpyDtoA, hipMemcpyDtoD, hipMemcpyDtoDAsync, hipMemcpyDtoH, hipMemcpyDtoHAsync, hipMemcpyHtoA, hipMemcpyHtoAAsync, hipMemcpyHtoD, hipMemcpyHtoDAsync, hipMemFree, hipMemFreeHost, hipMemGetAddressRange, hipMemGetInfo, hipMemHostAlloc, hipMemHostGetDevicePointer, hipMemsetD8, hipMemsetD16, hipMemsetD32, hipArrayGetInfo

◆ hipArrayCreate()

hipError_t hipArrayCreate ( hipArray_t pHandle,
const HIP_ARRAY_DESCRIPTOR pAllocateArray 
)

Create an array memory pointer on the device.

Parameters
[out]pHandlePointer to the array memory
[in]pAllocateArrayRequested array desciptor
Returns
hipSuccess, hipErrorInvalidValue, hipErrorNotSupported
See also
hipMallocArray, hipArrayDestroy, hipFreeArray

◆ hipArrayDestroy()

hipError_t hipArrayDestroy ( hipArray_t  array)

Destroy an array memory pointer on the device.

Parameters
[in]arrayPointer to the array memory
Returns
hipSuccess, hipErrorInvalidValue
See also
hipArrayCreate, hipArrayDestroy, hipFreeArray

◆ hipArrayGetDescriptor()

hipError_t hipArrayGetDescriptor ( HIP_ARRAY_DESCRIPTOR pArrayDescriptor,
hipArray_t  array 
)

Gets a 1D or 2D array descriptor.

Parameters
[out]pArrayDescriptor- Returned array descriptor
[in]array- Array to get descriptor of
Returns
hipSuccess, hipErrorDeinitialized, hipErrorNotInitialized, hipErrorInvalidContext, hipErrorInvalidValue hipErrorInvalidHandle
See also
hipArray3DCreate, hipArray3DGetDescriptor, hipArrayCreate, hipArrayDestroy, hipMemAlloc, hipMemAllocHost, hipMemAllocPitch, hipMemcpy2D, hipMemcpy2DAsync, hipMemcpy2DUnaligned, hipMemcpy3D, hipMemcpy3DAsync, hipMemcpyAtoA, hipMemcpyAtoD, hipMemcpyAtoH, hipMemcpyAtoHAsync, hipMemcpyDtoA, hipMemcpyDtoD, hipMemcpyDtoDAsync, hipMemcpyDtoH, hipMemcpyDtoHAsync, hipMemcpyHtoA, hipMemcpyHtoAAsync, hipMemcpyHtoD, hipMemcpyHtoDAsync, hipMemFree, hipMemFreeHost, hipMemGetAddressRange, hipMemGetInfo, hipMemHostAlloc, hipMemHostGetDevicePointer, hipMemsetD8, hipMemsetD16, hipMemsetD32, hipArrayGetInfo

◆ hipArrayGetInfo()

hipError_t hipArrayGetInfo ( hipChannelFormatDesc desc,
hipExtent extent,
unsigned int *  flags,
hipArray_t  array 
)

Gets info about the specified array.

Parameters
[out]desc- Returned array type
[out]extent- Returned array shape. 2D arrays will have depth of zero
[out]flags- Returned array flags
[in]array- The HIP array to get info for
Returns
hipSuccess, hipErrorInvalidValue hipErrorInvalidHandle
See also
hipArrayGetDescriptor, hipArray3DGetDescriptor

◆ hipDrvMemcpy3D()

hipError_t hipDrvMemcpy3D ( const HIP_MEMCPY3D pCopy)

◆ hipDrvMemcpy3DAsync()

hipError_t hipDrvMemcpy3DAsync ( const HIP_MEMCPY3D pCopy,
hipStream_t  stream 
)

Copies data between host and device asynchronously.

Parameters
[in]pCopy3D memory copy parameters
[in]streamStream to use
Returns
hipSuccess, hipErrorInvalidValue, hipErrorInvalidPitchValue, hipErrorInvalidDevicePointer, hipErrorInvalidMemcpyDirection
See also
hipMemcpy, hipMemcpy2DToArray, hipMemcpy2D, hipMemcpyFromArray, hipMemcpyToSymbol, hipMemcpyAsync

◆ hipDrvPointerGetAttributes()

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

Returns information about the specified pointer.[BETA].

Parameters
[in]numAttributesnumber of attributes to query for
[in]attributesattributes to query for
[in,out]dataa two-dimensional containing pointers to memory locations where the result of each attribute query will be written to
[in]ptrpointer to get attributes for
Returns
hipSuccess, hipErrorInvalidDevice, hipErrorInvalidValue
Warning
This API is marked as beta, meaning, while this is feature complete, it is still open to changes and may have outstanding issues.
See also
hipPointerGetAttribute

◆ hipExtMallocWithFlags()

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

Allocate memory on the default accelerator.

Parameters
[out]ptrPointer to the allocated memory
[in]sizeBytesRequested memory size
[in]flagsType of memory allocation

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

The memory allocation flag should be either hipDeviceMallocDefault, hipDeviceMallocFinegrained, hipDeviceMallocUncached, or hipMallocSignalMemory. If the flag is any other value, the API returns hipErrorInvalidValue.

Returns
hipSuccess, hipErrorOutOfMemory, hipErrorInvalidValue (bad context, null *ptr)
See also
hipMallocPitch, hipFree, hipMallocArray, hipFreeArray, hipMalloc3D, hipMalloc3DArray, hipHostFree, hipHostMalloc

◆ hipFree()

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
[in]ptrPointer to memory to be freed
Returns
hipSuccess
hipErrorInvalidDevicePointer (if pointer is invalid, including host pointers allocated with hipHostMalloc)
See also
hipMalloc, hipMallocPitch, hipMallocArray, hipFreeArray, hipHostFree, hipMalloc3D, hipMalloc3DArray, hipHostMalloc

◆ hipFreeArray()

hipError_t hipFreeArray ( hipArray_t  array)

Frees an array on the device.

Parameters
[in]arrayPointer to array to free
Returns
hipSuccess, hipErrorInvalidValue, hipErrorNotInitialized
See also
hipMalloc, hipMallocPitch, hipFree, hipMallocArray, hipHostMalloc, hipHostFree

◆ hipFreeHost()

hipError_t hipFreeHost ( void *  ptr)

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

Parameters
[in]ptrPointer to memory to be freed
Returns
hipSuccess, hipErrorInvalidValue (if pointer is invalid, including device pointers allocated with hipMalloc)
Warning
This API is deprecated, use hipHostFree() instead

◆ hipGetProcAddress()

hipError_t hipGetProcAddress ( const char *  symbol,
void **  pfn,
int  hipVersion,
uint64_t  flags,
hipDriverProcAddressQueryResult symbolStatus 
)

Gets the symbol's function address.

Parameters
[in]symbolsymbol name in char*
[out]pfnoutput pointer to symbol
[in]hipVersionversion of the function requested. Rocm 6.0.1 = 601
[in]flagscurrently there is no flags other than default
[out]symbolStatusoptional enum returned to indicate what part failed
Returns
hipSuccess, hipErrorInvalidValue

◆ hipGetSymbolAddress()

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

Gets device pointer associated with symbol on the device.

Parameters
[out]devPtrpointer to the device associated the symbole
[in]symbolpointer to the symbole of the device
Returns
hipSuccess, hipErrorInvalidValue

◆ hipGetSymbolSize()

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

Gets the size of the given symbol on the device.

Parameters
[in]symbolpointer to the device symbole
[out]sizepointer to the size
Returns
hipSuccess, hipErrorInvalidValue

◆ hipHostAlloc()

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

Allocate device accessible page locked host memory [Deprecated].

Parameters
[out]ptrPointer to the allocated host pinned memory
[in]sizeRequested memory size in bytes
[in]flagsType of host memory allocation

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

Returns
hipSuccess, hipErrorOutOfMemory
Warning
This API is deprecated, use hipHostMalloc() instead

◆ hipHostFree()

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
[in]ptrPointer to memory to be freed
Returns
hipSuccess, hipErrorInvalidValue (if pointer is invalid, including device pointers allocated with hipMalloc)
See also
hipMalloc, hipMallocPitch, hipFree, hipMallocArray, hipFreeArray, hipMalloc3D, hipMalloc3DArray, hipHostMalloc

◆ hipHostGetDevicePointer()

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

Get Device pointer from Host Pointer allocated through hipHostMalloc.

Parameters
[out]devPtrDevice Pointer mapped to passed host pointer
[in]hstPtrHost Pointer allocated through hipHostMalloc
[in]flagsFlags to be passed for extension
Returns
hipSuccess, hipErrorInvalidValue, hipErrorOutOfMemory
See also
hipSetDeviceFlags, hipHostMalloc

◆ hipHostGetFlags()

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

Return flags associated with host pointer.

Parameters
[out]flagsPtrMemory location to store flags
[in]hostPtrHost Pointer allocated through hipHostMalloc
Returns
hipSuccess, hipErrorInvalidValue
See also
hipHostMalloc

◆ hipHostMalloc()

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

Allocates device accessible page locked (pinned) host memory.

This API allocates pinned host memory which is mapped into the address space of all GPUs in the system, the memory can be accessed directly by the GPU device, and can be read or written with much higher bandwidth than pageable memory obtained with functions such as malloc().

Using the pinned host memory, applications can implement faster data transfers for HostToDevice and DeviceToHost. The runtime tracks the hipHostMalloc allocations and can avoid some of the setup required for regular unpinned memory.

When the memory accesses are infrequent, zero-copy memory can be a good choice, for coherent allocation. GPU can directly access the host memory over the CPU/GPU interconnect, without need to copy the data.

Currently the allocation granularity is 4KB for the API.

Developers need to choose proper allocation flag with consideration of synchronization.

Parameters
[out]ptrPointer to the allocated host pinned memory
[in]sizeRequested memory size in bytes If size is 0, no memory is allocated, *ptr returns nullptr, and hipSuccess is returned.
[in]flagsType of host memory allocation

If no input for flags, it will be the default pinned memory allocation on the host.

Returns
hipSuccess, hipErrorOutOfMemory
See also
hipSetDeviceFlags, hipHostFree

◆ hipHostRegister()

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

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

Parameters
[out]hostPtrPointer to host memory to be registered.
[in]sizeBytesSize of the host memory
[in]flagsSee below.

Flags:

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.

Returns
hipSuccess, hipErrorOutOfMemory
See also
hipHostUnregister, hipHostGetFlags, hipHostGetDevicePointer

◆ hipHostUnregister()

hipError_t hipHostUnregister ( void *  hostPtr)

Un-register host pointer.

Parameters
[in]hostPtrHost pointer previously registered with hipHostRegister
Returns
Error code
See also
hipHostRegister

◆ hipMalloc()

hipError_t hipMalloc ( void **  ptr,
size_t  size 
)

Allocate memory on the default accelerator.

Parameters
[out]ptrPointer to the allocated memory
[in]sizeRequested memory size

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

Returns
hipSuccess, hipErrorOutOfMemory, hipErrorInvalidValue (bad context, null *ptr)
See also
hipMallocPitch, hipFree, hipMallocArray, hipFreeArray, hipMalloc3D, hipMalloc3DArray, hipHostFree, hipHostMalloc

◆ hipMalloc3D()

hipError_t hipMalloc3D ( hipPitchedPtr pitchedDevPtr,
hipExtent  extent 
)

Create a 3D memory pointer on the device.

Parameters
[out]pitchedDevPtrPointer to the 3D memory
[in]extentRequested extent
Returns
hipSuccess, hipErrorInvalidValue, hipErrorNotSupported
See also
hipMallocPitch, hipMemGetInfo, hipFree

◆ hipMalloc3DArray()

hipError_t hipMalloc3DArray ( hipArray_t array,
const struct hipChannelFormatDesc desc,
struct hipExtent  extent,
unsigned int  flags 
)

Allocate an array on the device.

Parameters
[out]arrayPointer to allocated array in device memory
[in]descRequested channel format
[in]extentRequested array allocation width, height and depth
[in]flagsRequested properties of allocated array
Returns
hipSuccess, hipErrorOutOfMemory
See also
hipMalloc, hipMallocPitch, hipFree, hipFreeArray, hipHostMalloc, hipHostFree

◆ hipMallocArray()

hipError_t hipMallocArray ( hipArray_t array,
const hipChannelFormatDesc desc,
size_t  width,
size_t  height,
unsigned int  flags 
)

Allocate an array on the device.

Parameters
[out]arrayPointer to allocated array in device memory
[in]descRequested channel format
[in]widthRequested array allocation width
[in]heightRequested array allocation height
[in]flagsRequested properties of allocated array
Returns
hipSuccess, hipErrorOutOfMemory
See also
hipMalloc, hipMallocPitch, hipFree, hipFreeArray, hipHostMalloc, hipHostFree

◆ hipMallocHost()

hipError_t hipMallocHost ( void **  ptr,
size_t  size 
)

Allocate pinned host memory [Deprecated].

Parameters
[out]ptrPointer to the allocated host pinned memory
[in]sizeRequested memory size

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

Returns
hipSuccess, hipErrorOutOfMemory
Warning
This API is deprecated, use hipHostMalloc() instead

◆ hipMallocPitch()

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

Parameters
[out]ptrPointer to the allocated device memory
[out]pitchPitch for allocation (in bytes)
[in]widthRequested pitched allocation width (in bytes)
[in]heightRequested pitched allocation height

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

Returns
Error code
See also
hipMalloc, hipFree, hipMallocArray, hipFreeArray, hipHostFree, hipMalloc3D, hipMalloc3DArray, hipHostMalloc

◆ hipMemAllocHost()

hipError_t hipMemAllocHost ( void **  ptr,
size_t  size 
)

Allocate pinned host memory [Deprecated].

Parameters
[out]ptrPointer to the allocated host pinned memory
[in]sizeRequested memory size

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

Returns
hipSuccess, hipErrorOutOfMemory
Warning
This API is deprecated, use hipHostMalloc() instead

◆ hipMemAllocPitch()

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

Parameters
[out]dptrPointer to the allocated device memory
[out]pitchPitch for allocation (in bytes)
[in]widthInBytesRequested pitched allocation width (in bytes)
[in]heightRequested pitched allocation height
[in]elementSizeBytesThe size of element bytes, should be 4, 8 or 16

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;

Returns
Error code
See also
hipMalloc, hipFree, hipMallocArray, hipFreeArray, hipHostFree, hipMalloc3D, hipMalloc3DArray, hipHostMalloc

◆ hipMemcpy()

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.

Parameters
[out]dstData being copy to
[in]srcData being copy from
[in]sizeBytesData size in bytes
[in]kindKind of transfer
Returns
hipSuccess, hipErrorInvalidValue, hipErrorUnknown
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

◆ hipMemcpy2D()

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
[in]dstDestination memory address
[in]dpitchPitch of destination memory
[in]srcSource memory address
[in]spitchPitch of source memory
[in]widthWidth of matrix transfer (columns in bytes)
[in]heightHeight of matrix transfer (rows)
[in]kindType of transfer
Returns
hipSuccess, hipErrorInvalidValue, hipErrorInvalidPitchValue, hipErrorInvalidDevicePointer, hipErrorInvalidMemcpyDirection
See also
hipMemcpy, hipMemcpyToArray, hipMemcpy2DToArray, hipMemcpyFromArray, hipMemcpyToSymbol, hipMemcpyAsync

◆ hipMemcpy2DAsync()

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 
)

Copies data between host and device.

Parameters
[in]dstDestination memory address
[in]dpitchPitch of destination memory
[in]srcSource memory address
[in]spitchPitch of source memory
[in]widthWidth of matrix transfer (columns in bytes)
[in]heightHeight of matrix transfer (rows)
[in]kindType of transfer
[in]streamStream to use
Returns
hipSuccess, hipErrorInvalidValue, hipErrorInvalidPitchValue, hipErrorInvalidDevicePointer, hipErrorInvalidMemcpyDirection
See also
hipMemcpy, hipMemcpyToArray, hipMemcpy2DToArray, hipMemcpyFromArray, hipMemcpyToSymbol, hipMemcpyAsync

◆ hipMemcpy2DFromArray()

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
[in]dstDestination memory address
[in]dpitchPitch of destination memory
[in]srcSource memory address
[in]wOffsetSource starting X offset
[in]hOffsetSource starting Y offset
[in]widthWidth of matrix transfer (columns in bytes)
[in]heightHeight of matrix transfer (rows)
[in]kindType of transfer
Returns
hipSuccess, hipErrorInvalidValue, hipErrorInvalidPitchValue, hipErrorInvalidDevicePointer, hipErrorInvalidMemcpyDirection
See also
hipMemcpy, hipMemcpy2DToArray, hipMemcpy2D, hipMemcpyFromArray, hipMemcpyToSymbol, hipMemcpyAsync

◆ hipMemcpy2DFromArrayAsync()

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 
)

Copies data between host and device asynchronously.

Parameters
[in]dstDestination memory address
[in]dpitchPitch of destination memory
[in]srcSource memory address
[in]wOffsetSource starting X offset
[in]hOffsetSource starting Y offset
[in]widthWidth of matrix transfer (columns in bytes)
[in]heightHeight of matrix transfer (rows)
[in]kindType of transfer
[in]streamAccelerator view which the copy is being enqueued
Returns
hipSuccess, hipErrorInvalidValue, hipErrorInvalidPitchValue, hipErrorInvalidDevicePointer, hipErrorInvalidMemcpyDirection
See also
hipMemcpy, hipMemcpy2DToArray, hipMemcpy2D, hipMemcpyFromArray, hipMemcpyToSymbol, hipMemcpyAsync

◆ hipMemcpy2DToArray()

hipError_t hipMemcpy2DToArray ( hipArray_t  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
[in]dstDestination memory address
[in]wOffsetDestination starting X offset
[in]hOffsetDestination starting Y offset
[in]srcSource memory address
[in]spitchPitch of source memory
[in]widthWidth of matrix transfer (columns in bytes)
[in]heightHeight of matrix transfer (rows)
[in]kindType of transfer
Returns
hipSuccess, hipErrorInvalidValue, hipErrorInvalidPitchValue, hipErrorInvalidDevicePointer, hipErrorInvalidMemcpyDirection
See also
hipMemcpy, hipMemcpyToArray, hipMemcpy2D, hipMemcpyFromArray, hipMemcpyToSymbol, hipMemcpyAsync

◆ hipMemcpy2DToArrayAsync()

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

Copies data between host and device.

Parameters
[in]dstDestination memory address
[in]wOffsetDestination starting X offset
[in]hOffsetDestination starting Y offset
[in]srcSource memory address
[in]spitchPitch of source memory
[in]widthWidth of matrix transfer (columns in bytes)
[in]heightHeight of matrix transfer (rows)
[in]kindType of transfer
[in]streamAccelerator view which the copy is being enqueued
Returns
hipSuccess, hipErrorInvalidValue, hipErrorInvalidPitchValue, hipErrorInvalidDevicePointer, hipErrorInvalidMemcpyDirection
See also
hipMemcpy, hipMemcpyToArray, hipMemcpy2D, hipMemcpyFromArray, hipMemcpyToSymbol, hipMemcpyAsync

◆ hipMemcpy3D()

hipError_t hipMemcpy3D ( const struct hipMemcpy3DParms p)

◆ hipMemcpy3DAsync()

hipError_t hipMemcpy3DAsync ( const struct hipMemcpy3DParms p,
hipStream_t  stream 
)

Copies data between host and device asynchronously.

Parameters
[in]p3D memory copy parameters
[in]streamStream to use
Returns
hipSuccess, hipErrorInvalidValue, hipErrorInvalidPitchValue, hipErrorInvalidDevicePointer, hipErrorInvalidMemcpyDirection
See also
hipMemcpy, hipMemcpy2DToArray, hipMemcpy2D, hipMemcpyFromArray, hipMemcpyToSymbol, hipMemcpyAsync

◆ hipMemcpyAsync()

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

Copy data from src to dst asynchronously.

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.
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.

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.

Parameters
[out]dstData being copy to
[in]srcData being copy from
[in]sizeBytesData size in bytes
[in]kindType of memory transfer
[in]streamStream identifier
Returns
hipSuccess, hipErrorInvalidValue, hipErrorUnknown
See also
hipMemcpy, hipMemcpy2D, hipMemcpyToArray, hipMemcpy2DToArray, hipMemcpyFromArray, hipMemcpy2DFromArray, hipMemcpyArrayToArray, hipMemcpy2DArrayToArray, hipMemcpyToSymbol, hipMemcpyFromSymbol, hipMemcpy2DAsync, hipMemcpyToArrayAsync, hipMemcpy2DToArrayAsync, hipMemcpyFromArrayAsync, hipMemcpy2DFromArrayAsync, hipMemcpyToSymbolAsync, hipMemcpyFromSymbolAsync

◆ hipMemcpyAtoH()

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

Copies data between host and device.

Parameters
[in]dstDestination memory address
[in]srcArraySource array
[in]srcOffsetOffset in bytes of source array
[in]countSize of memory copy in bytes
Returns
hipSuccess, hipErrorInvalidValue, hipErrorInvalidPitchValue, hipErrorInvalidDevicePointer, hipErrorInvalidMemcpyDirection
See also
hipMemcpy, hipMemcpy2DToArray, hipMemcpy2D, hipMemcpyFromArray, hipMemcpyToSymbol, hipMemcpyAsync

◆ hipMemcpyDtoD()

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

Copy data from Device to Device.

Parameters
[out]dstData being copy to
[in]srcData being copy from
[in]sizeBytesData size in bytes
Returns
hipSuccess, hipErrorDeinitialized, hipErrorNotInitialized, hipErrorInvalidContext, hipErrorInvalidValue
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

◆ hipMemcpyDtoDAsync()

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

Copy data from Device to Device asynchronously.

Parameters
[out]dstData being copy to
[in]srcData being copy from
[in]sizeBytesData size in bytes
[in]streamStream identifier
Returns
hipSuccess, hipErrorDeinitialized, hipErrorNotInitialized, hipErrorInvalidContext, hipErrorInvalidValue
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

◆ hipMemcpyDtoH()

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

Copy data from Device to Host.

Parameters
[out]dstData being copy to
[in]srcData being copy from
[in]sizeBytesData size in bytes
Returns
hipSuccess, hipErrorDeinitialized, hipErrorNotInitialized, hipErrorInvalidContext, hipErrorInvalidValue
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

◆ hipMemcpyDtoHAsync()

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

Copy data from Device to Host asynchronously.

Parameters
[out]dstData being copy to
[in]srcData being copy from
[in]sizeBytesData size in bytes
[in]streamStream identifier
Returns
hipSuccess, hipErrorDeinitialized, hipErrorNotInitialized, hipErrorInvalidContext, hipErrorInvalidValue
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

◆ hipMemcpyFromArray()

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
[in]dstDestination memory address
[in]srcArraySource memory address
[in]wOffsetSource starting X offset
[in]hOffsetSource starting Y offset
[in]countSize in bytes to copy
[in]kindType of transfer
Returns
hipSuccess, hipErrorInvalidValue, hipErrorInvalidPitchValue, hipErrorInvalidDevicePointer, hipErrorInvalidMemcpyDirection
See also
hipMemcpy, hipMemcpy2DToArray, hipMemcpy2D, hipMemcpyFromArray, hipMemcpyToSymbol, hipMemcpyAsync
Warning
This API is deprecated.

◆ hipMemcpyFromSymbol()

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

Copies data from the given symbol on the device.

Parameters
[out]dstReturns pointer to destinition memory address
[in]symbolPointer to the symbole address on the device
[in]sizeBytesSize in bytes to copy
[in]offsetOffset in bytes from the start of symbole
[in]kindType of memory transfer
Returns
hipSuccess, hipErrorInvalidValue

◆ hipMemcpyFromSymbolAsync()

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

Copies data from the given symbol on the device asynchronously.

Parameters
[out]dstReturns pointer to destinition memory address
[in]symbolpointer to the symbole address on the device
[in]sizeBytessize in bytes to copy
[in]offsetoffset in bytes from the start of symbole
[in]kindtype of memory transfer
[in]streamstream identifier
Returns
hipSuccess, hipErrorInvalidValue

◆ hipMemcpyHtoA()

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

Copies data between host and device.

Parameters
[in]dstArrayDestination memory address
[in]dstOffsetOffset in bytes of destination array
[in]srcHostSource host pointer
[in]countSize of memory copy in bytes
Returns
hipSuccess, hipErrorInvalidValue, hipErrorInvalidPitchValue, hipErrorInvalidDevicePointer, hipErrorInvalidMemcpyDirection
See also
hipMemcpy, hipMemcpy2DToArray, hipMemcpy2D, hipMemcpyFromArray, hipMemcpyToSymbol, hipMemcpyAsync

◆ hipMemcpyHtoD()

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

Copy data from Host to Device.

Parameters
[out]dstData being copy to
[in]srcData being copy from
[in]sizeBytesData size in bytes
Returns
hipSuccess, hipErrorDeinitialized, hipErrorNotInitialized, hipErrorInvalidContext, hipErrorInvalidValue
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

◆ hipMemcpyHtoDAsync()

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

Copy data from Host to Device asynchronously.

Parameters
[out]dstData being copy to
[in]srcData being copy from
[in]sizeBytesData size in bytes
[in]streamStream identifier
Returns
hipSuccess, hipErrorDeinitialized, hipErrorNotInitialized, hipErrorInvalidContext, hipErrorInvalidValue
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

◆ hipMemcpyParam2D()

◆ hipMemcpyParam2DAsync()

hipError_t hipMemcpyParam2DAsync ( const hip_Memcpy2D pCopy,
hipStream_t  stream 
)

◆ hipMemcpyToArray()

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

Copies data between host and device.

Parameters
[in]dstDestination memory address
[in]wOffsetDestination starting X offset
[in]hOffsetDestination starting Y offset
[in]srcSource memory address
[in]countsize in bytes to copy
[in]kindType of transfer
Returns
hipSuccess, hipErrorInvalidValue, hipErrorInvalidPitchValue, hipErrorInvalidDevicePointer, hipErrorInvalidMemcpyDirection
See also
hipMemcpy, hipMemcpy2DToArray, hipMemcpy2D, hipMemcpyFromArray, hipMemcpyToSymbol, hipMemcpyAsync
Warning
This API is deprecated.

◆ hipMemcpyToSymbol()

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

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
[out]symbolpointer to the device symbole
[in]srcpointer to the source address
[in]sizeBytessize in bytes to copy
[in]offsetoffset in bytes from start of symbole
[in]kindtype of memory transfer
Returns
hipSuccess, hipErrorInvalidValue

◆ hipMemcpyToSymbolAsync()

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

Copies data to the given symbol on the device asynchronously.

Parameters
[out]symbolpointer to the device symbole
[in]srcpointer to the source address
[in]sizeBytessize in bytes to copy
[in]offsetoffset in bytes from start of symbole
[in]kindtype of memory transfer
[in]streamstream identifier
Returns
hipSuccess, hipErrorInvalidValue

◆ hipMemcpyWithStream()

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

Memory copy on the stream. It allows single or multiple devices to do memory copy on single or multiple streams.

Parameters
[out]dstData being copy to
[in]srcData being copy from
[in]sizeBytesData size in bytes
[in]kindKind of transfer
[in]streamValid stream
Returns
hipSuccess, hipErrorInvalidValue, hipErrorUnknown, hipErrorContextIsDestroyed
See also
hipMemcpy, hipStreamCreate, hipStreamSynchronize, hipStreamDestroy, hipSetDevice, hipLaunchKernelGGL

◆ hipMemGetInfo()

hipError_t hipMemGetInfo ( size_t *  free,
size_t *  total 
)

Query memory info.

On ROCM, this function gets the actual free memory left on the current device, so supports the cases while running multi-workload (such as multiple processes, multiple threads, and multiple GPUs).

Warning
On Windows, the free memory only accounts for memory allocated by this process and may be optimistic.
Parameters
[out]freeReturns free memory on the current device in bytes
[out]totalReturns total allocatable memory on the current device in bytes
Returns
hipSuccess, hipErrorInvalidDevice, hipErrorInvalidValue

◆ hipMemPtrGetInfo()

hipError_t hipMemPtrGetInfo ( void *  ptr,
size_t *  size 
)

Get allocated memory size via memory pointer.

This function gets the allocated shared virtual memory size from memory pointer.

Parameters
[in]ptrPointer to allocated memory
[out]sizeReturns the allocated memory size in bytes
Returns
hipSuccess, hipErrorInvalidValue

◆ hipMemset()

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
[out]dstData being filled
[in]valueValue to be set
[in]sizeBytesData size in bytes
Returns
hipSuccess, hipErrorInvalidValue, hipErrorNotInitialized

◆ hipMemset2D()

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
[out]dstPointer to device memory
[in]pitchData size in bytes
[in]valueConstant value to be set
[in]width
[in]height
Returns
hipSuccess, hipErrorInvalidValue

◆ hipMemset2DAsync()

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

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

Parameters
[in]dstPointer to 2D device memory
[in]pitchPitch size in bytes
[in]valueValue to be set for each byte of specified memory
[in]widthWidth of matrix set columns in bytes
[in]heightHeight of matrix set rows in bytes
[in]streamStream identifier
Returns
hipSuccess, hipErrorInvalidValue

◆ hipMemset3D()

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

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

Parameters
[in]pitchedDevPtrPointer to pitched device memory
[in]valueValue to set for each byte of specified memory
[in]extentSize parameters for width field in bytes in device memory
Returns
hipSuccess, hipErrorInvalidValue

◆ hipMemset3DAsync()

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

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

Parameters
[in]pitchedDevPtrPointer to pitched device memory
[in]valueValue to set for each byte of specified memory
[in]extentSize parameters for width field in bytes in device memory
[in]streamStream identifier
Returns
hipSuccess, hipErrorInvalidValue

◆ hipMemsetAsync()

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

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
[out]dstPointer to device memory
[in]valueValue to set for each byte of specified memory
[in]sizeBytesSize in bytes to set
[in]streamStream identifier
Returns
hipSuccess, hipErrorInvalidValue

◆ hipMemsetD16()

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
[out]destData ptr to be filled
[in]valueConstant value to be set
[in]countNumber of values to be set
Returns
hipSuccess, hipErrorInvalidValue, hipErrorNotInitialized

◆ hipMemsetD16Async()

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

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
[out]destData ptr to be filled
[in]valueConstant value to be set
[in]countNumber of values to be set
[in]streamStream identifier
Returns
hipSuccess, hipErrorInvalidValue, hipErrorNotInitialized

◆ hipMemsetD32()

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
[out]destData being filled
[in]valueConstant value to be set
[in]countNumber of values to be set
Returns
hipSuccess, hipErrorInvalidValue, hipErrorNotInitialized

◆ hipMemsetD32Async()

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

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
[out]dstPointer to device memory
[in]valueValue to set for each byte of specified memory
[in]countNumber of values to be set
[in]streamStream identifier
Returns
hipSuccess, hipErrorInvalidValue

◆ hipMemsetD8()

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
[out]destData ptr to be filled
[in]valueValue to be set
[in]countNumber of values to be set
Returns
hipSuccess, hipErrorInvalidValue, hipErrorNotInitialized

◆ hipMemsetD8Async()

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

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
[out]destData ptr to be filled
[in]valueConstant value to be set
[in]countNumber of values to be set
[in]streamStream identifier
Returns
hipSuccess, hipErrorInvalidValue, hipErrorNotInitialized

◆ hipModuleGetGlobal()

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
[out]dptrReturns global device pointer
[out]bytesReturns global size in bytes
[in]hmodModule to retrieve global from
[in]nameName of global to retrieve
Returns
hipSuccess, hipErrorInvalidValue, hipErrorNotFound, hipErrorInvalidContext

◆ hipPointerGetAttribute()

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

Returns information about the specified pointer.[BETA].

Parameters
[in,out]dataReturned pointer attribute value
[in]attributeAttribute to query for
[in]ptrPointer to get attributes for
Returns
hipSuccess, hipErrorInvalidDevice, hipErrorInvalidValue
Warning
This API is marked as beta, meaning, while this is feature complete, it is still open to changes and may have outstanding issues.
See also
hipPointerGetAttributes

◆ hipPointerGetAttributes()

hipError_t hipPointerGetAttributes ( hipPointerAttribute_t attributes,
const void *  ptr 
)

Return attributes for the specified pointer.

Parameters
[out]attributesattributes for the specified pointer
[in]ptrpointer to get attributes for
Note
: To get pointer's memory type, the parameter attributes has 'type' as member variable. The 'type' indicates input pointer is allocated on device or host. That means the input pointer must be returned or passed through an HIP API such as hipHostMalloc, hipMallocManaged, hipHostRegister, etc. Otherwise, the pointer can't be handled by this API and attributes returned hipErrorInvalidValue, due to the hipMemoryType enums values, unrecognized memory type is currently not supported due to HIP functionality backward compatibility.
Returns
hipSuccess, hipErrorInvalidDevice, hipErrorInvalidValue
See also
hipPointerGetAttribute

◆ hipPointerSetAttribute()

hipError_t hipPointerSetAttribute ( const void *  value,
hipPointer_attribute  attribute,
hipDeviceptr_t  ptr 
)

Sets information on the specified pointer.[BETA].

Parameters
[in]valueSets pointer attribute value
[in]attributeAttribute to set
[in]ptrPointer to set attributes for
Returns
hipSuccess, hipErrorInvalidDevice, hipErrorInvalidValue
Warning
This API is marked as beta, meaning, while this is feature complete, it is still open to changes and may have outstanding issues.