CUDA Driver API. API Reference Manual (January 2024)

Modules

This function may be called on 1D and 2D arrays, in which case the Height and/or Depth members

of the descriptor struct will be set to 0.

Note:

Note that this function may also return error codes from previous, asynchronous launches.

See also:

cuArray3DCreate, cuArrayCreate, cuArrayDestroy, cuArrayGetDescriptor, cuMemAlloc,

cuMemAllocHost, cuMemAllocPitch, cuMemcpy2D, cuMemcpy2DAsync, cuMemcpy2DUnaligned,

cuMemcpy3D, cuMemcpy3DAsync, cuMemcpyAtoA, cuMemcpyAtoD, cuMemcpyAtoH,

cuMemcpyAtoHAsync, cuMemcpyDtoA, cuMemcpyDtoD, cuMemcpyDtoDAsync,

cuMemcpyDtoH, cuMemcpyDtoHAsync, cuMemcpyHtoA, cuMemcpyHtoAAsync, cuMemcpyHtoD,

cuMemcpyHtoDAsync, cuMemFree, cuMemFreeHost, cuMemGetAddressRange, cuMemGetInfo,

cuMemHostAlloc, cuMemHostGetDevicePointer, cuMemsetD2D8, cuMemsetD2D16,

cuMemsetD2D32, cuMemsetD8, cuMemsetD16, cuMemsetD32, cudaArrayGetInfo

CUresult cuArrayCreate (CUarray *pHandle, const

CUDA_ARRAY_DESCRIPTOR *pAllocateArray)

Creates a 1D or 2D CUDA array.

Parameters

pHandle

- Returned array

pAllocateArray

- Array descriptor

Returns

CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,

CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_VALUE,

CUDA_ERROR_OUT_OF_MEMORY, CUDA_ERROR_UNKNOWN

Description

Creates a CUDA array according to the CUDA_ARRAY_DESCRIPTOR structure

pAllocateArray and returns a handle to the new CUDA array in *pHandle. The

CUDA_ARRAY_DESCRIPTOR is defined as:

‎

typedef struct {

unsigned int Width;

unsigned int Height;

CUarray_format Format;

unsigned int NumChannels;

} CUDA_ARRAY_DESCRIPTOR;

187

Modules

where:

‣ Width, and Height are the width, and height of the CUDA array (in elements); the CUDA array

is one-dimensional if height is 0, two-dimensional otherwise;

‣ Format specifies the format of the elements; CUarray_format is defined as:

‎

typedef enum CUarray_format_enum {

CU_AD_FORMAT_UNSIGNED_INT8 = 0x01,

CU_AD_FORMAT_UNSIGNED_INT16 = 0x02,

CU_AD_FORMAT_UNSIGNED_INT32 = 0x03,

CU_AD_FORMAT_SIGNED_INT8 = 0x08,

CU_AD_FORMAT_SIGNED_INT16 = 0x09,

CU_AD_FORMAT_SIGNED_INT32 = 0x0a,

CU_AD_FORMAT_HALF = 0x10,

CU_AD_FORMAT_FLOAT = 0x20,

CU_AD_FORMAT_NV12 = 0xb0,

CU_AD_FORMAT_UNORM_INT8X1 = 0xc0,

CU_AD_FORMAT_UNORM_INT8X2 = 0xc1,

CU_AD_FORMAT_UNORM_INT8X4 = 0xc2,

CU_AD_FORMAT_UNORM_INT16X1 = 0xc3,

CU_AD_FORMAT_UNORM_INT16X2 = 0xc4,

CU_AD_FORMAT_UNORM_INT16X4 = 0xc5,

CU_AD_FORMAT_SNORM_INT8X1 = 0xc6,

CU_AD_FORMAT_SNORM_INT8X2 = 0xc7,

CU_AD_FORMAT_SNORM_INT8X4 = 0xc8,

CU_AD_FORMAT_SNORM_INT16X1 = 0xc9,

CU_AD_FORMAT_SNORM_INT16X2 = 0xca,

CU_AD_FORMAT_SNORM_INT16X4 = 0xcb,

CU_AD_FORMAT_BC1_UNORM = 0x91,

CU_AD_FORMAT_BC1_UNORM_SRGB = 0x92,

CU_AD_FORMAT_BC2_UNORM = 0x93,

CU_AD_FORMAT_BC2_UNORM_SRGB = 0x94,

CU_AD_FORMAT_BC3_UNORM = 0x95,

CU_AD_FORMAT_BC3_UNORM_SRGB = 0x96,

CU_AD_FORMAT_BC4_UNORM = 0x97,

CU_AD_FORMAT_BC4_SNORM = 0x98,

CU_AD_FORMAT_BC5_UNORM = 0x99,

CU_AD_FORMAT_BC5_SNORM = 0x9a,

CU_AD_FORMAT_BC6H_UF16 = 0x9b,

CU_AD_FORMAT_BC6H_SF16 = 0x9c,

CU_AD_FORMAT_BC7_UNORM = 0x9d,

CU_AD_FORMAT_BC7_UNORM_SRGB = 0x9e,

CU_AD_FORMAT_P010 = 0x9f,

CU_AD_FORMAT_P016 = 0xa1,

CU_AD_FORMAT_NV16 = 0xa2,

CU_AD_FORMAT_P210 = 0xa3,

CU_AD_FORMAT_P216 = 0xa4,

CU_AD_FORMAT_YUY2 = 0xa5,

CU_AD_FORMAT_Y210 = 0xa6,

CU_AD_FORMAT_Y216 = 0xa7,

CU_AD_FORMAT_AYUV = 0xa8,

CU_AD_FORMAT_Y410 = 0xa9,

CU_AD_FORMAT_Y416 = 0xb1,

CU_AD_FORMAT_Y444_PLANAR8 = 0xb2,

CU_AD_FORMAT_Y444_PLANAR10 = 0xb3,

CU_AD_FORMAT_YUV444_8bit_SemiPlanar = 0xb4,

CU_AD_FORMAT_YUV444_16bit_SemiPlanar = 0xb5,

CU_AD_FORMAT_UNORM_INT_101010_2 = 0x50,

} CUarray_format;

‣ NumChannels specifies the number of packed components per CUDA array element; it may be

1, 2, or 4;

Here are examples of CUDA array descriptions:

188

Modules

Description for a CUDA array of 2048 floats:

‎

CUDA_ARRAY_DESCRIPTOR desc;

desc.Format = CU_AD_FORMAT_FLOAT;

desc.NumChannels = 1;

desc.Width = 2048;

desc.Height = 1;

Description for a 64 x 64 CUDA array of floats:

‎

CUDA_ARRAY_DESCRIPTOR desc;

desc.Format = CU_AD_FORMAT_FLOAT;

desc.NumChannels = 1;

desc.Width = 64;

desc.Height = 64;

Description for a width x height CUDA array of 64-bit, 4x16-bit float16's:

