Provided by: nvidia-cuda-dev_10.1.243-3_amd64 
NAME
External Resource Interoperability -
Functions
cudaError_t cudaDestroyExternalMemory (cudaExternalMemory_t extMem)
Destroys an external memory object.
cudaError_t cudaDestroyExternalSemaphore (cudaExternalSemaphore_t extSem)
Destroys an external semaphore.
cudaError_t cudaExternalMemoryGetMappedBuffer (void **devPtr, cudaExternalMemory_t extMem,
const struct cudaExternalMemoryBufferDesc *bufferDesc)
Maps a buffer onto an imported memory object.
cudaError_t cudaExternalMemoryGetMappedMipmappedArray (cudaMipmappedArray_t *mipmap,
cudaExternalMemory_t extMem, const struct cudaExternalMemoryMipmappedArrayDesc
*mipmapDesc)
Maps a CUDA mipmapped array onto an external memory object.
cudaError_t cudaImportExternalMemory (cudaExternalMemory_t *extMem_out, const struct
cudaExternalMemoryHandleDesc *memHandleDesc)
Imports an external memory object.
cudaError_t cudaImportExternalSemaphore (cudaExternalSemaphore_t *extSem_out, const struct
cudaExternalSemaphoreHandleDesc *semHandleDesc)
Imports an external semaphore.
cudaError_t cudaSignalExternalSemaphoresAsync (const cudaExternalSemaphore_t *extSemArray,
const struct cudaExternalSemaphoreSignalParams *paramsArray, unsigned int numExtSems,
cudaStream_t stream=0)
Signals a set of external semaphore objects.
cudaError_t cudaWaitExternalSemaphoresAsync (const cudaExternalSemaphore_t *extSemArray,
const struct cudaExternalSemaphoreWaitParams *paramsArray, unsigned int numExtSems,
cudaStream_t stream=0)
Waits on a set of external semaphore objects.
Detailed Description
\brief External resource interoperability functions of the CUDA runtime API
(cuda_runtime_api.h)
This section describes the external resource interoperability functions of the CUDA
runtime application programming interface.
Function Documentation
cudaError_t cudaDestroyExternalMemory (cudaExternalMemory_t extMem)
Destroys the specified external memory object. Any existing buffers and CUDA mipmapped
arrays mapped onto this object must no longer be used and must be explicitly freed using
cudaFree and cudaFreeMipmappedArray respectively.
Parameters:
extMem - External memory object to be destroyed
Returns:
cudaSuccess, cudaErrorInvalidResourceHandle
Note:
Note that this function may also return error codes from previous, asynchronous
launches.
See also:
cudaImportExternalMemory cudaExternalMemoryGetMappedBuffer,
cudaExternalMemoryGetMappedMipmappedArray
cudaError_t cudaDestroyExternalSemaphore (cudaExternalSemaphore_t extSem)
Destroys an external semaphore object and releases any references to the underlying
resource. Any outstanding signals or waits must have completed before the semaphore is
destroyed.
Parameters:
extSem - External semaphore to be destroyed
Returns:
cudaSuccess, cudaErrorInvalidResourceHandle
Note:
Note that this function may also return error codes from previous, asynchronous
launches.
See also:
cudaImportExternalSemaphore, cudaSignalExternalSemaphoresAsync,
cudaWaitExternalSemaphoresAsync
cudaError_t cudaExternalMemoryGetMappedBuffer (void ** devPtr, cudaExternalMemory_t extMem,
const struct cudaExternalMemoryBufferDesc * bufferDesc)
Maps a buffer onto an imported memory object and returns a device pointer in devPtr.
The properties of the buffer being mapped must be described in bufferDesc. The
cudaExternalMemoryBufferDesc structure is defined as follows:
typedef struct cudaExternalMemoryBufferDesc_st {
unsigned long long offset;
unsigned long long size;
unsigned int flags;
} cudaExternalMemoryBufferDesc;
where cudaExternalMemoryBufferDesc::offset is the offset in the memory object where the
buffer's base address is. cudaExternalMemoryBufferDesc::size is the size of the buffer.
cudaExternalMemoryBufferDesc::flags must be zero.
The offset and size have to be suitably aligned to match the requirements of the external
API. Mapping two buffers whose ranges overlap may or may not result in the same virtual
address being returned for the overlapped portion. In such cases, the application must
ensure that all accesses to that region from the GPU are volatile. Otherwise writes made
via one address are not guaranteed to be visible via the other address, even if they're
issued by the same thread. It is recommended that applications map the combined range
instead of mapping separate buffers and then apply the appropriate offsets to the returned
pointer to derive the individual buffers.
The returned pointer devPtr must be freed using cudaFree.
Parameters:
devPtr - Returned device pointer to buffer
extMem - Handle to external memory object
bufferDesc - Buffer descriptor
Returns:
cudaSuccess, cudaErrorInvalidResourceHandle
Note:
Note that this function may also return error codes from previous, asynchronous
launches.
See also:
cudaImportExternalMemory cudaDestroyExternalMemory,
cudaExternalMemoryGetMappedMipmappedArray
cudaError_t cudaExternalMemoryGetMappedMipmappedArray (cudaMipmappedArray_t * mipmap,
cudaExternalMemory_t extMem, const struct cudaExternalMemoryMipmappedArrayDesc *
mipmapDesc)
Maps a CUDA mipmapped array onto an external object and returns a handle to it in mipmap.
The properties of the CUDA mipmapped array being mapped must be described in mipmapDesc.
The structure cudaExternalMemoryMipmappedArrayDesc is defined as follows:
typedef struct cudaExternalMemoryMipmappedArrayDesc_st {
unsigned long long offset;
cudaChannelFormatDesc formatDesc;
cudaExtent extent;
unsigned int flags;
unsigned int numLevels;
} cudaExternalMemoryMipmappedArrayDesc;
where cudaExternalMemoryMipmappedArrayDesc::offset is the offset in the memory object
where the base level of the mipmap chain is.
cudaExternalMemoryMipmappedArrayDesc::formatDesc describes the format of the data.
cudaExternalMemoryMipmappedArrayDesc::extent specifies the dimensions of the base level of
the mipmap chain. cudaExternalMemoryMipmappedArrayDesc::flags are flags associated with
CUDA mipmapped arrays. For further details, please refer to the documentation for
cudaMalloc3DArray. Note that if the mipmapped array is bound as a color target in the
graphics API, then the flag cudaArrayColorAttachment must be specified in
cudaExternalMemoryMipmappedArrayDesc::flags.
cudaExternalMemoryMipmappedArrayDesc::numLevels specifies the total number of levels in
the mipmap chain.
The returned CUDA mipmapped array must be freed using cudaFreeMipmappedArray.
Parameters:
mipmap - Returned CUDA mipmapped array
extMem - Handle to external memory object
mipmapDesc - CUDA array descriptor
Returns:
cudaSuccess, cudaErrorInvalidResourceHandle
Note:
Note that this function may also return error codes from previous, asynchronous
launches.
See also:
cudaImportExternalMemory cudaDestroyExternalMemory, cudaExternalMemoryGetMappedBuffer
cudaError_t cudaImportExternalMemory (cudaExternalMemory_t * extMem_out, const struct
cudaExternalMemoryHandleDesc * memHandleDesc)
Imports an externally allocated memory object and returns a handle to that in extMem_out.
The properties of the handle being imported must be described in memHandleDesc. The
cudaExternalMemoryHandleDesc structure is defined as follows:
typedef struct cudaExternalMemoryHandleDesc_st {
cudaExternalMemoryHandleType type;
union {
int fd;
struct {
void *handle;
const void *name;
} win32;
} handle;
unsigned long long size;
unsigned int flags;
} cudaExternalMemoryHandleDesc;
where cudaExternalMemoryHandleDesc::type specifies the type of handle being imported.
cudaExternalMemoryHandleType is defined as:
typedef enum cudaExternalMemoryHandleType_enum {
cudaExternalMemoryHandleTypeOpaqueFd = 1,
cudaExternalMemoryHandleTypeOpaqueWin32 = 2,
cudaExternalMemoryHandleTypeOpaqueWin32Kmt = 3,
cudaExternalMemoryHandleTypeD3D12Heap = 4,
cudaExternalMemoryHandleTypeD3D12Resource = 5
} cudaExternalMemoryHandleType;
If cudaExternalMemoryHandleDesc::type is cudaExternalMemoryHandleTypeOpaqueFd, then
cudaExternalMemoryHandleDesc::handle::fd must be a valid file descriptor referencing a
memory object. Ownership of the file descriptor is transferred to the CUDA driver when the
handle is imported successfully. Performing any operations on the file descriptor after it
is imported results in undefined behavior.
If cudaExternalMemoryHandleDesc::type is cudaExternalMemoryHandleTypeOpaqueWin32, then
exactly one of cudaExternalMemoryHandleDesc::handle::win32::handle and
cudaExternalMemoryHandleDesc::handle::win32::name must not be NULL. If
cudaExternalMemoryHandleDesc::handle::win32::handle is not NULL, then it must represent a
valid shared NT handle that references a memory object. Ownership of this handle is not
transferred to CUDA after the import operation, so the application must release the handle
using the appropriate system call. If cudaExternalMemoryHandleDesc::handle::win32::name is
not NULL, then it must point to a NULL-terminated array of UTF-16 characters that refers
to a memory object.
If cudaExternalMemoryHandleDesc::type is cudaExternalMemoryHandleTypeOpaqueWin32Kmt, then
cudaExternalMemoryHandleDesc::handle::win32::handle must be non-NULL and
cudaExternalMemoryHandleDesc::handle::win32::name must be NULL. The handle specified must
be a globally shared KMT handle. This handle does not hold a reference to the underlying
object, and thus will be invalid when all references to the memory object are destroyed.
If cudaExternalMemoryHandleDesc::type is cudaExternalMemoryHandleTypeD3D12Heap, then
exactly one of cudaExternalMemoryHandleDesc::handle::win32::handle and
cudaExternalMemoryHandleDesc::handle::win32::name must not be NULL. If
cudaExternalMemoryHandleDesc::handle::win32::handle is not NULL, then it must represent a
valid shared NT handle that is returned by ID3DDevice::CreateSharedHandle when referring
to a ID3D12Heap object. This handle holds a reference to the underlying object. If
cudaExternalMemoryHandleDesc::handle::win32::name is not NULL, then it must point to a
NULL-terminated array of UTF-16 characters that refers to a ID3D12Heap object.
If cudaExternalMemoryHandleDesc::type is cudaExternalMemoryHandleTypeD3D12Resource, then
exactly one of cudaExternalMemoryHandleDesc::handle::win32::handle and
cudaExternalMemoryHandleDesc::handle::win32::name must not be NULL. If
cudaExternalMemoryHandleDesc::handle::win32::handle is not NULL, then it must represent a
valid shared NT handle that is returned by ID3DDevice::CreateSharedHandle when referring
to a ID3D12Resource object. This handle holds a reference to the underlying object. If
cudaExternalMemoryHandleDesc::handle::win32::name is not NULL, then it must point to a
NULL-terminated array of UTF-16 characters that refers to a ID3D12Resource object.
The size of the memory object must be specified in cudaExternalMemoryHandleDesc::size.
Specifying the flag cudaExternalMemoryDedicated in cudaExternalMemoryHandleDesc::flags
indicates that the resource is a dedicated resource. The definition of what a dedicated
resource is outside the scope of this extension.
Parameters:
extMem_out - Returned handle to an external memory object
memHandleDesc - Memory import handle descriptor
Returns:
cudaSuccess, cudaErrorInvalidResourceHandle
Note:
Note that this function may also return error codes from previous, asynchronous
launches.
If the Vulkan memory imported into CUDA is mapped on the CPU then the application must
use vkInvalidateMappedMemoryRanges/vkFlushMappedMemoryRanges as well as appropriate
Vulkan pipeline barriers to maintain coherence between CPU and GPU. For more
information on these APIs, please refer to 'Synchronization and Cache Control' chapter
from Vulkan specification.
See also:
cudaDestroyExternalMemory, cudaExternalMemoryGetMappedBuffer,
cudaExternalMemoryGetMappedMipmappedArray
cudaError_t cudaImportExternalSemaphore (cudaExternalSemaphore_t * extSem_out, const struct
cudaExternalSemaphoreHandleDesc * semHandleDesc)
Imports an externally allocated synchronization object and returns a handle to that in
extSem_out.
The properties of the handle being imported must be described in semHandleDesc. The
cudaExternalSemaphoreHandleDesc is defined as follows:
typedef struct cudaExternalSemaphoreHandleDesc_st {
cudaExternalSemaphoreHandleType type;
union {
int fd;
struct {
void *handle;
const void *name;
} win32;
} handle;
unsigned int flags;
} cudaExternalSemaphoreHandleDesc;
where cudaExternalSemaphoreHandleDesc::type specifies the type of handle being imported.
cudaExternalSemaphoreHandleType is defined as:
typedef enum cudaExternalSemaphoreHandleType_enum {
cudaExternalSemaphoreHandleTypeOpaqueFd = 1,
cudaExternalSemaphoreHandleTypeOpaqueWin32 = 2,
cudaExternalSemaphoreHandleTypeOpaqueWin32Kmt = 3,
cudaExternalSemaphoreHandleTypeD3D12Fence = 4
} cudaExternalSemaphoreHandleType;
If cudaExternalSemaphoreHandleDesc::type is cudaExternalSemaphoreHandleTypeOpaqueFd, then
cudaExternalSemaphoreHandleDesc::handle::fd must be a valid file descriptor referencing a
synchronization object. Ownership of the file descriptor is transferred to the CUDA driver
when the handle is imported successfully. Performing any operations on the file descriptor
after it is imported results in undefined behavior.
If cudaExternalSemaphoreHandleDesc::type is cudaExternalSemaphoreHandleTypeOpaqueWin32,
then exactly one of cudaExternalSemaphoreHandleDesc::handle::win32::handle and
cudaExternalSemaphoreHandleDesc::handle::win32::name must not be NULL. If
cudaExternalSemaphoreHandleDesc::handle::win32::handle is not NULL, then it must represent
a valid shared NT handle that references a synchronization object. Ownership of this
handle is not transferred to CUDA after the import operation, so the application must
release the handle using the appropriate system call. If
cudaExternalSemaphoreHandleDesc::handle::win32::name is not NULL, then it must name a
valid synchronization object.
If cudaExternalSemaphoreHandleDesc::type is cudaExternalSemaphoreHandleTypeOpaqueWin32Kmt,
then cudaExternalSemaphoreHandleDesc::handle::win32::handle must be non-NULL and
cudaExternalSemaphoreHandleDesc::handle::win32::name must be NULL. The handle specified
must be a globally shared KMT handle. This handle does not hold a reference to the
underlying object, and thus will be invalid when all references to the synchronization
object are destroyed.
If cudaExternalSemaphoreHandleDesc::type is cudaExternalSemaphoreHandleTypeD3D12Fence,
then exactly one of cudaExternalSemaphoreHandleDesc::handle::win32::handle and
cudaExternalSemaphoreHandleDesc::handle::win32::name must not be NULL. If
cudaExternalSemaphoreHandleDesc::handle::win32::handle is not NULL, then it must represent
a valid shared NT handle that is returned by ID3DDevice::CreateSharedHandle when referring
to a ID3D12Fence object. This handle holds a reference to the underlying object. If
cudaExternalSemaphoreHandleDesc::handle::win32::name is not NULL, then it must name a
valid synchronization object that refers to a valid ID3D12Fence object.
Parameters:
extSem_out - Returned handle to an external semaphore
semHandleDesc - Semaphore import handle descriptor
Returns:
cudaSuccess, cudaErrorInvalidResourceHandle
Note:
Note that this function may also return error codes from previous, asynchronous
launches.
See also:
cudaDestroyExternalSemaphore, cudaSignalExternalSemaphoresAsync,
cudaWaitExternalSemaphoresAsync
cudaError_t cudaSignalExternalSemaphoresAsync (const cudaExternalSemaphore_t * extSemArray,
const struct cudaExternalSemaphoreSignalParams * paramsArray, unsigned int numExtSems,
cudaStream_t stream = 0)
Enqueues a signal operation on a set of externally allocated semaphore object in the
specified stream. The operations will be executed when all prior operations in the stream
complete.
The exact semantics of signaling a semaphore depends on the type of the object.
If the semaphore object is any one of the following types:
cudaExternalSemaphoreHandleTypeOpaqueFd, cudaExternalSemaphoreHandleTypeOpaqueWin32,
cudaExternalSemaphoreHandleTypeOpaqueWin32Kmt then signaling the semaphore will set it to
the signaled state.
If the semaphore object is of the type cudaExternalSemaphoreHandleTypeD3D12Fence, then the
semaphore will be set to the value specified in
cudaExternalSemaphoreSignalParams::params::fence::value.
Parameters:
extSemArray - Set of external semaphores to be signaled
paramsArray - Array of semaphore parameters
numExtSems - Number of semaphores to signal
stream - Stream to enqueue the signal operations in
Returns:
cudaSuccess, cudaErrorInvalidResourceHandle
Note:
Note that this function may also return error codes from previous, asynchronous
launches.
See also:
cudaImportExternalSemaphore, cudaDestroyExternalSemaphore,
cudaWaitExternalSemaphoresAsync
cudaError_t cudaWaitExternalSemaphoresAsync (const cudaExternalSemaphore_t * extSemArray,
const struct cudaExternalSemaphoreWaitParams * paramsArray, unsigned int numExtSems,
cudaStream_t stream = 0)
Enqueues a wait operation on a set of externally allocated semaphore object in the
specified stream. The operations will be executed when all prior operations in the stream
complete.
The exact semantics of waiting on a semaphore depends on the type of the object.
If the semaphore object is any one of the following types:
cudaExternalSemaphoreHandleTypeOpaqueFd, cudaExternalSemaphoreHandleTypeOpaqueWin32,
cudaExternalSemaphoreHandleTypeOpaqueWin32Kmt then waiting on the semaphore will wait
until the semaphore reaches the signaled state. The semaphore will then be reset to the
unsignaled state. Therefore for every signal operation, there can only be one wait
operation.
If the semaphore object is of the type cudaExternalSemaphoreHandleTypeD3D12Fence, then
waiting on the semaphore will wait until the value of the semaphore is greater than or
equal to cudaExternalSemaphoreWaitParams::params::fence::value.
Parameters:
extSemArray - External semaphores to be waited on
paramsArray - Array of semaphore parameters
numExtSems - Number of semaphores to wait on
stream - Stream to enqueue the wait operations in
Returns:
cudaSuccess, cudaErrorInvalidResourceHandle
Note:
Note that this function may also return error codes from previous, asynchronous
launches.
See also:
cudaImportExternalSemaphore, cudaDestroyExternalSemaphore,
cudaSignalExternalSemaphoresAsync
Author
Generated automatically by Doxygen from the source code.