This page contains proposed changes for a future release of ROCm. Read the latest Linux release of ROCm documentation for your production environments.

Virtual Memory Management

Virtual Memory Management#

HIP Runtime API Reference: Virtual Memory Management
Virtual Memory Management
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.

Note
Please note, the virtual memory management functions of HIP runtime API are implemented on Linux, under development on Windows.

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.
Note
This API is implemented on Linux, under development on Windows.

◆ 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.
Note
This API is implemented on Linux, under development on Windows.

◆ 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.
Note
This API is implemented on Linux, under development on Windows.

◆ 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.
Note
This API is implemented on Linux, under development on Windows.

◆ 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.
Note
This API is implemented on Linux, under development on Windows.

◆ 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.
Note
This API is implemented on Linux, under development on Windows.

◆ 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.
Note
This API is implemented on Linux under development on Windows.

◆ 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.
Note
This API is implemented on Linux, under development on Windows.

◆ 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.
Note
This API is implemented on Linux, under development on Windows.

◆ 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.
Note
This API is implemented on Linux, under development on Windows.

◆ 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.
Note
This API is implemented on Linux, under development on Windows.

◆ 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.
Note
This API is implemented on Linux, under development on Windows.

◆ 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.
Note
This API is implemented on Linux, under development on Windows.

◆ 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.
Note
This API is implemented on Linux, under development on Windows.