.TH "External Resource Interoperability" 3 "24 Apr 2019" "Version 6.0" "Doxygen" \" -*- nroff -*-
.ad l
.nh
.SH NAME
External Resource Interoperability \- 
.SS "Functions"

.in +1c
.ti -1c
.RI "\fBcudaError_t\fP \fBcudaDestroyExternalMemory\fP (\fBcudaExternalMemory_t\fP extMem)"
.br
.RI "\fIDestroys an external memory object. \fP"
.ti -1c
.RI "\fBcudaError_t\fP \fBcudaDestroyExternalSemaphore\fP (\fBcudaExternalSemaphore_t\fP extSem)"
.br
.RI "\fIDestroys an external semaphore. \fP"
.ti -1c
.RI "\fBcudaError_t\fP \fBcudaExternalMemoryGetMappedBuffer\fP (void **devPtr, \fBcudaExternalMemory_t\fP extMem, const struct \fBcudaExternalMemoryBufferDesc\fP *bufferDesc)"
.br
.RI "\fIMaps a buffer onto an imported memory object. \fP"
.ti -1c
.RI "\fBcudaError_t\fP \fBcudaExternalMemoryGetMappedMipmappedArray\fP (\fBcudaMipmappedArray_t\fP *mipmap, \fBcudaExternalMemory_t\fP extMem, const struct \fBcudaExternalMemoryMipmappedArrayDesc\fP *mipmapDesc)"
.br
.RI "\fIMaps a CUDA mipmapped array onto an external memory object. \fP"
.ti -1c
.RI "\fBcudaError_t\fP \fBcudaImportExternalMemory\fP (\fBcudaExternalMemory_t\fP *extMem_out, const struct \fBcudaExternalMemoryHandleDesc\fP *memHandleDesc)"
.br
.RI "\fIImports an external memory object. \fP"
.ti -1c
.RI "\fBcudaError_t\fP \fBcudaImportExternalSemaphore\fP (\fBcudaExternalSemaphore_t\fP *extSem_out, const struct \fBcudaExternalSemaphoreHandleDesc\fP *semHandleDesc)"
.br
.RI "\fIImports an external semaphore. \fP"
.ti -1c
.RI "\fBcudaError_t\fP \fBcudaSignalExternalSemaphoresAsync\fP (const \fBcudaExternalSemaphore_t\fP *extSemArray, const struct \fBcudaExternalSemaphoreSignalParams\fP *paramsArray, unsigned int numExtSems, \fBcudaStream_t\fP stream=0)"
.br
.RI "\fISignals a set of external semaphore objects. \fP"
.ti -1c
.RI "\fBcudaError_t\fP \fBcudaWaitExternalSemaphoresAsync\fP (const \fBcudaExternalSemaphore_t\fP *extSemArray, const struct \fBcudaExternalSemaphoreWaitParams\fP *paramsArray, unsigned int numExtSems, \fBcudaStream_t\fP stream=0)"
.br
.RI "\fIWaits on a set of external semaphore objects. \fP"
.in -1c
.SH "Detailed Description"
.PP 
\\brief External resource interoperability functions of the CUDA runtime API (cuda_runtime_api.h)
.PP
This section describes the external resource interoperability functions of the CUDA runtime application programming interface. 
.SH "Function Documentation"
.PP 
.SS "\fBcudaError_t\fP cudaDestroyExternalMemory (\fBcudaExternalMemory_t\fP extMem)"
.PP
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 \fBcudaFree\fP and \fBcudaFreeMipmappedArray\fP respectively.
.PP
\fBParameters:\fP
.RS 4
\fIextMem\fP - External memory object to be destroyed
.RE
.PP
\fBReturns:\fP
.RS 4
\fBcudaSuccess\fP, \fBcudaErrorInvalidResourceHandle\fP 
.RE
.PP
\fBNote:\fP
.RS 4
Note that this function may also return error codes from previous, asynchronous launches.  
.RE
.PP
\fBSee also:\fP
.RS 4
\fBcudaImportExternalMemory\fP \fBcudaExternalMemoryGetMappedBuffer\fP, \fBcudaExternalMemoryGetMappedMipmappedArray\fP 
.RE
.PP

.SS "\fBcudaError_t\fP cudaDestroyExternalSemaphore (\fBcudaExternalSemaphore_t\fP extSem)"
.PP
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.
.PP
\fBParameters:\fP
.RS 4
\fIextSem\fP - External semaphore to be destroyed
.RE
.PP
\fBReturns:\fP
.RS 4
\fBcudaSuccess\fP, \fBcudaErrorInvalidResourceHandle\fP 
.RE
.PP
\fBNote:\fP
.RS 4
Note that this function may also return error codes from previous, asynchronous launches.  
.RE
.PP
\fBSee also:\fP
.RS 4
\fBcudaImportExternalSemaphore\fP, \fBcudaSignalExternalSemaphoresAsync\fP, \fBcudaWaitExternalSemaphoresAsync\fP 
.RE
.PP

