Memory Management

Modules | Functions

Memory Management

HIP API

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].
hipError_t	hipPointerGetAttributes (hipPointerAttribute_t *attributes, const void *ptr)
	Return attributes for the specified pointer.
hipError_t	hipPointerGetAttribute (void *data, hipPointer_attribute attribute, hipDeviceptr_t ptr)
	Returns information about the specified pointer.[BETA].
hipError_t	hipDrvPointerGetAttributes (unsigned int numAttributes, hipPointer_attribute *attributes, void **data, hipDeviceptr_t ptr)
	Returns information about the specified pointer.[BETA].
hipError_t	hipMalloc (void **ptr, size_t size)
	Allocate memory on the default accelerator.
hipError_t	hipExtMallocWithFlags (void **ptr, size_t sizeBytes, unsigned int flags)
	Allocate memory on the default accelerator.
hipError_t	hipMallocHost (void **ptr, size_t size)
	Allocate pinned host memory [Deprecated].
hipError_t	hipMemAllocHost (void **ptr, size_t size)
	Allocate pinned host memory [Deprecated].
hipError_t	hipHostMalloc (void **ptr, size_t size, unsigned int flags)
	Allocates device accessible page locked (pinned) host memory.
hipError_t	hipHostAlloc (void **ptr, size_t size, unsigned int flags)
	Allocate device accessible page locked host memory [Deprecated].
hipError_t	hipHostGetDevicePointer (void **devPtr, void *hstPtr, unsigned int flags)
	Get Device pointer from Host Pointer allocated through hipHostMalloc.
hipError_t	hipHostGetFlags (unsigned int *flagsPtr, void *hostPtr)
	Return flags associated with host pointer.
hipError_t	hipHostRegister (void *hostPtr, size_t sizeBytes, unsigned int flags)
	Register host memory so it can be accessed from the current device.
hipError_t	hipHostUnregister (void *hostPtr)
	Un-register host pointer.
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.
hipError_t	hipFreeHost (void *ptr)
	Free memory allocated by the hcc hip host memory allocation API [Deprecated].
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.
hipError_t	hipMemcpy (void *dst, const void *src, size_t sizeBytes, hipMemcpyKind kind)
	Copy data from src to dst.
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.
hipError_t	hipMemcpyHtoD (hipDeviceptr_t dst, void *src, size_t sizeBytes)
	Copy data from Host to Device.
hipError_t	hipMemcpyDtoH (void *dst, hipDeviceptr_t src, size_t sizeBytes)
	Copy data from Device to Host.
hipError_t	hipMemcpyDtoD (hipDeviceptr_t dst, hipDeviceptr_t src, size_t sizeBytes)
	Copy data from Device to Device.
hipError_t	hipMemcpyHtoDAsync (hipDeviceptr_t dst, void *src, size_t sizeBytes, hipStream_t stream)
	Copy data from Host to Device asynchronously.
hipError_t	hipMemcpyDtoHAsync (void *dst, hipDeviceptr_t src, size_t sizeBytes, hipStream_t stream)
	Copy data from Device to Host asynchronously.
hipError_t	hipMemcpyDtoDAsync (hipDeviceptr_t dst, hipDeviceptr_t src, size_t sizeBytes, hipStream_t stream)
	Copy data from Device to Device asynchronously.
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.
hipError_t	hipGetSymbolAddress (void **devPtr, const void *symbol)
	Gets device pointer associated with symbol on the device.
hipError_t	hipGetSymbolSize (size_t *size, const void *symbol)
	Gets the size of the given symbol on the device.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
hipError_t	hipMemset3D (hipPitchedPtr pitchedDevPtr, int value, hipExtent extent)
	Fills synchronously the memory area pointed to by pitchedDevPtr with the constant value.
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.
hipError_t	hipMemGetInfo (size_t *free, size_t *total)
	Query memory info.
hipError_t	hipMemPtrGetInfo (void *ptr, size_t *size)
	Get allocated memory size via memory pointer.
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.
hipError_t	hipArrayCreate (hipArray **pHandle, const HIP_ARRAY_DESCRIPTOR *pAllocateArray)
	Create an array memory pointer on the device.
