Provided by: nvidia-cuda-dev_7.5.18-0ubuntu1_amd64 
NAME
Unified Addressing -
Functions
CUresult cuPointerGetAttribute (void *data, CUpointer_attribute attribute, CUdeviceptr ptr)
Returns information about a pointer.
CUresult cuPointerGetAttributes (unsigned int numAttributes, CUpointer_attribute *attributes, void
**data, CUdeviceptr ptr)
Returns information about a pointer.
CUresult cuPointerSetAttribute (const void *value, CUpointer_attribute attribute, CUdeviceptr ptr)
Set attributes on a previously allocated memory region.
Detailed Description
\brief unified addressing functions of the low-level CUDA driver API (cuda.h)
This section describes the unified addressing functions of the low-level CUDA driver application
programming interface.
Overview
CUDA devices can share a unified address space with the host. For these devices there is no distinction
between a device pointer and a host pointer -- the same pointer value may be used to access memory from
the host program and from a kernel running on the device (with exceptions enumerated below).
Supported Platforms
Whether or not a device supports unified addressing may be queried by calling cuDeviceGetAttribute() with
the device attribute CU_DEVICE_ATTRIBUTE_UNIFIED_ADDRESSING.
Unified addressing is automatically enabled in 64-bit processes on devices with compute capability
greater than or equal to 2.0.
Looking Up Information from Pointer Values
It is possible to look up information about the memory which backs a pointer value. For instance, one may
want to know if a pointer points to host or device memory. As another example, in the case of device
memory, one may want to know on which CUDA device the memory resides. These properties may be queried
using the function cuPointerGetAttribute()
Since pointers are unique, it is not necessary to specify information about the pointers specified to the
various copy functions in the CUDA API. The function cuMemcpy() may be used to perform a copy between two
pointers, ignoring whether they point to host or device memory (making cuMemcpyHtoD(), cuMemcpyDtoD(),
and cuMemcpyDtoH() unnecessary for devices supporting unified addressing). For multidimensional copies,
the memory type CU_MEMORYTYPE_UNIFIED may be used to specify that the CUDA driver should infer the
location of the pointer from its value.
Automatic Mapping of Host Allocated Host Memory
All host memory allocated in all contexts using cuMemAllocHost() and cuMemHostAlloc() is always directly
accessible from all contexts on all devices that support unified addressing. This is the case regardless
of whether or not the flags CU_MEMHOSTALLOC_PORTABLE and CU_MEMHOSTALLOC_DEVICEMAP are specified.
The pointer value through which allocated host memory may be accessed in kernels on all devices that
support unified addressing is the same as the pointer value through which that memory is accessed on the
host, so it is not necessary to call cuMemHostGetDevicePointer() to get the device pointer for these
allocations.
Note that this is not the case for memory allocated using the flag CU_MEMHOSTALLOC_WRITECOMBINED, as
discussed below.
Automatic Registration of Peer Memory
Upon enabling direct access from a context that supports unified addressing to another peer context that
supports unified addressing using cuCtxEnablePeerAccess() all memory allocated in the peer context using
cuMemAlloc() and cuMemAllocPitch() will immediately be accessible by the current context. The device
pointer value through which any peer memory may be accessed in the current context is the same pointer
value through which that memory may be accessed in the peer context.
Exceptions, Disjoint Addressing
Not all memory may be accessed on devices through the same pointer value through which they are accessed
on the host. These exceptions are host memory registered using cuMemHostRegister() and host memory
allocated using the flag CU_MEMHOSTALLOC_WRITECOMBINED. For these exceptions, there exists a distinct
host and device address for the memory. The device address is guaranteed to not overlap any valid host
pointer range and is guaranteed to have the same value across all contexts that support unified
addressing.
This device address may be queried using cuMemHostGetDevicePointer() when a context using unified
addressing is current. Either the host or the unified device pointer value may be used to refer to this
memory through cuMemcpy() and similar functions using the CU_MEMORYTYPE_UNIFIED memory type.
Function Documentation
CUresult cuPointerGetAttribute (void * data, CUpointer_attribute attribute, CUdeviceptr ptr)
The supported attributes are:
• CU_POINTER_ATTRIBUTE_CONTEXT:
Returns in *data the CUcontext in which ptr was allocated or registered. The type of data must be
CUcontext *.
If ptr was not allocated by, mapped by, or registered with a CUcontext which uses unified virtual
addressing then CUDA_ERROR_INVALID_VALUE is returned.
• CU_POINTER_ATTRIBUTE_MEMORY_TYPE:
Returns in *data the physical memory type of the memory that ptr addresses as a CUmemorytype enumerated
value. The type of data must be unsigned int.
If ptr addresses device memory then *data is set to CU_MEMORYTYPE_DEVICE. The particular CUdevice on
which the memory resides is the CUdevice of the CUcontext returned by the CU_POINTER_ATTRIBUTE_CONTEXT
attribute of ptr.
If ptr addresses host memory then *data is set to CU_MEMORYTYPE_HOST.
If ptr was not allocated by, mapped by, or registered with a CUcontext which uses unified virtual
addressing then CUDA_ERROR_INVALID_VALUE is returned.
If the current CUcontext does not support unified virtual addressing then CUDA_ERROR_INVALID_CONTEXT is
returned.
• CU_POINTER_ATTRIBUTE_DEVICE_POINTER:
Returns in *data the device pointer value through which ptr may be accessed by kernels running in the
current CUcontext. The type of data must be CUdeviceptr *.
If there exists no device pointer value through which kernels running in the current CUcontext may access
ptr then CUDA_ERROR_INVALID_VALUE is returned.
If there is no current CUcontext then CUDA_ERROR_INVALID_CONTEXT is returned.
Except in the exceptional disjoint addressing cases discussed below, the value returned in *data will
equal the input value ptr.
• CU_POINTER_ATTRIBUTE_HOST_POINTER:
Returns in *data the host pointer value through which ptr may be accessed by by the host program. The
type of data must be void **. If there exists no host pointer value through which the host program may
directly access ptr then CUDA_ERROR_INVALID_VALUE is returned.
Except in the exceptional disjoint addressing cases discussed below, the value returned in *data will
equal the input value ptr.
• CU_POINTER_ATTRIBUTE_P2P_TOKENS:
Returns in *data two tokens for use with the nv-p2p.h Linux kernel interface. data must be a struct of
type CUDA_POINTER_ATTRIBUTE_P2P_TOKENS.
ptr must be a pointer to memory obtained from :cuMemAlloc(). Note that p2pToken and vaSpaceToken are only
valid for the lifetime of the source allocation. A subsequent allocation at the same address may return
completely different tokens. Querying this attribute has a side effect of setting the attribute
CU_POINTER_ATTRIBUTE_SYNC_MEMOPS for the region of memory that ptr points to.
• CU_POINTER_ATTRIBUTE_SYNC_MEMOPS:
A boolean attribute which when set, ensures that synchronous memory operations initiated on the region of
memory that ptr points to will always synchronize. See further documentation in the section titled 'API
synchronization behavior' to learn more about cases when synchronous memory operations can exhibit
asynchronous behavior.
• CU_POINTER_ATTRIBUTE_BUFFER_ID:
Returns in *data a buffer ID which is guaranteed to be unique within the process. data must point to an
unsigned long long.
ptr must be a pointer to memory obtained from a CUDA memory allocation API. Every memory allocation from
any of the CUDA memory allocation APIs will have a unique ID over a process lifetime. Subsequent
allocations do not reuse IDs from previous freed allocations. IDs are only unique within a single
process.
• CU_POINTER_ATTRIBUTE_IS_MANAGED:
Returns in *data a boolean that indicates whether the pointer points to managed memory or not.
.RS 4
Note that for most allocations in the unified virtual address space the host and device pointer for
accessing the allocation will be the same. The exceptions to this are
• user memory registered using cuMemHostRegister
• host memory allocated using cuMemHostAlloc with the CU_MEMHOSTALLOC_WRITECOMBINED flag For these types
of allocation there will exist separate, disjoint host and device addresses for accessing the
allocation. In particular
• The host address will correspond to an invalid unmapped device address (which will result in an
exception if accessed from the device)
• The device address will correspond to an invalid unmapped host address (which will result in an
exception if accessed from the host). For these types of allocations, querying
CU_POINTER_ATTRIBUTE_HOST_POINTER and CU_POINTER_ATTRIBUTE_DEVICE_POINTER may be used to retrieve the
host and device addresses from either address.
Parameters:
data - Returned pointer attribute value
attribute - Pointer attribute to query
ptr - Pointer
Returns:
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED, CUDA_ERROR_INVALID_CONTEXT,
CUDA_ERROR_INVALID_VALUE, CUDA_ERROR_INVALID_DEVICE
Note:
Note that this function may also return error codes from previous, asynchronous launches.
See also:
cuPointerSetAttribute, cuMemAlloc, cuMemFree, cuMemAllocHost, cuMemFreeHost, cuMemHostAlloc,
cuMemHostRegister, cuMemHostUnregister
CUresult cuPointerGetAttributes (unsigned int numAttributes, CUpointer_attribute * attributes, void ** data,
CUdeviceptr ptr)
The supported attributes are (refer to cuPointerGetAttribute for attribute descriptions and
restrictions):
• CU_POINTER_ATTRIBUTE_CONTEXT
• CU_POINTER_ATTRIBUTE_MEMORY_TYPE
• CU_POINTER_ATTRIBUTE_DEVICE_POINTER
• CU_POINTER_ATTRIBUTE_HOST_POINTER
• CU_POINTER_ATTRIBUTE_SYNC_MEMOPS
• CU_POINTER_ATTRIBUTE_BUFFER_ID
• CU_POINTER_ATTRIBUTE_IS_MANAGED
Parameters:
numAttributes - Number of attributes to query
attributes - An array of attributes to query (numAttributes and the number of attributes in this
array should match)
data - A two-dimensional array containing pointers to memory locations where the result of each
attribute query will be written to.
ptr - Pointer to query
Unlike cuPointerGetAttribute, this function will not return an error when the ptr encountered is not a
valid CUDA pointer. Instead, the attributes are assigned default NULL values and CUDA_SUCCESS is
returned.
If ptr was not allocated by, mapped by, or registered with a CUcontext which uses UVA (Unified Virtual
Addressing), CUDA_ERROR_INVALID_CONTEXT is returned.
Returns:
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_VALUE,
CUDA_ERROR_INVALID_DEVICE
Note:
Note that this function may also return error codes from previous, asynchronous launches.
See also:
cuPointerGetAttribute, cuPointerSetAttribute
CUresult cuPointerSetAttribute (const void * value, CUpointer_attribute attribute, CUdeviceptr ptr)
The supported attributes are:
• CU_POINTER_ATTRIBUTE_SYNC_MEMOPS:
A boolean attribute that can either be set (1) or unset (0). When set, the region of memory that ptr
points to is guaranteed to always synchronize memory operations that are synchronous. If there are some
previously initiated synchronous memory operations that are pending when this attribute is set, the
function does not return until those memory operations are complete. See further documentation in the
section titled 'API synchronization behavior' to learn more about cases when synchronous memory
operations can exhibit asynchronous behavior. value will be considered as a pointer to an unsigned
integer to which this attribute is to be set.
Parameters:
value - Pointer to memory containing the value to be set
attribute - Pointer attribute to set
ptr - Pointer to a memory region allocated using CUDA memory allocation APIs
Returns:
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED, CUDA_ERROR_INVALID_CONTEXT,
CUDA_ERROR_INVALID_VALUE, CUDA_ERROR_INVALID_DEVICE
Note:
Note that this function may also return error codes from previous, asynchronous launches.
See also:
cuPointerGetAttribute, cuPointerGetAttributes, cuMemAlloc, cuMemFree, cuMemAllocHost, cuMemFreeHost,
cuMemHostAlloc, cuMemHostRegister, cuMemHostUnregister
Author
Generated automatically by Doxygen from the source code.
Version 6.0 15 Aug 2015 Unified Addressing(3)