.SS "\fBcudaError_t\fP cudaExternalMemoryGetMappedBuffer (void ** devPtr, \fBcudaExternalMemory_t\fP extMem, const struct \fBcudaExternalMemoryBufferDesc\fP * bufferDesc)"
.PP
Maps a buffer onto an imported memory object and returns a device pointer in \fCdevPtr\fP.
.PP
The properties of the buffer being mapped must be described in \fCbufferDesc\fP. The \fBcudaExternalMemoryBufferDesc\fP structure is defined as follows:
.PP
.PP
.nf
        typedef struct cudaExternalMemoryBufferDesc_st {
            unsigned long long offset;
            unsigned long long size;
            unsigned int flags;
        } cudaExternalMemoryBufferDesc;
.fi
.PP
.PP
where \fBcudaExternalMemoryBufferDesc::offset\fP is the offset in the memory object where the buffer's base address is. \fBcudaExternalMemoryBufferDesc::size\fP is the size of the buffer. cudaExternalMemoryBufferDesc::flags must be zero.
.PP
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.
.PP
The returned pointer \fCdevPtr\fP must be freed using \fBcudaFree\fP.
.PP
\fBParameters:\fP
.RS 4
\fIdevPtr\fP - Returned device pointer to buffer 
.br
\fIextMem\fP - Handle to external memory object 
.br
\fIbufferDesc\fP - Buffer descriptor
.RE
.PP
\fBReturns:\fP
.RS 4
\fBcudaSuccess\fP, \fBcudaErrorInvalidResourceHandle\fP 
.RE
.PP
\fBNote:\fP
.RS 4
Note that this function may also return error codes from previous, asynchronous launches.  
.RE
.PP
\fBSee also:\fP
.RS 4
\fBcudaImportExternalMemory\fP \fBcudaDestroyExternalMemory\fP, \fBcudaExternalMemoryGetMappedMipmappedArray\fP 
.RE
.PP

.SS "\fBcudaError_t\fP cudaExternalMemoryGetMappedMipmappedArray (\fBcudaMipmappedArray_t\fP * mipmap, \fBcudaExternalMemory_t\fP extMem, const struct \fBcudaExternalMemoryMipmappedArrayDesc\fP * mipmapDesc)"
.PP
Maps a CUDA mipmapped array onto an external object and returns a handle to it in \fCmipmap\fP.
.PP
The properties of the CUDA mipmapped array being mapped must be described in \fCmipmapDesc\fP. The structure \fBcudaExternalMemoryMipmappedArrayDesc\fP is defined as follows:
.PP
.PP
.nf
        typedef struct cudaExternalMemoryMipmappedArrayDesc_st {
            unsigned long long offset;
            cudaChannelFormatDesc formatDesc;
            cudaExtent extent;
            unsigned int flags;
            unsigned int numLevels;
        } cudaExternalMemoryMipmappedArrayDesc;
.fi
.PP
.PP
where \fBcudaExternalMemoryMipmappedArrayDesc::offset\fP is the offset in the memory object where the base level of the mipmap chain is. \fBcudaExternalMemoryMipmappedArrayDesc::formatDesc\fP 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 \fBcudaMalloc3DArray\fP. Note that if the mipmapped array is bound as a color target in the graphics API, then the flag \fBcudaArrayColorAttachment\fP must be specified in cudaExternalMemoryMipmappedArrayDesc::flags. \fBcudaExternalMemoryMipmappedArrayDesc::numLevels\fP specifies the total number of levels in the mipmap chain.
.PP
The returned CUDA mipmapped array must be freed using \fBcudaFreeMipmappedArray\fP.
.PP
\fBParameters:\fP
.RS 4
\fImipmap\fP - Returned CUDA mipmapped array 
.br
\fIextMem\fP - Handle to external memory object 
.br
\fImipmapDesc\fP - CUDA array descriptor
.RE
.PP
\fBReturns:\fP
.RS 4
\fBcudaSuccess\fP, \fBcudaErrorInvalidResourceHandle\fP 
.RE
.PP
\fBNote:\fP
.RS 4
Note that this function may also return error codes from previous, asynchronous launches.  
.RE
.PP
\fBSee also:\fP
.RS 4
\fBcudaImportExternalMemory\fP \fBcudaDestroyExternalMemory\fP, \fBcudaExternalMemoryGetMappedBuffer\fP 
.RE
.PP