hipError_t	hipArrayDestroy (hipArray *array)
	Destroy an array memory pointer on the device.
hipError_t	hipArray3DCreate (hipArray **array, const HIP_ARRAY3D_DESCRIPTOR *pAllocateArray)
	Create a 3D array memory pointer on the device.
hipError_t	hipMalloc3D (hipPitchedPtr *pitchedDevPtr, hipExtent extent)
	Create a 3D memory pointer on the device.
hipError_t	hipFreeArray (hipArray *array)
	Frees an array on the device.
hipError_t	hipMalloc3DArray (hipArray **array, const struct hipChannelFormatDesc *desc, struct hipExtent extent, unsigned int flags)
	Allocate an array on the device.
hipError_t	hipArrayGetInfo (hipChannelFormatDesc *desc, hipExtent *extent, unsigned int *flags, hipArray *array)
	Gets info about the specified array.
hipError_t	hipArrayGetDescriptor (HIP_ARRAY_DESCRIPTOR *pArrayDescriptor, hipArray *array)
	Gets a 1D or 2D array descriptor.
hipError_t	hipArray3DGetDescriptor (HIP_ARRAY3D_DESCRIPTOR *pArrayDescriptor, hipArray *array)
	Gets a 3D array descriptor.
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.
hipError_t	hipMemcpyParam2D (const hip_Memcpy2D *pCopy)
	Copies memory for 2D arrays.
hipError_t	hipMemcpyParam2DAsync (const hip_Memcpy2D *pCopy, hipStream_t stream __dparm(0))
	Copies memory for 2D arrays.
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.
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.
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.
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.
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.
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.
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.
hipError_t	hipMemcpyAtoH (void *dst, hipArray *srcArray, size_t srcOffset, size_t count)
	Copies data between host and device.
hipError_t	hipMemcpyHtoA (hipArray *dstArray, size_t dstOffset, const void *srcHost, size_t count)
	Copies data between host and device.
hipError_t	hipMemcpy3D (const struct hipMemcpy3DParms *p)
	Copies data between host and device.
hipError_t	hipMemcpy3DAsync (const struct hipMemcpy3DParms *p, hipStream_t stream __dparm(0))
	Copies data between host and device asynchronously.
hipError_t	hipDrvMemcpy3D (const HIP_MEMCPY3D *pCopy)
	Copies data between host and device.
hipError_t	hipDrvMemcpy3DAsync (const HIP_MEMCPY3D *pCopy, hipStream_t stream)
	Copies data between host and device asynchronously.

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 **	array,
		const HIP_ARRAY3D_DESCRIPTOR *	pAllocateArray
	)

Create a 3D array memory pointer on the device.

Parameters

[out]	array	Pointer to the 3D array memory
[in]	pAllocateArray	Requested array desciptor

Returns

hipSuccess, hipErrorInvalidValue, hipErrorNotSupported

See also

hipMallocArray, hipArrayDestroy, hipFreeArray

◆ hipArray3DGetDescriptor()

hipError_t hipArray3DGetDescriptor	(	HIP_ARRAY3D_DESCRIPTOR *	pArrayDescriptor,
		hipArray *	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 **	pHandle,
		const HIP_ARRAY_DESCRIPTOR *	pAllocateArray
	)

Create an array memory pointer on the device.

Parameters

[out]	pHandle	Pointer to the array memory
[in]	pAllocateArray	Requested array desciptor

Returns

hipSuccess, hipErrorInvalidValue, hipErrorNotSupported

See also

hipMallocArray, hipArrayDestroy, hipFreeArray

◆ hipArrayDestroy()

hipError_t hipArrayDestroy

(

hipArray *

array

)

Destroy an array memory pointer on the device.

Parameters

[in]

array

Pointer to the array memory

Returns

hipSuccess, hipErrorInvalidValue

See also

hipArrayCreate, hipArrayDestroy, hipFreeArray

◆ hipArrayGetDescriptor()

