Managed Memory

Managed Memory#

HIP Runtime API Reference: Managed Memory
Functions
Managed Memory
HIP API » Memory Management
Collaboration diagram for Managed Memory:

Functions

hipError_t hipMallocManaged (void **dev_ptr, size_t size, unsigned int flags)
 Allocates memory that will be automatically managed by HIP.
 
hipError_t hipMemPrefetchAsync (const void *dev_ptr, size_t count, int device, hipStream_t stream)
 Prefetches memory to the specified destination device using HIP.
 
hipError_t hipMemAdvise (const void *dev_ptr, size_t count, hipMemoryAdvise advice, int device)
 Advise about the usage of a given memory range to HIP.
 
hipError_t hipMemRangeGetAttribute (void *data, size_t data_size, hipMemRangeAttribute attribute, const void *dev_ptr, size_t count)
 Query an attribute of a given memory range in HIP.
 
hipError_t hipMemRangeGetAttributes (void **data, size_t *data_sizes, hipMemRangeAttribute *attributes, size_t num_attributes, const void *dev_ptr, size_t count)
 Query attributes of a given memory range in HIP.
 
hipError_t hipStreamAttachMemAsync (hipStream_t stream, void *dev_ptr, size_t length, unsigned int flags)
 Attach memory to a stream asynchronously in HIP.
 

Detailed Description

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

Note
The managed memory management APIs are implemented on Linux, under developement on Windows.

Function Documentation

◆ hipMallocManaged()

hipError_t hipMallocManaged ( void **  dev_ptr,
size_t  size,
unsigned int  flags 
)

Allocates memory that will be automatically managed by HIP.

This API is used for managed memory, allows data be shared and accessible to both CPU and GPU using a single pointer.

The API returns the allocation pointer, managed by HMM, can be used further to execute kernels on device and fetch data between the host and device as needed.

Note
It is recommend to do the capability check before call this API.
Parameters
[out]dev_ptr- pointer to allocated device memory
[in]size- requested allocation size in bytes, it should be granularity of 4KB
[in]flags- must be either hipMemAttachGlobal or hipMemAttachHost (defaults to hipMemAttachGlobal)
Returns
hipSuccess, hipErrorMemoryAllocation, hipErrorNotSupported, hipErrorInvalidValue

◆ hipMemAdvise()

hipError_t hipMemAdvise ( const void *  dev_ptr,
size_t  count,
hipMemoryAdvise  advice,
int  device 
)

Advise about the usage of a given memory range to HIP.

Parameters
[in]dev_ptrpointer to memory to set the advice for
[in]countsize in bytes of the memory range, it should be CPU page size alligned.
[in]adviceadvice to be applied for the specified memory range
[in]devicedevice to apply the advice for
Returns
hipSuccess, hipErrorInvalidValue

This HIP API advises about the usage to be applied on unified memory allocation in the range starting from the pointer address devPtr, with the size of count bytes. The memory range must refer to managed memory allocated via the API hipMallocManaged, and the range will be handled with proper round down and round up respectively in the driver to be aligned to CPU page size, the same way as corresponding CUDA API behaves in CUDA version 8.0 and afterwards.

Note
This API is implemented on Linux and is under development on Microsoft Windows.

◆ hipMemPrefetchAsync()

hipError_t hipMemPrefetchAsync ( const void *  dev_ptr,
size_t  count,
int  device,
hipStream_t  stream 
)

Prefetches memory to the specified destination device using HIP.

Parameters
[in]dev_ptrpointer to be prefetched
[in]countsize in bytes for prefetching
[in]devicedestination device to prefetch to
[in]streamstream to enqueue prefetch operation
Returns
hipSuccess, hipErrorInvalidValue
Note
This API is implemented on Linux and is under development on Microsoft Windows.

◆ hipMemRangeGetAttribute()

hipError_t hipMemRangeGetAttribute ( void *  data,
size_t  data_size,
hipMemRangeAttribute  attribute,
const void *  dev_ptr,
size_t  count 
)

Query an attribute of a given memory range in HIP.

Parameters
[in,out]dataa pointer to a memory location where the result of each attribute query will be written to
[in]data_sizethe size of data
[in]attributethe attribute to query
[in]dev_ptrstart of the range to query
[in]countsize of the range to query
Returns
hipSuccess, hipErrorInvalidValue
Note
This API is implemented on Linux and is under development on Microsoft Windows.

◆ hipMemRangeGetAttributes()

hipError_t hipMemRangeGetAttributes ( void **  data,
size_t *  data_sizes,
hipMemRangeAttribute *  attributes,
size_t  num_attributes,
const void *  dev_ptr,
size_t  count 
)

Query attributes of a given memory range in HIP.

Parameters
[in,out]dataa two-dimensional array containing pointers to memory locations where the result of each attribute query will be written to
[in]data_sizesan array, containing the sizes of each result
[in]attributesthe attribute to query
[in]num_attributesan array of attributes to query (numAttributes and the number of attributes in this array should match)
[in]dev_ptrstart of the range to query
[in]countsize of the range to query
Returns
hipSuccess, hipErrorInvalidValue
Note
This API is implemented on Linux and is under development on Microsoft Windows.

◆ hipStreamAttachMemAsync()

hipError_t hipStreamAttachMemAsync ( hipStream_t  stream,
void *  dev_ptr,
size_t  length,
unsigned int  flags 
)

Attach memory to a stream asynchronously in HIP.

Parameters
[in]stream- stream in which to enqueue the attach operation
[in]dev_ptr- pointer to memory (must be a pointer to managed memory or to a valid host-accessible region of system-allocated memory)
[in]length- length of memory (defaults to zero)
[in]flags- must be one of hipMemAttachGlobal, hipMemAttachHost or hipMemAttachSingle (defaults to hipMemAttachSingle)
Returns
hipSuccess, hipErrorInvalidValue
Warning
This API is under development. Currently it is a no-operation (NOP) function on AMD GPUs and returns hipSuccess.