‎

CUDA_ARRAY_DESCRIPTOR desc;

desc.Format = CU_AD_FORMAT_HALF;

desc.NumChannels = 4;

desc.Width = width;

desc.Height = height;

Description for a width x height CUDA array of 16-bit elements, each of which is two 8-bit

unsigned chars:

‎

CUDA_ARRAY_DESCRIPTOR arrayDesc;

desc.Format = CU_AD_FORMAT_UNSIGNED_INT8;

desc.NumChannels = 2;

desc.Width = width;

desc.Height = height;

Note:

Note that this function may also return error codes from previous, asynchronous launches.

See also:

cuArray3DCreate, cuArray3DGetDescriptor, cuArrayDestroy, cuArrayGetDescriptor,

cuMemAlloc, cuMemAllocHost, cuMemAllocPitch, cuMemcpy2D, cuMemcpy2DAsync,

cuMemcpy2DUnaligned, cuMemcpy3D, cuMemcpy3DAsync, cuMemcpyAtoA, cuMemcpyAtoD,

cuMemcpyAtoH, cuMemcpyAtoHAsync, cuMemcpyDtoA, cuMemcpyDtoD, cuMemcpyDtoDAsync,

cuMemcpyDtoH, cuMemcpyDtoHAsync, cuMemcpyHtoA, cuMemcpyHtoAAsync, cuMemcpyHtoD,

cuMemcpyHtoDAsync, cuMemFree, cuMemFreeHost, cuMemGetAddressRange, cuMemGetInfo,

cuMemHostAlloc, cuMemHostGetDevicePointer, cuMemsetD2D8, cuMemsetD2D16,

cuMemsetD2D32, cuMemsetD8, cuMemsetD16, cuMemsetD32, cudaMallocArray

CUresult cuArrayDestroy (CUarray hArray)

Destroys a CUDA array.

Parameters

hArray

- Array to destroy

189

Modules

Returns

CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,

CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_HANDLE,

CUDA_ERROR_ARRAY_IS_MAPPED, CUDA_ERROR_CONTEXT_IS_DESTROYED

Description

Destroys the CUDA array hArray.

Note:

Note that this function may also return error codes from previous, asynchronous launches.

See also:

cuArray3DCreate, cuArray3DGetDescriptor, cuArrayCreate, cuArrayGetDescriptor,

cuMemAlloc, cuMemAllocHost, cuMemAllocPitch, cuMemcpy2D, cuMemcpy2DAsync,

cuMemcpy2DUnaligned, cuMemcpy3D, cuMemcpy3DAsync, cuMemcpyAtoA, cuMemcpyAtoD,

cuMemcpyAtoH, cuMemcpyAtoHAsync, cuMemcpyDtoA, cuMemcpyDtoD, cuMemcpyDtoDAsync,

cuMemcpyDtoH, cuMemcpyDtoHAsync, cuMemcpyHtoA, cuMemcpyHtoAAsync, cuMemcpyHtoD,

cuMemcpyHtoDAsync, cuMemFree, cuMemFreeHost, cuMemGetAddressRange, cuMemGetInfo,

cuMemHostAlloc, cuMemHostGetDevicePointer, cuMemsetD2D8, cuMemsetD2D16,

cuMemsetD2D32, cuMemsetD8, cuMemsetD16, cuMemsetD32, cudaFreeArray

CUresult cuArrayGetDescriptor

(CUDA_ARRAY_DESCRIPTOR *pArrayDescriptor,

CUarray hArray)

Get a 1D or 2D CUDA array descriptor.

Parameters

pArrayDescriptor

- Returned array descriptor

hArray

- Array to get descriptor of

Returns

CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,

CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_VALUE,

CUDA_ERROR_INVALID_HANDLE

190

Modules

Description

Returns in *pArrayDescriptor a descriptor containing information on the format and dimensions

of the CUDA array hArray. It is useful for subroutines that have been passed a CUDA array, but need

to know the CUDA array parameters for validation or other purposes.

Note:

Note that this function may also return error codes from previous, asynchronous launches.

See also:

cuArray3DCreate, cuArray3DGetDescriptor, cuArrayCreate, cuArrayDestroy, cuMemAlloc,

cuMemAllocHost, cuMemAllocPitch, cuMemcpy2D, cuMemcpy2DAsync, cuMemcpy2DUnaligned,

cuMemcpy3D, cuMemcpy3DAsync, cuMemcpyAtoA, cuMemcpyAtoD, cuMemcpyAtoH,

cuMemcpyAtoHAsync, cuMemcpyDtoA, cuMemcpyDtoD, cuMemcpyDtoDAsync,

cuMemcpyDtoH, cuMemcpyDtoHAsync, cuMemcpyHtoA, cuMemcpyHtoAAsync, cuMemcpyHtoD,

cuMemcpyHtoDAsync, cuMemFree, cuMemFreeHost, cuMemGetAddressRange, cuMemGetInfo,

cuMemHostAlloc, cuMemHostGetDevicePointer, cuMemsetD2D8, cuMemsetD2D16,

cuMemsetD2D32, cuMemsetD8, cuMemsetD16, cuMemsetD32, cudaArrayGetInfo

CUresult cuArrayGetMemoryRequirements

(CUDA_ARRAY_MEMORY_REQUIREMENTS

*memoryRequirements, CUarray array, CUdevice device)

Returns the memory requirements of a CUDA array.

Parameters

memoryRequirements

- Pointer to CUDA_ARRAY_MEMORY_REQUIREMENTS

array

- CUDA array to get the memory requirements of

device

- Device to get the memory requirements for

Returns

CUDA_SUCCESS CUDA_ERROR_INVALID_VALUE

191

Modules

Description

Returns the memory requirements of a CUDA array in memoryRequirements If the

CUDA array is not allocated with flag CUDA_ARRAY3D_DEFERRED_MAPPING

CUDA_ERROR_INVALID_VALUE will be returned.

The returned value in CUDA_ARRAY_MEMORY_REQUIREMENTS::size

represents the total size of the CUDA array. The returned value in

CUDA_ARRAY_MEMORY_REQUIREMENTS::alignment represents the alignment necessary for

mapping the CUDA array.

See also:

cuMipmappedArrayGetMemoryRequirements, cuMemMapArrayAsync

CUresult cuArrayGetPlane (CUarray *pPlaneArray,

CUarray hArray, unsigned int planeIdx)

Gets a CUDA array plane from a CUDA array.

Parameters

pPlaneArray

- Returned CUDA array referenced by the planeIdx

hArray

- Multiplanar CUDA array

planeIdx

- Plane index

Returns

CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,

CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_VALUE,

CUDA_ERROR_INVALID_HANDLE

Description

Returns in pPlaneArray a CUDA array that represents a single format plane of the CUDA array

hArray.

If planeIdx is greater than the maximum number of planes in this array or if the array does not have