hipError_t hipArrayGetDescriptor	(	HIP_ARRAY_DESCRIPTOR *	pArrayDescriptor,
		hipArray *	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 *	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

)

Copies data between host and device.

Parameters

[in]

pCopy

3D memory copy parameters

Returns

hipSuccess, hipErrorInvalidValue, hipErrorInvalidPitchValue, hipErrorInvalidDevicePointer, hipErrorInvalidMemcpyDirection

See also

hipMemcpy, hipMemcpy2DToArray, hipMemcpy2D, hipMemcpyFromArray, hipMemcpyToSymbol, hipMemcpyAsync

◆ hipDrvMemcpy3DAsync()

hipError_t hipDrvMemcpy3DAsync	(	const HIP_MEMCPY3D *	pCopy,
		hipStream_t	stream
	)

Copies data between host and device asynchronously.

Parameters

[in]	pCopy	3D memory copy parameters
[in]	stream	Stream 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]	numAttributes	number of attributes to query for
[in]	attributes	attributes to query for
[in,out]	data	a two-dimensional containing pointers to memory locations where the result of each attribute query will be written to
[in]	ptr	pointer to get attributes for

Returns

hipSuccess, hipErrorInvalidDevice, hipErrorInvalidValue

@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

◆ hipExtMallocWithFlags()

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

Allocate memory on the default accelerator.

Parameters

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

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

◆ 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]

ptr

Pointer 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 *

array

)

Frees an array on the device.

Parameters

[in]

array

Pointer 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]

ptr

Pointer 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

◆ hipGetSymbolAddress()

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

Gets device pointer associated with symbol on the device.

Parameters

[out]	devPtr	pointer to the device associated the symbole
[in]	symbol	pointer 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]	symbol	pointer to the device symbole
[out]	size	pointer 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]	ptr	Pointer to the allocated host pinned memory
[in]	size	Requested memory size in bytes
[in]	flags	Type 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]

ptr

Pointer 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]	dstPtr	Device Pointer mapped to passed host pointer
[in]	hstPtr	Host Pointer allocated through hipHostMalloc
[in]	flags	Flags 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]	flagsPtr	Memory location to store flags
[in]	hostPtr	Host 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]	ptr	Pointer to the allocated host pinned memory
[in]	size	Requested memory size in bytes If size is 0, no memory is allocated, *ptr returns nullptr, and hipSuccess is returned.
[in]	flags	Type of host memory allocation

The flags are defined as hipHostMallocDefault, hipHostMallocPortable, hipHostMallocMapped, hipHostMallocWriteCombined, hipHostMallocNumaUser, hipHostMallocCoherent, and hipHostMallocNonCoherent.

All flags are independent, and can be used in any combination, for instance, hipHostMalloc can be called with both hipHostMallocPortable and hipHostMallocMapped flags set. Both models use the same allocation flags, the difference is how the surrounding code uses the host memory. hipHostMallocCoherent and hipHostMallocNonCoherent are used as coherency control options.

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]	hostPtr	Pointer to host memory to be registered.
[in]	sizeBytes	size of the host memory
[in]	flags.	See below.

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.

Returns

hipSuccess, hipErrorOutOfMemory

See also

hipHostUnregister, hipHostGetFlags, hipHostGetDevicePointer

◆ hipHostUnregister()

hipError_t hipHostUnregister

(

void *

hostPtr

)

Un-register host pointer.

Parameters

[in]

hostPtr

Host 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]	ptr	Pointer to the allocated memory
[in]	size	Requested 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]	pitchedDevPtr	Pointer to the 3D memory
[in]	extent	Requested extent

Returns

hipSuccess, hipErrorInvalidValue, hipErrorNotSupported

See also

hipMallocPitch, hipMemGetInfo, hipFree

◆ hipMalloc3DArray()

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

Allocate an array on the device.

Parameters

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

Returns

hipSuccess, hipErrorOutOfMemory

See also

hipMalloc, hipMallocPitch, hipFree, hipFreeArray, hipHostMalloc, hipHostFree

◆ hipMallocArray()