.SS "\fBcudaError_t\fP cudaImportExternalMemory (\fBcudaExternalMemory_t\fP * extMem_out, const struct \fBcudaExternalMemoryHandleDesc\fP * memHandleDesc)"
.PP
Imports an externally allocated memory object and returns a handle to that in \fCextMem_out\fP.
.PP
The properties of the handle being imported must be described in \fCmemHandleDesc\fP. The \fBcudaExternalMemoryHandleDesc\fP structure is defined as follows:
.PP
.PP
.nf
        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;
.fi
.PP
.PP
where \fBcudaExternalMemoryHandleDesc::type\fP specifies the type of handle being imported. \fBcudaExternalMemoryHandleType\fP is defined as:
.PP
.PP
.nf
        typedef enum cudaExternalMemoryHandleType_enum {
            cudaExternalMemoryHandleTypeOpaqueFd        = 1,
            cudaExternalMemoryHandleTypeOpaqueWin32     = 2,
            cudaExternalMemoryHandleTypeOpaqueWin32Kmt  = 3,
            cudaExternalMemoryHandleTypeD3D12Heap       = 4,
            cudaExternalMemoryHandleTypeD3D12Resource   = 5
        } cudaExternalMemoryHandleType;
.fi
.PP
.PP
If \fBcudaExternalMemoryHandleDesc::type\fP is \fBcudaExternalMemoryHandleTypeOpaqueFd\fP, 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.
.PP
If \fBcudaExternalMemoryHandleDesc::type\fP is \fBcudaExternalMemoryHandleTypeOpaqueWin32\fP, 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.
.PP
If \fBcudaExternalMemoryHandleDesc::type\fP is \fBcudaExternalMemoryHandleTypeOpaqueWin32Kmt\fP, 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.
.PP
If \fBcudaExternalMemoryHandleDesc::type\fP is \fBcudaExternalMemoryHandleTypeD3D12Heap\fP, 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.
.PP
If \fBcudaExternalMemoryHandleDesc::type\fP is \fBcudaExternalMemoryHandleTypeD3D12Resource\fP, 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.
.PP
The size of the memory object must be specified in \fBcudaExternalMemoryHandleDesc::size\fP.
.PP
Specifying the flag \fBcudaExternalMemoryDedicated\fP 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.
.PP
\fBParameters:\fP
.RS 4
\fIextMem_out\fP - Returned handle to an external memory object 
.br
\fImemHandleDesc\fP - Memory import handle descriptor
.RE
.PP
\fBReturns:\fP
.RS 4
\fBcudaSuccess\fP, \fBcudaErrorInvalidResourceHandle\fP 
.RE
.PP
\fBNote:\fP
.RS 4
Note that this function may also return error codes from previous, asynchronous launches.  
.PP
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.
.RE
.PP
\fBSee also:\fP
.RS 4
\fBcudaDestroyExternalMemory\fP, \fBcudaExternalMemoryGetMappedBuffer\fP, \fBcudaExternalMemoryGetMappedMipmappedArray\fP 
.RE
.PP

.SS "\fBcudaError_t\fP cudaImportExternalSemaphore (\fBcudaExternalSemaphore_t\fP * extSem_out, const struct \fBcudaExternalSemaphoreHandleDesc\fP * semHandleDesc)"
.PP
Imports an externally allocated synchronization object and returns a handle to that in \fCextSem_out\fP.
.PP
The properties of the handle being imported must be described in \fCsemHandleDesc\fP. The \fBcudaExternalSemaphoreHandleDesc\fP is defined as follows:
.PP
.PP
.nf
        typedef struct cudaExternalSemaphoreHandleDesc_st {
            cudaExternalSemaphoreHandleType type;
            union {
                int fd;
                struct {
                    void *handle;
                    const void *name;
                } win32;
            } handle;
            unsigned int flags;
        } cudaExternalSemaphoreHandleDesc;
.fi
.PP
.PP
where \fBcudaExternalSemaphoreHandleDesc::type\fP specifies the type of handle being imported. \fBcudaExternalSemaphoreHandleType\fP is defined as:
.PP
.PP
.nf
        typedef enum cudaExternalSemaphoreHandleType_enum {
            cudaExternalSemaphoreHandleTypeOpaqueFd       = 1,
            cudaExternalSemaphoreHandleTypeOpaqueWin32    = 2,
            cudaExternalSemaphoreHandleTypeOpaqueWin32Kmt = 3,
            cudaExternalSemaphoreHandleTypeD3D12Fence     = 4
        } cudaExternalSemaphoreHandleType;