a multi-planar format e.g: CU_AD_FORMAT_NV12, then CUDA_ERROR_INVALID_VALUE is

returned.

Note that if the hArray has format CU_AD_FORMAT_NV12, then passing in 0 for

planeIdx returns a CUDA array of the same size as hArray but with one channel and

CU_AD_FORMAT_UNSIGNED_INT8 as its format. If 1 is passed for planeIdx, then

192

Modules

the returned CUDA array has half the height and width of hArray with two channels and

CU_AD_FORMAT_UNSIGNED_INT8 as its format.

Note:

Note that this function may also return error codes from previous, asynchronous launches.

See also:

cuArrayCreate, cudaArrayGetPlane

CUresult cuArrayGetSparseProperties

(CUDA_ARRAY_SPARSE_PROPERTIES

*sparseProperties, CUarray array)

Returns the layout properties of a sparse CUDA array.

Parameters

sparseProperties

- Pointer to CUDA_ARRAY_SPARSE_PROPERTIES

array

- CUDA array to get the sparse properties of

Returns

CUDA_SUCCESS CUDA_ERROR_INVALID_VALUE

Description

Returns the layout properties of a sparse CUDA array in sparseProperties If the CUDA array

is not allocated with flag CUDA_ARRAY3D_SPARSE CUDA_ERROR_INVALID_VALUE will be

returned.

If the returned value in CUDA_ARRAY_SPARSE_PROPERTIES::flags

contains CU_ARRAY_SPARSE_PROPERTIES_SINGLE_MIPTAIL,

then CUDA_ARRAY_SPARSE_PROPERTIES::miptailSize represents the

total size of the array. Otherwise, it will be zero. Also, the returned value in

CUDA_ARRAY_SPARSE_PROPERTIES::miptailFirstLevel is always zero. Note that the array

must have been allocated using cuArrayCreate or cuArray3DCreate. For CUDA arrays obtained

using cuMipmappedArrayGetLevel, CUDA_ERROR_INVALID_VALUE will be returned. Instead,

cuMipmappedArrayGetSparseProperties must be used to obtain the sparse properties of the entire

CUDA mipmapped array to which array belongs to.

See also:

193

Modules

cuMipmappedArrayGetSparseProperties, cuMemMapArrayAsync

CUresult cuDeviceGetByPCIBusId (CUdevice *dev, const

char *pciBusId)

Returns a handle to a compute device.

Parameters

dev

- Returned device handle

pciBusId

- String in one of the following forms: [domain]:[bus]:[device].[function] [domain]:[bus]:[device]

[bus]:[device].[function] where domain, bus, device, and function are all hexadecimal

values

Returns

CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,

CUDA_ERROR_INVALID_VALUE, CUDA_ERROR_INVALID_DEVICE

Description

Returns in *device a device handle given a PCI bus ID string.

Note:

Note that this function may also return error codes from previous, asynchronous launches.

See also:

cuDeviceGet, cuDeviceGetAttribute, cuDeviceGetPCIBusId, cudaDeviceGetByPCIBusId

CUresult cuDeviceGetPCIBusId (char *pciBusId, int len,

CUdevice dev)

Returns a PCI Bus Id string for the device.

Parameters

pciBusId

- Returned identifier string for the device in the following format [domain]:[bus]:[device].[function]

where domain, bus, device, and function are all hexadecimal values. pciBusId should be

large enough to store 13 characters including the NULL-terminator.

len

- Maximum length of string to store in name

194

Modules

dev

- Device to get identifier string for

Returns

CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,

CUDA_ERROR_INVALID_VALUE, CUDA_ERROR_INVALID_DEVICE

Description

Returns an ASCII string identifying the device dev in the NULL-terminated string pointed to by

pciBusId. len specifies the maximum length of the string that may be returned.

Note:

Note that this function may also return error codes from previous, asynchronous launches.

See also:

cuDeviceGet, cuDeviceGetAttribute, cuDeviceGetByPCIBusId, cudaDeviceGetPCIBusId

CUresult cuDeviceRegisterAsyncNotification (CUdevice

device, CUasyncCallback callbackFunc, void *userData,

CUasyncCallbackHandle *callback)

Registers a callback function to receive async notifications.

Parameters

device

- The device on which to register the callback

callbackFunc

- The function to register as a callback

userData

- A generic pointer to user data. This is passed into the callback function.

callback

- A handle representing the registered callback instance

Returns

CUDA_SUCCESS, CUDA_ERROR_NOT_SUPPORTED, CUDA_ERROR_INVALID_DEVICE,

CUDA_ERROR_INVALID_VALUE, CUDA_ERROR_NOT_PERMITTED,

CUDA_ERROR_UNKNOWN

195

Modules

Description

Registers callbackFunc to receive async notifications.

The userData parameter is passed to the callback function at async notification time. Likewise,

callback is also passed to the callback function to distinguish between multiple registered callbacks.

The callback function being registered should be designed to return quickly (~10ms). Any long running

tasks should be queued for execution on an application thread.

Callbacks may not call cuDeviceRegisterAsyncNotification or cuDeviceUnregisterAsyncNotification.

Doing so will result in CUDA_ERROR_NOT_PERMITTED. Async notification callbacks execute in

an undefined order and may be serialized.

Returns in *callback a handle representing the registered callback instance.

Note:

Note that this function may also return error codes from previous, asynchronous launches.

See also:

cuDeviceUnregisterAsyncNotification

CUresult cuDeviceUnregisterAsyncNotification (CUdevice

device, CUasyncCallbackHandle callback)

Unregisters an async notification callback.

Parameters

device

- The device from which to remove callback.

callback

- The callback instance to unregister from receiving async notifications.

Returns

CUDA_SUCCESS, CUDA_ERROR_NOT_SUPPORTED, CUDA_ERROR_INVALID_DEVICE,

CUDA_ERROR_INVALID_VALUE, CUDA_ERROR_NOT_PERMITTED,

CUDA_ERROR_UNKNOWN

Description

Unregisters callback so that the corresponding callback function will stop receiving async

notifications.

196

Modules

Note:

Note that this function may also return error codes from previous, asynchronous launches.

See also:

cuDeviceRegisterAsyncNotification

CUresult cuIpcCloseMemHandle (CUdeviceptr dptr)

Attempts to close memory mapped with cuIpcOpenMemHandle.

Parameters

dptr

- Device pointer returned by cuIpcOpenMemHandle

Returns

CUDA_SUCCESS, CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_MAP_FAILED,

CUDA_ERROR_INVALID_HANDLE, CUDA_ERROR_INVALID_VALUE

Description

Decrements the reference count of the memory returned by cuIpcOpenMemHandle by 1. When the

reference count reaches 0, this API unmaps the memory. The original allocation in the exporting

process as well as imported mappings in other processes will be unaffected.

Any resources used to enable peer access will be freed if this is the last mapping using them.

IPC functionality is restricted to devices with support for unified addressing on Linux and Windows