hipError_t hipMallocArray	(	hipArray **	array,
		const hipChannelFormatDesc *	desc,
		size_t	width,
		size_t height	__dparm0,
		unsigned int flags	__dparmhipArrayDefault
	)

Allocate an array on the device.

Parameters

[out]	array	Pointer to allocated array in device memory
[in]	desc	Requested channel format
[in]	width	Requested array allocation width
[in]	height	Requested array allocation height
[in]	flags	Requested 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]	ptr	Pointer to the allocated host pinned memory
[in]	size	Requested 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]	ptr	Pointer to the allocated device memory
[out]	pitch	Pitch for allocation (in bytes)
[in]	width	Requested pitched allocation width (in bytes)
[in]	height	Requested 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]	ptr	Pointer to the allocated host pinned memory
[in]	size	Requested 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]	dptr	Pointer to the allocated device memory
[out]	pitch	Pitch for allocation (in bytes)
[in]	width	Requested pitched allocation width (in bytes)
[in]	height	Requested pitched allocation height

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]	dst	Data being copy to
[in]	src	Data being copy from
[in]	sizeBytes	Data size in bytes
[in]	copyType	Memory copy type

Returns

hipSuccess, hipErrorInvalidValue, #hipErrorMemoryFree, 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]	dst	Destination memory address
[in]	dpitch	Pitch of destination memory
[in]	src	Source memory address
[in]	spitch	Pitch of source memory
[in]	width	Width of matrix transfer (columns in bytes)
[in]	height	Height of matrix transfer (rows)
[in]	kind	Type 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	__dparm0
	)

Copies data between host and device.

Parameters

[in]	dst	Destination memory address
[in]	dpitch	Pitch of destination memory
[in]	src	Source memory address
[in]	spitch	Pitch of source memory
[in]	width	Width of matrix transfer (columns in bytes)
[in]	height	Height of matrix transfer (rows)
[in]	kind	Type of transfer
[in]	stream	Stream 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]	dst	Destination memory address
[in]	dpitch	Pitch of destination memory
[in]	src	Source memory address
[in]	wOffset	Source starting X offset
[in]	hOffset	Source starting Y offset
[in]	width	Width of matrix transfer (columns in bytes)
[in]	height	Height of matrix transfer (rows)
[in]	kind	Type 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	__dparm0
	)

Copies data between host and device asynchronously.

Parameters

[in]	dst	Destination memory address
[in]	dpitch	Pitch of destination memory
[in]	src	Source memory address
[in]	wOffset	Source starting X offset
[in]	hOffset	Source starting Y offset
[in]	width	Width of matrix transfer (columns in bytes)
[in]	height	Height of matrix transfer (rows)
[in]	kind	Type of transfer
[in]	stream	Accelerator 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 *	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]	dst	Destination memory address
[in]	wOffset	Destination starting X offset
[in]	hOffset	Destination starting Y offset
[in]	src	Source memory address
[in]	spitch	Pitch of source memory
[in]	width	Width of matrix transfer (columns in bytes)
[in]	height	Height of matrix transfer (rows)
[in]	kind	Type of transfer

Returns

hipSuccess, hipErrorInvalidValue, hipErrorInvalidPitchValue, hipErrorInvalidDevicePointer, hipErrorInvalidMemcpyDirection

See also

hipMemcpy, hipMemcpyToArray, hipMemcpy2D, hipMemcpyFromArray, hipMemcpyToSymbol, hipMemcpyAsync

◆ hipMemcpy2DToArrayAsync()

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	__dparm0
	)

Copies data between host and device.

Parameters

[in]	dst	Destination memory address
[in]	wOffset	Destination starting X offset
[in]	hOffset	Destination starting Y offset
[in]	src	Source memory address
[in]	spitch	Pitch of source memory
[in]	width	Width of matrix transfer (columns in bytes)
[in]	height	Height of matrix transfer (rows)
[in]	kind	Type of transfer
[in]	stream	Accelerator 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

)

Copies data between host and device.

Parameters

[in]

p

3D memory copy parameters

Returns

hipSuccess, hipErrorInvalidValue, hipErrorInvalidPitchValue, hipErrorInvalidDevicePointer, hipErrorInvalidMemcpyDirection

