Memory Management

Memory Management#

HIP Runtime API Reference: Memory Management

Collaboration diagram for Memory Management:

Functions
hipError_t	hipMemAddressFree (void *devPtr, size_t size)
	Frees an address range reservation made via hipMemAddressReserve. More...

hipError_t	hipMemAddressReserve (void *ptr, size_t size, size_t alignment, void addr, unsigned long long flags)
	Reserves an address range. More...

hipError_t	hipMemCreate (hipMemGenericAllocationHandle_t handle, size_t size, const hipMemAllocationProp prop, unsigned long long flags)
	Creates a memory allocation described by the properties and size. More...

hipError_t	hipMemExportToShareableHandle (void *shareableHandle, hipMemGenericAllocationHandle_t handle, hipMemAllocationHandleType handleType, unsigned long long flags)
	Exports an allocation to a requested shareable handle type. More...

hipError_t	hipMemGetAccess (unsigned long long flags, const hipMemLocation location, void *ptr)
	Get the access flags set for the given location and ptr. More...

hipError_t	hipMemGetAllocationGranularity (size_t granularity, const hipMemAllocationProp prop, hipMemAllocationGranularity_flags option)
	Calculates either the minimal or recommended granularity. More...

hipError_t	hipMemGetAllocationPropertiesFromHandle (hipMemAllocationProp *prop, hipMemGenericAllocationHandle_t handle)
	Retrieve the property structure of the given handle. More...

hipError_t	hipMemImportFromShareableHandle (hipMemGenericAllocationHandle_t handle, void osHandle, hipMemAllocationHandleType shHandleType)
	Imports an allocation from a requested shareable handle type. More...

hipError_t	hipMemMap (void *ptr, size_t size, size_t offset, hipMemGenericAllocationHandle_t handle, unsigned long long flags)
	Maps an allocation handle to a reserved virtual address range. More...

hipError_t	hipMemMapArrayAsync (hipArrayMapInfo *mapInfoList, unsigned int count, hipStream_t stream)
	Maps or unmaps subregions of sparse HIP arrays and sparse HIP mipmapped arrays. More...

hipError_t	hipMemRelease (hipMemGenericAllocationHandle_t handle)
	Release a memory handle representing a memory allocation which was previously allocated through hipMemCreate. More...

hipError_t	hipMemRetainAllocationHandle (hipMemGenericAllocationHandle_t handle, void addr)
	Returns the allocation handle of the backing memory allocation given the address. More...

hipError_t	hipMemSetAccess (void ptr, size_t size, const hipMemAccessDesc desc, size_t count)
	Set the access flags for each location specified in desc for the given virtual address range. More...

hipError_t	hipMemUnmap (void *ptr, size_t size)
	Unmap memory allocation of a given address range. More...

Detailed Description

This section describes the virtual memory management functions of HIP runtime API.

Function Documentation

◆ hipMemAddressFree()

hipError_t hipMemAddressFree	(	void *	devPtr,
		size_t	size
	)

Frees an address range reservation made via hipMemAddressReserve.

Parameters

[in]	devPtr	- starting address of the range.
[in]	size	- size of the range.

Returns: hipSuccess, hipErrorInvalidValue, hipErrorNotSupported

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

◆ hipMemAddressReserve()

hipError_t hipMemAddressReserve	(	void **	ptr,
		size_t	size,
		size_t	alignment,
		void *	addr,
		unsigned long long	flags
	)

Reserves an address range.

Parameters

[out]	ptr	- starting address of the reserved range.
[in]	size	- size of the reservation.
[in]	alignment	- alignment of the address.
[in]	addr	- requested starting address of the range.
[in]	flags	- currently unused, must be zero.

Returns: hipSuccess, hipErrorInvalidValue, hipErrorNotSupported

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

◆ hipMemCreate()

hipError_t hipMemCreate	(	hipMemGenericAllocationHandle_t *	handle,
		size_t	size,
		const hipMemAllocationProp *	prop,
		unsigned long long	flags
	)

Creates a memory allocation described by the properties and size.

Parameters

[out]	handle	- value of the returned handle.
[in]	size	- size of the allocation.
[in]	prop	- properties of the allocation.
[in]	flags	- currently unused, must be zero.

Returns: hipSuccess, hipErrorInvalidValue, hipErrorNotSupported

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

◆ hipMemExportToShareableHandle()

hipError_t hipMemExportToShareableHandle	(	void *	shareableHandle,
		hipMemGenericAllocationHandle_t	handle,
		hipMemAllocationHandleType	handleType,
		unsigned long long	flags
	)

Exports an allocation to a requested shareable handle type.

Parameters

[out]	shareableHandle	- value of the returned handle.
[in]	handle	- handle to share.
[in]	handleType	- type of the shareable handle.
[in]	flags	- currently unused, must be zero.

Returns: hipSuccess, hipErrorInvalidValue, hipErrorNotSupported

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

◆ hipMemGetAccess()

hipError_t hipMemGetAccess	(	unsigned long long *	flags,
		const hipMemLocation *	location,
		void *	ptr
	)

Get the access flags set for the given location and ptr.

Parameters