operating systems. IPC functionality on Windows is supported for compatibility purposes but not

recommended as it comes with performance cost. Users can test their device for IPC functionality by

calling cuapiDeviceGetAttribute with CU_DEVICE_ATTRIBUTE_IPC_EVENT_SUPPORTED

See also:

cuMemAlloc, cuMemFree, cuIpcGetEventHandle, cuIpcOpenEventHandle, cuIpcGetMemHandle,

cuIpcOpenMemHandle, cudaIpcCloseMemHandle

197

Modules

CUresult cuIpcGetEventHandle (CUipcEventHandle

*pHandle, CUevent event)

Gets an interprocess handle for a previously allocated event.

Parameters

pHandle

- Pointer to a user allocated CUipcEventHandle in which to return the opaque event handle

event

- Event allocated with CU_EVENT_INTERPROCESS and CU_EVENT_DISABLE_TIMING

flags.

Returns

CUDA_SUCCESS, CUDA_ERROR_INVALID_HANDLE, CUDA_ERROR_OUT_OF_MEMORY,

CUDA_ERROR_MAP_FAILED, CUDA_ERROR_INVALID_VALUE

Description

Takes as input a previously allocated event. This event must have been created with the

CU_EVENT_INTERPROCESS and CU_EVENT_DISABLE_TIMING flags set. This opaque

handle may be copied into other processes and opened with cuIpcOpenEventHandle to allow efficient

hardware synchronization between GPU work in different processes.

After the event has been opened in the importing process, cuEventRecord, cuEventSynchronize,

cuStreamWaitEvent and cuEventQuery may be used in either process. Performing operations on the

imported event after the exported event has been freed with cuEventDestroy will result in undefined

behavior.

IPC functionality is restricted to devices with support for unified addressing on Linux and Windows

operating systems. IPC functionality on Windows is supported for compatibility purposes but not

recommended as it comes with performance cost. Users can test their device for IPC functionality by

calling cuDeviceGetAttribute with CU_DEVICE_ATTRIBUTE_IPC_EVENT_SUPPORTED

See also:

cuEventCreate, cuEventDestroy, cuEventSynchronize, cuEventQuery, cuStreamWaitEvent,

cuIpcOpenEventHandle, cuIpcGetMemHandle, cuIpcOpenMemHandle, cuIpcCloseMemHandle,

cudaIpcGetEventHandle

198

Modules

CUresult cuIpcGetMemHandle (CUipcMemHandle

*pHandle, CUdeviceptr dptr)

Gets an interprocess memory handle for an existing device memory allocation.

Parameters

pHandle

- Pointer to user allocated CUipcMemHandle to return the handle in.

dptr

- Base pointer to previously allocated device memory

Returns

CUDA_SUCCESS, CUDA_ERROR_INVALID_HANDLE, CUDA_ERROR_INVALID_CONTEXT,

CUDA_ERROR_OUT_OF_MEMORY, CUDA_ERROR_MAP_FAILED,

CUDA_ERROR_INVALID_VALUE

Description

Takes a pointer to the base of an existing device memory allocation created with cuMemAlloc and

exports it for use in another process. This is a lightweight operation and may be called multiple times

on an allocation without adverse effects.

If a region of memory is freed with cuMemFree and a subsequent call to cuMemAlloc returns memory

with the same device address, cuIpcGetMemHandle will return a unique handle for the new memory.

IPC functionality is restricted to devices with support for unified addressing on Linux and Windows

operating systems. IPC functionality on Windows is supported for compatibility purposes but not

recommended as it comes with performance cost. Users can test their device for IPC functionality by

calling cuapiDeviceGetAttribute with CU_DEVICE_ATTRIBUTE_IPC_EVENT_SUPPORTED

See also:

cuMemAlloc, cuMemFree, cuIpcGetEventHandle, cuIpcOpenEventHandle, cuIpcOpenMemHandle,

cuIpcCloseMemHandle, cudaIpcGetMemHandle

CUresult cuIpcOpenEventHandle (CUevent *phEvent,

CUipcEventHandle handle)

Opens an interprocess event handle for use in the current process.

Parameters

phEvent

- Returns the imported event

199

Modules

handle

- Interprocess handle to open

Returns

CUDA_SUCCESS, CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_MAP_FAILED,

CUDA_ERROR_PEER_ACCESS_UNSUPPORTED, CUDA_ERROR_INVALID_HANDLE,

CUDA_ERROR_INVALID_VALUE

Description

Opens an interprocess event handle exported from another process with cuIpcGetEventHandle.

This function returns a CUevent that behaves like a locally created event with the

CU_EVENT_DISABLE_TIMING flag specified. This event must be freed with cuEventDestroy.

Performing operations on the imported event after the exported event has been freed with

cuEventDestroy will result in undefined behavior.

IPC functionality is restricted to devices with support for unified addressing on Linux and Windows

operating systems. IPC functionality on Windows is supported for compatibility purposes but not

recommended as it comes with performance cost. Users can test their device for IPC functionality by

calling cuapiDeviceGetAttribute with CU_DEVICE_ATTRIBUTE_IPC_EVENT_SUPPORTED

See also:

cuEventCreate, cuEventDestroy, cuEventSynchronize, cuEventQuery, cuStreamWaitEvent,

cuIpcGetEventHandle, cuIpcGetMemHandle, cuIpcOpenMemHandle, cuIpcCloseMemHandle,

cudaIpcOpenEventHandle

CUresult cuIpcOpenMemHandle (CUdeviceptr *pdptr,

CUipcMemHandle handle, unsigned int Flags)

Opens an interprocess memory handle exported from another process and returns a device pointer

usable in the local process.

Parameters

pdptr

- Returned device pointer

handle

- CUipcMemHandle to open

Flags

- Flags for this operation. Must be specified as CU_IPC_MEM_LAZY_ENABLE_PEER_ACCESS

200

Modules

Returns

CUDA_SUCCESS, CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_MAP_FAILED,

CUDA_ERROR_INVALID_HANDLE, CUDA_ERROR_TOO_MANY_PEERS,

CUDA_ERROR_INVALID_VALUE

Description

Maps memory exported from another process with cuIpcGetMemHandle into the current device

address space. For contexts on different devices cuIpcOpenMemHandle can attempt to enable peer

access between the devices as if the user called cuCtxEnablePeerAccess. This behavior is controlled by

the CU_IPC_MEM_LAZY_ENABLE_PEER_ACCESS flag. cuDeviceCanAccessPeer can determine

if a mapping is possible.

Contexts that may open CUipcMemHandles are restricted in the following way. CUipcMemHandles

from each CUdevice in a given process may only be opened by one CUcontext per CUdevice per other

process.

If the memory handle has already been opened by the current context, the reference count on the handle

is incremented by 1 and the existing device pointer is returned.

Memory returned from cuIpcOpenMemHandle must be freed with cuIpcCloseMemHandle.

