Memory Management

Functions
hipError_t	hipPointerGetAttributes (hipPointerAttribute_t *attributes, void *ptr)
	Return attributes for the specified pointer. More...
hipError_t	hipMalloc (void **ptr, size_t size)
	Allocate memory on the default accelerator. More...
hipError_t	hipMallocHost (void **ptr, size_t size) __attribute__((deprecated("use hipHostMalloc instead")))
	Allocate pinned host memory. More...
hipError_t	hipHostMalloc (void **ptr, size_t size, unsigned int flags)
	Allocate device accessible page locked host memory. More...
hipError_t	hipHostAlloc (void **ptr, size_t size, unsigned int flags) __attribute__((deprecated("use hipHostMalloc instead")))
hipError_t	hipHostGetDevicePointer (void **devPtr, void *hstPtr, unsigned int flags)
	Get Device pointer from Host Pointer allocated through hipHostAlloc. More...
hipError_t	hipHostGetFlags (unsigned int *flagsPtr, void *hostPtr)
	Get 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	hipFree (void *ptr)
	Free memory allocated by the hcc hip memory allocation API. This API performs an implicit hipDeviceSynchronize() call. More...
hipError_t	hipFreeHost (void *ptr) __attribute__((deprecated("use hipHostFree instead")))
	Free memory allocated by the hcc hip host memory allocation API. More...
hipError_t	hipHostFree (void *ptr)
	Free memory allocated by the hcc hip host memory allocation API. More...
hipError_t	hipMemcpy (void *dst, const void *src, size_t sizeBytes, hipMemcpyKind kind)
	Copy data from src to dst. More...
hipError_t	hipMemcpyToSymbol (const char *symbolName, const void *src, size_t sizeBytes, size_t offset, hipMemcpyKind kind)
	Copies sizeBytes bytes from the memory area pointed to by src to the memory area pointed to by offset bytes from the start of symbol symbol. 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)
	Copy data from src to dst asynchronously. 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	hipMemGetInfo (size_t *free, size_t *total)
	Query memory info. Return snapshot of free memory, and total allocatable memory on the device. More...

Detailed Description

----------------------------------------------------------------------------------------------—

The following CUDA APIs are not currently supported:

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

Function Documentation

hipError_t hipFree

(

void *

ptr

)

Free memory allocated by the hcc hip memory allocation API. This API performs an implicit hipDeviceSynchronize() call.

Parameters

[in]

ptr

Pointer to memory to be freed

Returns

hipSuccess, hipErrorMemoryFree

hipError_t hipFreeHost

(

void *

ptr

)

Free memory allocated by the hcc hip host memory allocation API.

Parameters

[in]

ptr

Pointer to memory to be freed

Returns

hipSuccess, hipErrorMemoryFree

hipError_t hipHostFree

(

void *

ptr

)

Free memory allocated by the hcc hip host memory allocation API.

Parameters

[in]

ptr

Pointer to memory to be freed

Returns

hipSuccess, hipErrorMemoryFree

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

Get Device pointer from Host Pointer allocated through hipHostAlloc.

Parameters

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

Returns

Error code

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

Get flags associated with host pointer.

Parameters

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

Returns

Error code

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

Allocate device accessible page locked host memory.

Parameters

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

Returns

Error code

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, hipErrorMemoryAllocation

hipError_t hipHostUnregister

(

void *

hostPtr

)

Un-register host pointer.

Parameters

[in]

hostPtr

Host pointer previously registered with hipHostRegister

Returns

Error code

hipError_t hipMalloc	(	void **	ptr,
		size_t	sizeBytes
	)

Allocate memory on the default accelerator.

Parameters

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

Returns

hipSuccess

hipSuccess hipErrorMemoryAllocation

hipError_t hipMallocHost	(	void **	ptr,
		size_t	size
	)

Allocate pinned host memory.

Parameters

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

Returns

Error code

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.

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

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.

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

hipSuccess, hipErrorInvalidDevice, hipErrorInvalidMemcpyDirection,

hipErrorInvalidValue : If dst==NULL or src==NULL, or other bad argument.

Warning

on HCC hipMemcpyAsync does not support overlapped H2D and D2H copies.

on HCC hipMemcpyAsync requires that any host pointers are pinned (ie via the hipMallocHost call).

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

Copies sizeBytes bytes from the memory area pointed to by src to the memory area pointed to by offset bytes from the start of symbol symbol.

The memory areas may not overlap. Symbol can either be a variable that resides in global or constant memory space, or it can be a character string, naming a variable that resides in global or constant memory space. Kind can be either hipMemcpyHostToDevice or hipMemcpyDeviceToDevice TODO: cudaErrorInvalidSymbol and cudaErrorInvalidMemcpyDirection is not supported, use hipErrorUnknown for now.

Parameters

[in]	symbolName	- Symbol destination on device
[in]	src	- Data being copy from
[in]	sizeBytes	- Data size in bytes
[in]	offset	- Offset from start of symbol in bytes
[in]	kind	- Type of transfer

Returns

hipSuccess, hipErrorInvalidValue, hipErrorMemoryFree, hipErrorUnknown

hipError_t hipMemGetInfo	(	size_t *	free,
		size_t *	total
	)

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

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

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

Copy data from src to dst asynchronously.

It supports memory from host to device, device to host, device to device and host to 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

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

hipErrorInvalidValue

hipError_t hipPointerGetAttributes	(	hipPointerAttribute_t *	attributes,
		void *	ptr
	)

Return attributes for the specified pointer.

Returns

hipSuccess, hipErrorInvalidValue, hipErrorInvalidDevice