[out]	flags	- flags for this location.
[in]	location	- target location.
[in]	ptr	- address to check the access flags.

Returns: hipSuccess, hipErrorInvalidValue, hipErrorNotSupported

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

◆ hipMemGetAllocationGranularity()

hipError_t hipMemGetAllocationGranularity	(	size_t *	granularity,
		const hipMemAllocationProp *	prop,
		hipMemAllocationGranularity_flags	option
	)

Calculates either the minimal or recommended granularity.

Parameters

[out]	granularity	- returned granularity.
[in]	prop	- location properties.
[in]	option	- determines which granularity to return.

Returns: hipSuccess, hipErrorInvalidValue, hipErrorNotSupported

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

◆ hipMemGetAllocationPropertiesFromHandle()

hipError_t hipMemGetAllocationPropertiesFromHandle	(	hipMemAllocationProp *	prop,
		hipMemGenericAllocationHandle_t	handle
	)

Retrieve the property structure of the given handle.

Parameters

[out]	prop	- properties of the given handle.
[in]	handle	- handle to perform the query on.

Returns: hipSuccess, hipErrorInvalidValue, hipErrorNotSupported

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

◆ hipMemImportFromShareableHandle()

hipError_t hipMemImportFromShareableHandle	(	hipMemGenericAllocationHandle_t *	handle,
		void *	osHandle,
		hipMemAllocationHandleType	shHandleType
	)

Imports an allocation from a requested shareable handle type.

Parameters

[out]	handle	- returned value.
[in]	osHandle	- shareable handle representing the memory allocation.
[in]	shHandleType	- handle type.

Returns: hipSuccess, hipErrorInvalidValue, hipErrorNotSupported

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

◆ hipMemMap()

hipError_t hipMemMap	(	void *	ptr,
		size_t	size,
		size_t	offset,
		hipMemGenericAllocationHandle_t	handle,
		unsigned long long	flags
	)

Maps an allocation handle to a reserved virtual address range.

Parameters

[in]	ptr	- address where the memory will be mapped.
[in]	size	- size of the mapping.
[in]	offset	- offset into the memory, currently must be zero.
[in]	handle	- memory allocation to be mapped.
[in]	flags	- currently unused, must be zero.

Returns: hipSuccess, hipErrorInvalidValue, hipErrorNotSupported

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

◆ hipMemMapArrayAsync()

hipError_t hipMemMapArrayAsync	(	hipArrayMapInfo *	mapInfoList,
		unsigned int	count,
		hipStream_t	stream
	)

Maps or unmaps subregions of sparse HIP arrays and sparse HIP mipmapped arrays.

Parameters

[in]	mapInfoList	- list of hipArrayMapInfo.
[in]	count	- number of hipArrayMapInfo in mapInfoList.
[in]	stream	- stream identifier for the stream to use for map or unmap operations.

Returns: hipSuccess, hipErrorInvalidValue, hipErrorNotSupported

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

◆ hipMemRelease()

hipError_t hipMemRelease ( hipMemGenericAllocationHandle_t handle )

Release a memory handle representing a memory allocation which was previously allocated through hipMemCreate.

Parameters

[in] handle - handle of the memory allocation.

Returns: hipSuccess, hipErrorInvalidValue, hipErrorNotSupported

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

◆ hipMemRetainAllocationHandle()

hipError_t hipMemRetainAllocationHandle	(	hipMemGenericAllocationHandle_t *	handle,
		void *	addr
	)

Returns the allocation handle of the backing memory allocation given the address.

Parameters

[out]	handle	- handle representing addr.
[in]	addr	- address to look up.

Returns: hipSuccess, hipErrorInvalidValue, hipErrorNotSupported

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

◆ hipMemSetAccess()

hipError_t hipMemSetAccess	(	void *	ptr,
		size_t	size,
		const hipMemAccessDesc *	desc,
		size_t	count
	)

Set the access flags for each location specified in desc for the given virtual address range.

Parameters

[in]	ptr	- starting address of the virtual address range.
[in]	size	- size of the range.
[in]	desc	- array of hipMemAccessDesc.
[in]	count	- number of hipMemAccessDesc in desc.

Returns: hipSuccess, hipErrorInvalidValue, hipErrorNotSupported

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

◆ hipMemUnmap()

hipError_t hipMemUnmap	(	void *	ptr,
		size_t	size
	)

Unmap memory allocation of a given address range.

Parameters

[in]	ptr	- starting address of the range to unmap.
[in]	size	- size of the virtual address range.

Returns: hipSuccess, hipErrorInvalidValue, hipErrorNotSupported

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

Memory Management

Memory Management#

Functions

Detailed Description

Function Documentation

◆ hipMemAddressFree()

◆ hipMemAddressReserve()

◆ hipMemCreate()

◆ hipMemExportToShareableHandle()

◆ hipMemGetAccess()

◆ hipMemGetAllocationGranularity()

◆ hipMemGetAllocationPropertiesFromHandle()

◆ hipMemImportFromShareableHandle()

◆ hipMemMap()

◆ hipMemMapArrayAsync()

◆ hipMemRelease()

◆ hipMemRetainAllocationHandle()

◆ hipMemSetAccess()

◆ hipMemUnmap()