Calling cuMemFree on an exported memory region before calling cuIpcCloseMemHandle in the

importing context will result in undefined behavior.

IPC functionality is restricted to devices with support for unified addressing on Linux and Windows

operating systems. IPC functionality on Windows is supported for compatibility purposes but not

recommended as it comes with performance cost. Users can test their device for IPC functionality by

calling cuapiDeviceGetAttribute with CU_DEVICE_ATTRIBUTE_IPC_EVENT_SUPPORTED

Note:

No guarantees are made about the address returned in *pdptr. In particular, multiple processes may

not receive the same address for the same handle.

See also:

cuMemAlloc, cuMemFree, cuIpcGetEventHandle, cuIpcOpenEventHandle, cuIpcGetMemHandle,

cuIpcCloseMemHandle, cuCtxEnablePeerAccess, cuDeviceCanAccessPeer, cudaIpcOpenMemHandle

201

Modules

CUresult cuMemAlloc (CUdeviceptr *dptr, size_t bytesize)

Allocates device memory.

Parameters

dptr

- Returned device pointer

bytesize

- Requested allocation size in bytes

Returns

CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,

CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_VALUE,

CUDA_ERROR_OUT_OF_MEMORY

Description

Allocates bytesize bytes of linear memory on the device and returns in *dptr a pointer to the

allocated memory. The allocated memory is suitably aligned for any kind of variable. The memory is

not cleared. If bytesize is 0, cuMemAlloc() returns CUDA_ERROR_INVALID_VALUE.

Note:

Note that this function may also return error codes from previous, asynchronous launches.

See also:

cuArray3DCreate, cuArray3DGetDescriptor, cuArrayCreate, cuArrayDestroy, cuArrayGetDescriptor,

cuMemAllocHost, cuMemAllocPitch, cuMemcpy2D, cuMemcpy2DAsync, cuMemcpy2DUnaligned,

cuMemcpy3D, cuMemcpy3DAsync, cuMemcpyAtoA, cuMemcpyAtoD, cuMemcpyAtoH,

cuMemcpyAtoHAsync, cuMemcpyDtoA, cuMemcpyDtoD, cuMemcpyDtoDAsync, cuMemcpyDtoH,

cuMemcpyDtoHAsync, cuMemcpyHtoA, cuMemcpyHtoAAsync, cuMemcpyHtoD,

cuMemcpyHtoDAsync, cuMemFree, cuMemFreeHost, cuMemGetAddressRange, cuMemGetInfo,

cuMemHostAlloc, cuMemHostGetDevicePointer, cuMemsetD2D8, cuMemsetD2D16,

cuMemsetD2D32, cuMemsetD8, cuMemsetD16, cuMemsetD32, cudaMalloc

CUresult cuMemAllocHost (void **pp, size_t bytesize)

Allocates page-locked host memory.

Parameters

- Returned pointer to host memory

202

Modules

bytesize

- Requested allocation size in bytes

Returns

CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,

CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_VALUE,

CUDA_ERROR_OUT_OF_MEMORY

Description

Allocates bytesize bytes of host memory that is page-locked and accessible to the device. The

driver tracks the virtual memory ranges allocated with this function and automatically accelerates calls

to functions such as cuMemcpy(). Since the memory can be accessed directly by the device, it can be

read or written with much higher bandwidth than pageable memory obtained with functions such as

malloc().

On systems where

CU_DEVICE_ATTRIBUTE_PAGEABLE_MEMORY_ACCESS_USES_HOST_PAGE_TABLES is

true, cuMemAllocHost may not page-lock the allocated memory.

Page-locking excessive amounts of memory with cuMemAllocHost() may degrade system

performance, since it reduces the amount of memory available to the system for paging. As a result,

this function is best used sparingly to allocate staging areas for data exchange between host and device.

Note all host memory allocated using cuMemAllocHost() will automatically be immediately

accessible to all contexts on all devices which support unified addressing (as may be queried using

CU_DEVICE_ATTRIBUTE_UNIFIED_ADDRESSING). The device pointer that may be used to

access this host memory from those contexts is always equal to the returned host pointer *pp. See

Unified Addressing for additional details.

Note:

Note that this function may also return error codes from previous, asynchronous launches.

See also:

cuArray3DCreate, cuArray3DGetDescriptor, cuArrayCreate, cuArrayDestroy, cuArrayGetDescriptor,

cuMemAlloc, cuMemAllocPitch, cuMemcpy2D, cuMemcpy2DAsync, cuMemcpy2DUnaligned,

cuMemcpy3D, cuMemcpy3DAsync, cuMemcpyAtoA, cuMemcpyAtoD, cuMemcpyAtoH,

cuMemcpyAtoHAsync, cuMemcpyDtoA, cuMemcpyDtoD, cuMemcpyDtoDAsync, cuMemcpyDtoH,

cuMemcpyDtoHAsync, cuMemcpyHtoA, cuMemcpyHtoAAsync, cuMemcpyHtoD,

cuMemcpyHtoDAsync, cuMemFree, cuMemFreeHost, cuMemGetAddressRange, cuMemGetInfo,

cuMemHostAlloc, cuMemHostGetDevicePointer, cuMemsetD2D8, cuMemsetD2D16,

cuMemsetD2D32, cuMemsetD8, cuMemsetD16, cuMemsetD32, cudaMallocHost

203

Modules

CUresult cuMemAllocManaged (CUdeviceptr *dptr, size_t

bytesize, unsigned int flags)

Allocates memory that will be automatically managed by the Unified Memory system.

Parameters

dptr

- Returned device pointer

bytesize

- Requested allocation size in bytes

flags

- Must be one of CU_MEM_ATTACH_GLOBAL or CU_MEM_ATTACH_HOST

Returns

CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,

CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_NOT_SUPPORTED,

CUDA_ERROR_INVALID_VALUE, CUDA_ERROR_OUT_OF_MEMORY

Description

Allocates bytesize bytes of managed memory on the device and returns in *dptr a

pointer to the allocated memory. If the device doesn't support allocating managed memory,

CUDA_ERROR_NOT_SUPPORTED is returned. Support for managed memory can be queried

using the device attribute CU_DEVICE_ATTRIBUTE_MANAGED_MEMORY. The allocated

memory is suitably aligned for any kind of variable. The memory is not cleared. If bytesize is 0,

cuMemAllocManaged returns CUDA_ERROR_INVALID_VALUE. The pointer is valid on the CPU

and on all GPUs in the system that support managed memory. All accesses to this pointer must obey

the Unified Memory programming model.

flags specifies the default stream association for this allocation. flags must

be one of CU_MEM_ATTACH_GLOBAL or CU_MEM_ATTACH_HOST. If

CU_MEM_ATTACH_GLOBAL is specified, then this memory is accessible from any

stream on any device. If CU_MEM_ATTACH_HOST is specified, then the allocation

should not be accessed from devices that have a zero value for the device attribute