.fi
.PP
.PP
If \fBcudaExternalSemaphoreHandleDesc::type\fP is \fBcudaExternalSemaphoreHandleTypeOpaqueFd\fP, 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.
.PP
If \fBcudaExternalSemaphoreHandleDesc::type\fP is \fBcudaExternalSemaphoreHandleTypeOpaqueWin32\fP, 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.
.PP
If \fBcudaExternalSemaphoreHandleDesc::type\fP is \fBcudaExternalSemaphoreHandleTypeOpaqueWin32Kmt\fP, 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.
.PP
If \fBcudaExternalSemaphoreHandleDesc::type\fP is \fBcudaExternalSemaphoreHandleTypeD3D12Fence\fP, 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.
.PP
\fBParameters:\fP
.RS 4
\fIextSem_out\fP - Returned handle to an external semaphore 
.br
\fIsemHandleDesc\fP - Semaphore import handle descriptor
.RE
.PP
\fBReturns:\fP
.RS 4
\fBcudaSuccess\fP, \fBcudaErrorInvalidResourceHandle\fP 
.RE
.PP
\fBNote:\fP
.RS 4
Note that this function may also return error codes from previous, asynchronous launches.  
.RE
.PP
\fBSee also:\fP
.RS 4
\fBcudaDestroyExternalSemaphore\fP, \fBcudaSignalExternalSemaphoresAsync\fP, \fBcudaWaitExternalSemaphoresAsync\fP 
.RE
.PP

.SS "\fBcudaError_t\fP cudaSignalExternalSemaphoresAsync (const \fBcudaExternalSemaphore_t\fP * extSemArray, const struct \fBcudaExternalSemaphoreSignalParams\fP * paramsArray, unsigned int numExtSems, \fBcudaStream_t\fP stream = \fC0\fP)"
.PP
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.
.PP
The exact semantics of signaling a semaphore depends on the type of the object.
.PP
If the semaphore object is any one of the following types: \fBcudaExternalSemaphoreHandleTypeOpaqueFd\fP, \fBcudaExternalSemaphoreHandleTypeOpaqueWin32\fP, \fBcudaExternalSemaphoreHandleTypeOpaqueWin32Kmt\fP then signaling the semaphore will set it to the signaled state.
.PP
If the semaphore object is of the type \fBcudaExternalSemaphoreHandleTypeD3D12Fence\fP, then the semaphore will be set to the value specified in cudaExternalSemaphoreSignalParams::params::fence::value.
.PP
\fBParameters:\fP
.RS 4
\fIextSemArray\fP - Set of external semaphores to be signaled 
.br
\fIparamsArray\fP - Array of semaphore parameters 
.br
\fInumExtSems\fP - Number of semaphores to signal 
.br
\fIstream\fP - Stream to enqueue the signal operations in
.RE
.PP
\fBReturns:\fP
.RS 4
\fBcudaSuccess\fP, \fBcudaErrorInvalidResourceHandle\fP 
.RE
.PP
\fBNote:\fP
.RS 4
Note that this function may also return error codes from previous, asynchronous launches.  
.RE
.PP
\fBSee also:\fP
.RS 4
\fBcudaImportExternalSemaphore\fP, \fBcudaDestroyExternalSemaphore\fP, \fBcudaWaitExternalSemaphoresAsync\fP 
.RE
.PP

.SS "\fBcudaError_t\fP cudaWaitExternalSemaphoresAsync (const \fBcudaExternalSemaphore_t\fP * extSemArray, const struct \fBcudaExternalSemaphoreWaitParams\fP * paramsArray, unsigned int numExtSems, \fBcudaStream_t\fP stream = \fC0\fP)"
.PP
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.
.PP
The exact semantics of waiting on a semaphore depends on the type of the object.
.PP
If the semaphore object is any one of the following types: \fBcudaExternalSemaphoreHandleTypeOpaqueFd\fP, \fBcudaExternalSemaphoreHandleTypeOpaqueWin32\fP, \fBcudaExternalSemaphoreHandleTypeOpaqueWin32Kmt\fP 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.
.PP
If the semaphore object is of the type \fBcudaExternalSemaphoreHandleTypeD3D12Fence\fP, then waiting on the semaphore will wait until the value of the semaphore is greater than or equal to cudaExternalSemaphoreWaitParams::params::fence::value.
.PP
\fBParameters:\fP
.RS 4
\fIextSemArray\fP - External semaphores to be waited on 
.br
\fIparamsArray\fP - Array of semaphore parameters 
.br
\fInumExtSems\fP - Number of semaphores to wait on 
.br
\fIstream\fP - Stream to enqueue the wait operations in
.RE
.PP
\fBReturns:\fP
.RS 4
\fBcudaSuccess\fP, \fBcudaErrorInvalidResourceHandle\fP 
.RE
.PP
\fBNote:\fP
.RS 4
Note that this function may also return error codes from previous, asynchronous launches.  
.RE
.PP
\fBSee also:\fP
.RS 4
\fBcudaImportExternalSemaphore\fP, \fBcudaDestroyExternalSemaphore\fP, \fBcudaSignalExternalSemaphoresAsync\fP 
.RE
.PP

.SH "Author"
.PP 
Generated automatically by Doxygen from the source code.