Virtual Memory Management#

HIP Runtime API Reference: Virtual Memory Management
Virtual Memory Management

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

Collaboration diagram for Virtual 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.