CU_DEVICE_ATTRIBUTE_CONCURRENT_MANAGED_ACCESS; an explicit call to

cuStreamAttachMemAsync will be required to enable access on such devices.

If the association is later changed via cuStreamAttachMemAsync to a single stream, the default

association as specified during cuMemAllocManaged is restored when that stream is destroyed. For

__managed__ variables, the default association is always CU_MEM_ATTACH_GLOBAL. Note that

destroying a stream is an asynchronous operation, and as a result, the change to default association

won't happen until all work in the stream has completed.

Memory allocated with cuMemAllocManaged should be released with cuMemFree.

204

Modules

Device memory oversubscription is possible for GPUs that have a non-zero value for the device

attribute CU_DEVICE_ATTRIBUTE_CONCURRENT_MANAGED_ACCESS. Managed memory on

such GPUs may be evicted from device memory to host memory at any time by the Unified Memory

driver in order to make room for other allocations.

In a system where all GPUs have a non-zero value for the device attribute

CU_DEVICE_ATTRIBUTE_CONCURRENT_MANAGED_ACCESS, managed memory may

not be populated when this API returns and instead may be populated on access. In such systems,

managed memory can migrate to any processor's memory at any time. The Unified Memory driver will

employ heuristics to maintain data locality and prevent excessive page faults to the extent possible. The

application can also guide the driver about memory usage patterns via cuMemAdvise. The application

can also explicitly migrate memory to a desired processor's memory via cuMemPrefetchAsync.

In a multi-GPU system where all of the GPUs have a zero value for the device attribute

CU_DEVICE_ATTRIBUTE_CONCURRENT_MANAGED_ACCESS and all the GPUs have peer-to-

peer support with each other, the physical storage for managed memory is created on the GPU which

is active at the time cuMemAllocManaged is called. All other GPUs will reference the data at reduced

bandwidth via peer mappings over the PCIe bus. The Unified Memory driver does not migrate memory

among such GPUs.

In a multi-GPU system where not all GPUs have peer-to-peer support with each other and where the

value of the device attribute CU_DEVICE_ATTRIBUTE_CONCURRENT_MANAGED_ACCESS

is zero for at least one of those GPUs, the location chosen for physical storage of managed memory is

system-dependent.

‣ On Linux, the location chosen will be device memory as long as the current set of active contexts

are on devices that either have peer-to-peer support with each other or have a non-zero value for

the device attribute CU_DEVICE_ATTRIBUTE_CONCURRENT_MANAGED_ACCESS. If

there is an active context on a GPU that does not have a non-zero value for that device attribute

and it does not have peer-to-peer support with the other devices that have active contexts on them,

then the location for physical storage will be 'zero-copy' or host memory. Note that this means

that managed memory that is located in device memory is migrated to host memory if a new

context is created on a GPU that doesn't have a non-zero value for the device attribute and does not

support peer-to-peer with at least one of the other devices that has an active context. This in turn

implies that context creation may fail if there is insufficient host memory to migrate all managed

allocations.

‣ On Windows, the physical storage is always created in 'zero-copy' or host memory. All GPUs

will reference the data at reduced bandwidth over the PCIe bus. In these circumstances, use

of the environment variable CUDA_VISIBLE_DEVICES is recommended to restrict CUDA

to only use those GPUs that have peer-to-peer support. Alternatively, users can also set

CUDA_MANAGED_FORCE_DEVICE_ALLOC to a non-zero value to force the driver to always

use device memory for physical storage. When this environment variable is set to a non-zero value,

all contexts created in that process on devices that support managed memory have to be peer-

to-peer compatible with each other. Context creation will fail if a context is created on a device

that supports managed memory and is not peer-to-peer compatible with any of the other managed

memory supporting devices on which contexts were previously created, even if those contexts have

205

Modules

been destroyed. These environment variables are described in the CUDA programming guide under

the "CUDA environment variables" section.

‣ On ARM, managed memory is not available on discrete gpu with Drive PX-2.

Note:

Note that this function may also return error codes from previous, asynchronous launches.

See also:

cuArray3DCreate, cuArray3DGetDescriptor, cuArrayCreate, cuArrayDestroy, cuArrayGetDescriptor,

cuMemAllocHost, cuMemAllocPitch, cuMemcpy2D, cuMemcpy2DAsync, cuMemcpy2DUnaligned,

cuMemcpy3D, cuMemcpy3DAsync, cuMemcpyAtoA, cuMemcpyAtoD, cuMemcpyAtoH,

cuMemcpyAtoHAsync, cuMemcpyDtoA, cuMemcpyDtoD, cuMemcpyDtoDAsync, cuMemcpyDtoH,

cuMemcpyDtoHAsync, cuMemcpyHtoA, cuMemcpyHtoAAsync, cuMemcpyHtoD,

cuMemcpyHtoDAsync, cuMemFree, cuMemFreeHost, cuMemGetAddressRange, cuMemGetInfo,

cuMemHostAlloc, cuMemHostGetDevicePointer, cuMemsetD2D8, cuMemsetD2D16,

cuMemsetD2D32, cuMemsetD8, cuMemsetD16, cuMemsetD32, cuDeviceGetAttribute,

cuStreamAttachMemAsync, cudaMallocManaged

CUresult cuMemAllocPitch (CUdeviceptr *dptr, size_t

*pPitch, size_t WidthInBytes, size_t Height, unsigned int

ElementSizeBytes)

Allocates pitched device memory.

Parameters

dptr

- Returned device pointer

pPitch

- Returned pitch of allocation in bytes

WidthInBytes

- Requested allocation width in bytes

Height

- Requested allocation height in rows

ElementSizeBytes

- Size of largest reads/writes for range

Returns

CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,

CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_VALUE,

CUDA_ERROR_OUT_OF_MEMORY

206

Modules

Description

Allocates at least WidthInBytes * Height bytes of linear memory on the device and returns

in *dptr a pointer to the allocated memory. The function may pad the allocation to ensure that

corresponding pointers in any given row will continue to meet the alignment requirements for

coalescing as the address is updated from row to row. ElementSizeBytes specifies the size of

the largest reads and writes that will be performed on the memory range. ElementSizeBytes

may be 4, 8 or 16 (since coalesced memory transactions are not possible on other data sizes). If

ElementSizeBytes is smaller than the actual read/write size of a kernel, the kernel will run

correctly, but possibly at reduced speed. The pitch returned in *pPitch by cuMemAllocPitch() is the

width in bytes of the allocation. The intended usage of pitch is as a separate parameter of the allocation,

used to compute addresses within the 2D array. Given the row and column of an array element of type

T, the address is computed as:

‎

T* pElement = (T*)((char*)BaseAddress + Row * Pitch) + Column;

The pitch returned by cuMemAllocPitch() is guaranteed to work with cuMemcpy2D() under all

circumstances. For allocations of 2D arrays, it is recommended that programmers consider performing