See also

hipMemcpy, hipMemcpy2DToArray, hipMemcpy2D, hipMemcpyFromArray, hipMemcpyToSymbol, hipMemcpyAsync

◆ hipMemcpy3DAsync()

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

Copies data between host and device asynchronously.

Parameters

[in]	p	3D memory copy parameters
[in]	stream	Stream 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	__dparm0
	)

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]	dst	Data being copy to
[in]	src	Data being copy from
[in]	sizeBytes	Data size in bytes
[in]	accelerator_view	Accelerator view which the copy is being enqueued

Returns

hipSuccess, hipErrorInvalidValue, #hipErrorMemoryFree, 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 *	srcArray,
		size_t	srcOffset,
		size_t	count
	)

Copies data between host and device.

Parameters

[in]	dst	Destination memory address
[in]	srcArray	Source array
[in]	srcoffset	Offset in bytes of source array
[in]	count	Size 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]	dst	Data being copy to
[in]	src	Data being copy from
[in]	sizeBytes	Data 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]	dst	Data being copy to
[in]	src	Data being copy from
[in]	sizeBytes	Data 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

◆ hipMemcpyDtoH()

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

Copy data from Device to Host.

Parameters

[out]	dst	Data being copy to
[in]	src	Data being copy from
[in]	sizeBytes	Data 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]	dst	Data being copy to
[in]	src	Data being copy from
[in]	sizeBytes	Data 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

◆ 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]	dst	Destination memory address
[in]	srcArray	Source memory address
[in]	wOffset	Source starting X offset
[in]	hOffset	Source starting Y offset
[in]	count	Size in bytes to copy
[in]	kind	Type 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	__dparm0,
		hipMemcpyKind kind	__dparmhipMemcpyDeviceToHost
	)

Copies data from the given symbol on the device.

Parameters

[out]	dptr	Returns pointer to destinition memory address
[in]	symbol	pointer to the symbole address on the device
[in]	sizeBytes	size in bytes to copy
[in]	offset	offset in bytes from the start of symbole
[in]	kind	type 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	__dparm0
	)

Copies data from the given symbol on the device asynchronously.

Parameters

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

Returns

hipSuccess, hipErrorInvalidValue

◆ hipMemcpyHtoA()

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

Copies data between host and device.

Parameters

[in]	dstArray	Destination memory address
[in]	dstOffset	Offset in bytes of destination array
[in]	srcHost	Source host pointer
[in]	count	Size 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]	dst	Data being copy to
[in]	src	Data being copy from
[in]	sizeBytes	Data 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]	dst	Data being copy to
[in]	src	Data being copy from
[in]	sizeBytes	Data 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

◆ hipMemcpyParam2D()

hipError_t hipMemcpyParam2D

(

const hip_Memcpy2D *

pCopy

)

Copies memory for 2D arrays.

Parameters

[in]

pCopy

Parameters for the memory copy

Returns

hipSuccess, hipErrorInvalidValue, hipErrorInvalidPitchValue, hipErrorInvalidDevicePointer, hipErrorInvalidMemcpyDirection

See also

hipMemcpy, hipMemcpy2D, hipMemcpyToArray, hipMemcpy2DToArray, hipMemcpyFromArray, hipMemcpyToSymbol, hipMemcpyAsync

◆ hipMemcpyParam2DAsync()

hipError_t hipMemcpyParam2DAsync	(	const hip_Memcpy2D *	pCopy,
		hipStream_t stream	__dparm0
	)

Copies memory for 2D arrays.

Parameters

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

Returns

hipSuccess, hipErrorInvalidValue, hipErrorInvalidPitchValue, hipErrorInvalidDevicePointer, hipErrorInvalidMemcpyDirection

See also

hipMemcpy, hipMemcpy2D, hipMemcpyToArray, hipMemcpy2DToArray, hipMemcpyFromArray, hipMemcpyToSymbol, hipMemcpyAsync

◆ hipMemcpyToArray()

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