pitch allocations using cuMemAllocPitch(). Due to alignment restrictions in the hardware, this is

especially true if the application will be performing 2D memory copies between different regions of

device memory (whether linear memory or CUDA arrays).

The byte alignment of the pitch returned by cuMemAllocPitch() is guaranteed to match or exceed the

alignment requirement for texture binding with cuTexRefSetAddress2D().

Note:

Note that this function may also return error codes from previous, asynchronous launches.

See also:

cuArray3DCreate, cuArray3DGetDescriptor, cuArrayCreate, cuArrayDestroy, cuArrayGetDescriptor,

cuMemAlloc, cuMemAllocHost, cuMemcpy2D, cuMemcpy2DAsync, cuMemcpy2DUnaligned,

cuMemcpy3D, cuMemcpy3DAsync, cuMemcpyAtoA, cuMemcpyAtoD, cuMemcpyAtoH,

cuMemcpyAtoHAsync, cuMemcpyDtoA, cuMemcpyDtoD, cuMemcpyDtoDAsync, cuMemcpyDtoH,

cuMemcpyDtoHAsync, cuMemcpyHtoA, cuMemcpyHtoAAsync, cuMemcpyHtoD,

cuMemcpyHtoDAsync, cuMemFree, cuMemFreeHost, cuMemGetAddressRange, cuMemGetInfo,

cuMemHostAlloc, cuMemHostGetDevicePointer, cuMemsetD2D8, cuMemsetD2D16,

cuMemsetD2D32, cuMemsetD8, cuMemsetD16, cuMemsetD32, cudaMallocPitch

207

Modules

CUresult cuMemBatchDecompressAsync

(CUmemDecompressParams *paramsArray, size_t count,

unsigned int flags, size_t *errorIndex, CUstream stream)

Submit a batch of count independent decompression operations.

Parameters

paramsArray

The array of structures describing the independent decompression operations.

count

The number of entries in paramsArray array.

flags

Must be 0.

errorIndex

The index into paramsArray of the decompression operation for which the error returned by this

function pertains to. If index is SIZE_MAX and the value returned is not CUDA_SUCCESS, then

the error returned by this function should be considered a general error that does not pertain to a

particular decompression operation. May be NULL, in which case, no index will be recorded in the

event of error.

stream

The stream where the work will be enqueued.

Returns

CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,

CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_VALUE,

CUDA_ERROR_INVALID_HANDLE

Description

Each of the count decompression operations is described by a single entry in the paramsArray

array. Once the batch has been submitted, the function will return, and decompression will happen

asynchronously w.r.t. the CPU. To the work completion tracking mechanisms in the CUDA driver, the

batch will be considered a single unit of work and processed according to stream semantics, i.e., it is

not possible to query the completion of individual decompression operations within a batch.

The memory pointed to by each of CUmemDecompressParams.src, CUmemDecompressParams.dst,

and CUmemDecompressParams.dstActBytes, must be capable of usage with the

hardware decompress feature. That is, for each of said pointers, the pointer attribute

CU_POINTER_ATTRIBUTE_IS_MEM_DECOMPRESS_CAPABLE should give a non-zero

value. To ensure this, the memory backing the pointers should have been allocated using one of

the following CUDA memory allocators: * cuMemAlloc() * cuMemCreate() with the usage flag

CU_MEM_CREATE_USAGE_HW_DECOMPRESS * cuMemAllocFromPoolAsync() from a pool

that was created with the usage flag CU_MEM_POOL_CREATE_USAGE_HW_DECOMPRESS

208

Modules

Additionally, CUmemDecompressParams.src, CUmemDecompressParams.dst, and

CUmemDecompressParams.dstActBytes, must all be accessible from the device associated with the

context where stream was created. For information on how to ensure this, see the documentation for

the allocator of interest.

Note:

‣ Note that this function may also return error codes from previous, asynchronous launches.

‣ This function exhibits asynchronous behavior for most use cases.

‣ This function uses standard default stream semantics.

See also:

cuMemAlloc, cuMemPoolCreate, cuMemAllocFromPoolAsync

CUresult cuMemcpy (CUdeviceptr dst, CUdeviceptr src,

size_t ByteCount)

Copies memory.

Parameters

dst

- Destination unified virtual address space pointer

src

- Source unified virtual address space pointer

ByteCount

- Size of memory copy in bytes

Returns

CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,

CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_VALUE

Description

Copies data between two pointers. dst and src are base pointers of the destination and source,

respectively. ByteCount specifies the number of bytes to copy. Note that this function infers the type

of the transfer (host to host, host to device, device to device, or device to host) from the pointer values.

This function is only allowed in contexts which support unified addressing.

Note:

‣ Note that this function may also return error codes from previous, asynchronous launches.

209

Modules

‣ This function exhibits synchronous behavior for most use cases.

‣ Memory regions requested must be either entirely registered with CUDA, or in the case

of host pageable transfers, not registered at all. Memory regions spanning over allocations

that are both registered and not registered with CUDA are not supported and will return

CUDA_ERROR_INVALID_VALUE.

See also:

cuArray3DCreate, cuArray3DGetDescriptor, cuArrayCreate, cuArrayDestroy, cuArrayGetDescriptor,

cuMemAlloc, cuMemAllocHost, cuMemAllocPitch, cuMemcpy2D, cuMemcpy2DAsync,

cuMemcpy2DUnaligned, cuMemcpy3D, cuMemcpy3DAsync, cuMemcpyAtoA, cuMemcpyAtoD,

cuMemcpyAtoH, cuMemcpyAtoHAsync, cuMemcpyDtoA, cuMemcpyDtoH, cuMemcpyDtoHAsync,

cuMemcpyHtoA, cuMemcpyHtoAAsync, cuMemcpyHtoD, cuMemcpyHtoDAsync,

cuMemFree, cuMemFreeHost, cuMemGetAddressRange, cuMemGetInfo, cuMemHostAlloc,

cuMemHostGetDevicePointer, cuMemsetD2D8, cuMemsetD2D16, cuMemsetD2D32, cuMemsetD8,

cuMemsetD16, cuMemsetD32, cudaMemcpy, cudaMemcpyToSymbol, cudaMemcpyFromSymbol

CUresult cuMemcpy2D (const CUDA_MEMCPY2D

*pCopy)

Copies memory for 2D arrays.

Parameters

pCopy

- Parameters for the memory copy

Returns

CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,

CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_VALUE

Description

Perform a 2D memory copy according to the parameters specified in pCopy. The

CUDA_MEMCPY2D structure is defined as:

‎

typedef struct CUDA_MEMCPY2D_st {

unsigned int srcXInBytes, srcY;

CUmemorytype srcMemoryType;

const void *srcHost;

CUdeviceptr srcDevice;

CUarray srcArray;

unsigned int srcPitch;

unsigned int dstXInBytes, dstY;

CUmemorytype dstMemoryType;

void *dstHost;

CUdeviceptr dstDevice;

CUarray dstArray;

unsigned int dstPitch;

210

Modules

unsigned int WidthInBytes;

unsigned int Height;

} CUDA_MEMCPY2D;