[in]	dst	Destination memory address
[in]	wOffset	Destination starting X offset
[in]	hOffset	Destination starting Y offset
[in]	src	Source memory address
[in]	count	size in bytes to copy
[in]	kind	Type 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	__dparm0,
		hipMemcpyKind kind	__dparmhipMemcpyHostToDevice
	)

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]	symbol	pointer to the device symbole
[in]	src	pointer to the source address
[in]	sizeBytes	size in bytes to copy
[in]	offset	offset in bytes from start of symbole
[in]	kind	type 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	__dparm0
	)

Copies data to the given symbol on the device asynchronously.

Parameters

[out]	symbol	pointer to the device symbole
[in]	src	pointer to the source address
[in]	sizeBytes	size in bytes to copy
[in]	offset	offset in bytes from start of symbole
[in]	kind	type of memory transfer
[in]	stream	stream 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]	dst	Data being copy to
[in]	src	Data being copy from
[in]	sizeBytes	Data size in bytes
[in]	copyType	Memory copy type
[in]	stream	Valid stream

Returns

hipSuccess, hipErrorInvalidValue, #hipErrorMemoryFree, 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]	free	Returns free memory on the current device in bytes
[out]	total	Returns 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]	ptr	Pointer to allocated memory
[out]	size	Returns 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]	dst	Data being filled
[in]	constant	value to be set
[in]	sizeBytes	Data 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]	dst	Pointer to device memory
[in]	pitch	- data size in bytes
[in]	value	- constant value to be set
[in]	width
[in]	height

Returns

hipSuccess, hipErrorInvalidValue, #hipErrorMemoryFree

◆ hipMemset2DAsync()

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

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

Parameters

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

Returns

hipSuccess, hipErrorInvalidValue, #hipErrorMemoryFree

◆ 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]	pitchedDevPtr
[in]	value	- constant value to be set
[in]	extent

Returns

hipSuccess, hipErrorInvalidValue, #hipErrorMemoryFree

◆ hipMemset3DAsync()

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

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

Parameters

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

Returns

hipSuccess, hipErrorInvalidValue, #hipErrorMemoryFree

◆ hipMemsetAsync()

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

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]	dst	Pointer to device memory
[in]	value	- Value to set for each byte of specified memory
[in]	sizeBytes	- Size in bytes to set
[in]	stream	- Stream identifier

Returns

hipSuccess, hipErrorInvalidValue, #hipErrorMemoryFree

◆ 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]	dst	Data ptr to be filled
[in]	constant	value to be set
[in]	number	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	__dparm0
	)

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]	dst	Data ptr to be filled
[in]	constant	value to be set
[in]	number	of values to be set
[in]	stream	- Stream 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]	dst	Data being filled
[in]	constant	value to be set
[in]	number	of values to be set

Returns

hipSuccess, hipErrorInvalidValue, hipErrorNotInitialized

◆ hipMemsetD32Async()

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

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]	dst	Pointer to device memory
[in]	value	- Value to set for each byte of specified memory
[in]	count	- number of values to be set
[in]	stream	- Stream identifier

Returns

hipSuccess, hipErrorInvalidValue, #hipErrorMemoryFree

◆ 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]	dst	Data ptr to be filled
[in]	constant	value to be set
[in]	number	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	__dparm0
	)

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]	dst	Data ptr to be filled
[in]	constant	value to be set
[in]	number	of values to be set
[in]	stream	- Stream 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]	dptr	Returns global device pointer
[out]	bytes	Returns global size in bytes
[in]	hmod	Module to retrieve global from
[in]	name	Name 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]	data	returned pointer attribute value
[in]	atribute	attribute to query for
[in]	ptr	pointer to get attributes for

Returns

hipSuccess, hipErrorInvalidDevice, hipErrorInvalidValue

@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

◆ hipPointerGetAttributes()

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

Return attributes for the specified pointer.

Parameters

[out]	attributes	attributes for the specified pointer
[in]	ptr	pointer 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 couldn'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]	value	sets pointer attribute value
[in]	atribute	attribute to set
[in]	ptr	pointer to set attributes for

Returns

hipSuccess, hipErrorInvalidDevice, hipErrorInvalidValue

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