where:

‣ srcMemoryType and dstMemoryType specify the type of memory of the source and destination,

respectively; CUmemorytype_enum is defined as:

‎

typedef enum CUmemorytype_enum {

CU_MEMORYTYPE_HOST = 0x01,

CU_MEMORYTYPE_DEVICE = 0x02,

CU_MEMORYTYPE_ARRAY = 0x03,

CU_MEMORYTYPE_UNIFIED = 0x04

} CUmemorytype;

If srcMemoryType is CU_MEMORYTYPE_UNIFIED, srcDevice and srcPitch specify the (unified

virtual address space) base address of the source data and the bytes per row to apply. srcArray is

ignored. This value may be used only if unified addressing is supported in the calling context.

If srcMemoryType is CU_MEMORYTYPE_HOST, srcHost and srcPitch specify the (host) base

address of the source data and the bytes per row to apply. srcArray is ignored.

If srcMemoryType is CU_MEMORYTYPE_DEVICE, srcDevice and srcPitch specify the (device)

base address of the source data and the bytes per row to apply. srcArray is ignored.

If srcMemoryType is CU_MEMORYTYPE_ARRAY, srcArray specifies the handle of the source data.

srcHost, srcDevice and srcPitch are ignored.

If dstMemoryType is CU_MEMORYTYPE_HOST, dstHost and dstPitch specify the (host) base

address of the destination data and the bytes per row to apply. dstArray is ignored.

If dstMemoryType is CU_MEMORYTYPE_UNIFIED, dstDevice and dstPitch specify the (unified

virtual address space) base address of the source data and the bytes per row to apply. dstArray is

ignored. This value may be used only if unified addressing is supported in the calling context.

If dstMemoryType is CU_MEMORYTYPE_DEVICE, dstDevice and dstPitch specify the (device)

base address of the destination data and the bytes per row to apply. dstArray is ignored.

If dstMemoryType is CU_MEMORYTYPE_ARRAY, dstArray specifies the handle of the destination

data. dstHost, dstDevice and dstPitch are ignored.

‣ srcXInBytes and srcY specify the base address of the source data for the copy.

For host pointers, the starting address is

‎ void* Start = (void*)((char*)srcHost+srcY*srcPitch + srcXInBytes);

For device pointers, the starting address is

‎ CUdeviceptr Start = srcDevice+srcY*srcPitch+srcXInBytes;

For CUDA arrays, srcXInBytes must be evenly divisible by the array element size.

211

Modules

‣ dstXInBytes and dstY specify the base address of the destination data for the copy.

For host pointers, the base address is

‎ void* dstStart = (void*)((char*)dstHost+dstY*dstPitch + dstXInBytes);

For device pointers, the starting address is

‎ CUdeviceptr dstStart = dstDevice+dstY*dstPitch+dstXInBytes;

For CUDA arrays, dstXInBytes must be evenly divisible by the array element size.

‣ WidthInBytes and Height specify the width (in bytes) and height of the 2D copy being performed.

‣ If specified, srcPitch must be greater than or equal to WidthInBytes + srcXInBytes, and dstPitch

must be greater than or equal to WidthInBytes + dstXInBytes.

cuMemcpy2D() returns an error if any pitch is greater than the maximum allowed

(CU_DEVICE_ATTRIBUTE_MAX_PITCH). cuMemAllocPitch() passes back pitches that always

work with cuMemcpy2D(). On intra-device memory copies (device to device, CUDA array to

device, CUDA array to CUDA array), cuMemcpy2D() may fail for pitches not computed by

cuMemAllocPitch(). cuMemcpy2DUnaligned() does not have this restriction, but may run significantly

slower in the cases where cuMemcpy2D() would have returned an error code.

Note:

‣ Note that this function may also return error codes from previous, asynchronous launches.

‣ This function exhibits synchronous behavior for most use cases.

See also:

cuArray3DCreate, cuArray3DGetDescriptor, cuArrayCreate, cuArrayDestroy, cuArrayGetDescriptor,

cuMemAlloc, cuMemAllocHost, cuMemAllocPitch, cuMemcpy2DAsync, cuMemcpy2DUnaligned,

cuMemcpy3D, cuMemcpy3DAsync, cuMemcpyAtoA, cuMemcpyAtoD, cuMemcpyAtoH,

cuMemcpyAtoHAsync, cuMemcpyDtoA, cuMemcpyDtoD, cuMemcpyDtoDAsync,

cuMemcpyDtoH, cuMemcpyDtoHAsync, cuMemcpyHtoA, cuMemcpyHtoAAsync, cuMemcpyHtoD,

cuMemcpyHtoDAsync, cuMemFree, cuMemFreeHost, cuMemGetAddressRange, cuMemGetInfo,

cuMemHostAlloc, cuMemHostGetDevicePointer, cuMemsetD2D8, cuMemsetD2D16,

cuMemsetD2D32, cuMemsetD8, cuMemsetD16, cuMemsetD32, cudaMemcpy2D,

cudaMemcpy2DToArray, cudaMemcpy2DFromArray

212

Modules

CUresult cuMemcpy2DAsync (const CUDA_MEMCPY2D

*pCopy, CUstream hStream)

Copies memory for 2D arrays.

Parameters

pCopy

- Parameters for the memory copy

hStream

- Stream identifier

Returns

CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,

CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_VALUE,

CUDA_ERROR_INVALID_HANDLE

Description

Perform a 2D memory copy according to the parameters specified in pCopy. The

CUDA_MEMCPY2D structure is defined as:

‎

typedef struct CUDA_MEMCPY2D_st {

unsigned int srcXInBytes, srcY;

CUmemorytype srcMemoryType;

const void *srcHost;

CUdeviceptr srcDevice;

CUarray srcArray;

unsigned int srcPitch;

unsigned int dstXInBytes, dstY;

CUmemorytype dstMemoryType;

void *dstHost;

CUdeviceptr dstDevice;

CUarray dstArray;

unsigned int dstPitch;

unsigned int WidthInBytes;

unsigned int Height;

} CUDA_MEMCPY2D;

where:

‣ srcMemoryType and dstMemoryType specify the type of memory of the source and destination,

respectively; CUmemorytype_enum is defined as:

‎

typedef enum CUmemorytype_enum {

CU_MEMORYTYPE_HOST = 0x01,

CU_MEMORYTYPE_DEVICE = 0x02,

CU_MEMORYTYPE_ARRAY = 0x03,

CU_MEMORYTYPE_UNIFIED = 0x04

} CUmemorytype;

If srcMemoryType is CU_MEMORYTYPE_HOST, srcHost and srcPitch specify the (host) base

address of the source data and the bytes per row to apply. srcArray is ignored.

213