Provided by: nvidia-cuda-dev_10.1.243-3_amd64 bug

NAME

       External Resource Interoperability -

   Functions
       CUresult cuDestroyExternalMemory (CUexternalMemory extMem)
           Destroys an external memory object.
       CUresult cuDestroyExternalSemaphore (CUexternalSemaphore extSem)
           Destroys an external semaphore.
       CUresult cuExternalMemoryGetMappedBuffer (CUdeviceptr *devPtr, CUexternalMemory extMem,
           const CUDA_EXTERNAL_MEMORY_BUFFER_DESC *bufferDesc)
           Maps a buffer onto an imported memory object.
       CUresult cuExternalMemoryGetMappedMipmappedArray (CUmipmappedArray *mipmap,
           CUexternalMemory extMem, const CUDA_EXTERNAL_MEMORY_MIPMAPPED_ARRAY_DESC *mipmapDesc)
           Maps a CUDA mipmapped array onto an external memory object.
       CUresult cuImportExternalMemory (CUexternalMemory *extMem_out, const
           CUDA_EXTERNAL_MEMORY_HANDLE_DESC *memHandleDesc)
           Imports an external memory object.
       CUresult cuImportExternalSemaphore (CUexternalSemaphore *extSem_out, const
           CUDA_EXTERNAL_SEMAPHORE_HANDLE_DESC *semHandleDesc)
           Imports an external semaphore.
       CUresult cuSignalExternalSemaphoresAsync (const CUexternalSemaphore *extSemArray, const
           CUDA_EXTERNAL_SEMAPHORE_SIGNAL_PARAMS *paramsArray, unsigned int numExtSems, CUstream
           stream)
           Signals a set of external semaphore objects.
       CUresult cuWaitExternalSemaphoresAsync (const CUexternalSemaphore *extSemArray, const
           CUDA_EXTERNAL_SEMAPHORE_WAIT_PARAMS *paramsArray, unsigned int numExtSems, CUstream
           stream)
           Waits on a set of external semaphore objects.

Detailed Description

       \brief External resource interoperability functions of the low-level CUDA driver API
       (cuda.h)

       This section describes the external resource interoperability functions of the low-level
       CUDA driver application programming interface.

Function Documentation

   CUresult cuDestroyExternalMemory (CUexternalMemory 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
       cuMemFree and cuMipmappedArrayDestroy respectively.

       Parameters:
           extMem - External memory object to be destroyed

       Returns:
           CUDA_SUCCESS, CUDA_ERROR_NOT_INITIALIZED, CUDA_ERROR_INVALID_HANDLE

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

       See also:
           cuImportExternalMemory cuExternalMemoryGetMappedBuffer,
           cuExternalMemoryGetMappedMipmappedArray

   CUresult cuDestroyExternalSemaphore (CUexternalSemaphore 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:
           CUDA_SUCCESS, CUDA_ERROR_NOT_INITIALIZED, CUDA_ERROR_INVALID_HANDLE

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

       See also:
           cuImportExternalSemaphore, cuSignalExternalSemaphoresAsync,
           cuWaitExternalSemaphoresAsync

   CUresult cuExternalMemoryGetMappedBuffer (CUdeviceptr * devPtr, CUexternalMemory extMem, const
       CUDA_EXTERNAL_MEMORY_BUFFER_DESC * 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
       CUDA_EXTERNAL_MEMORY_BUFFER_DESC structure is defined as follows:

               typedef struct CUDA_EXTERNAL_MEMORY_BUFFER_DESC_st {
                   unsigned long long offset;
                   unsigned long long size;
                   unsigned int flags;
               } CUDA_EXTERNAL_MEMORY_BUFFER_DESC;

       where CUDA_EXTERNAL_MEMORY_BUFFER_DESC::offset is the offset in the memory object where
       the buffer's base address is. CUDA_EXTERNAL_MEMORY_BUFFER_DESC::size is the size of the
       buffer. CUDA_EXTERNAL_MEMORY_BUFFER_DESC::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 cuMemFree.

       Parameters:
           devPtr - Returned device pointer to buffer
           extMem - Handle to external memory object
           bufferDesc - Buffer descriptor

       Returns:
           CUDA_SUCCESS, CUDA_ERROR_NOT_INITIALIZED, CUDA_ERROR_INVALID_HANDLE

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

       See also:
           cuImportExternalMemory cuDestroyExternalMemory,
           cuExternalMemoryGetMappedMipmappedArray

   CUresult cuExternalMemoryGetMappedMipmappedArray (CUmipmappedArray * mipmap, CUexternalMemory
       extMem, const CUDA_EXTERNAL_MEMORY_MIPMAPPED_ARRAY_DESC * 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 CUDA_EXTERNAL_MEMORY_MIPMAPPED_ARRAY_DESC is defined as follows:

               typedef struct CUDA_EXTERNAL_MEMORY_MIPMAPPED_ARRAY_DESC_st {
                   unsigned long long offset;
                   CUDA_ARRAY3D_DESCRIPTOR arrayDesc;
                   unsigned int numLevels;
               } CUDA_EXTERNAL_MEMORY_MIPMAPPED_ARRAY_DESC;

       where CUDA_EXTERNAL_MEMORY_MIPMAPPED_ARRAY_DESC::offset is the offset in the memory object
       where the base level of the mipmap chain is.
       CUDA_EXTERNAL_MEMORY_MIPMAPPED_ARRAY_DESC::arrayDesc describes the format, dimensions and
       type of the base level of the mipmap chain. For further details on these parameters,
       please refer to the documentation for cuMipmappedArrayCreate. Note that if the mipmapped
       array is bound as a color target in the graphics API, then the flag
       CUDA_ARRAY3D_COLOR_ATTACHMENT must be specified in
       CUDA_EXTERNAL_MEMORY_MIPMAPPED_ARRAY_DESC::arrayDesc::Flags.
       CUDA_EXTERNAL_MEMORY_MIPMAPPED_ARRAY_DESC::numLevels specifies the total number of levels
       in the mipmap chain.

       The returned CUDA mipmapped array must be freed using cuMipmappedArrayDestroy.

       Parameters:
           mipmap - Returned CUDA mipmapped array
           extMem - Handle to external memory object
           mipmapDesc - CUDA array descriptor

       Returns:
           CUDA_SUCCESS, CUDA_ERROR_NOT_INITIALIZED, CUDA_ERROR_INVALID_HANDLE

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

       See also:
           cuImportExternalMemory cuDestroyExternalMemory, cuExternalMemoryGetMappedBuffer

   CUresult cuImportExternalMemory (CUexternalMemory * extMem_out, const
       CUDA_EXTERNAL_MEMORY_HANDLE_DESC * 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
       CUDA_EXTERNAL_MEMORY_HANDLE_DESC structure is defined as follows:

               typedef struct CUDA_EXTERNAL_MEMORY_HANDLE_DESC_st {
                   CUexternalMemoryHandleType type;
                   union {
                       int fd;
                       struct {
                           void *handle;
                           const void *name;
                       } win32;
                   } handle;
                   unsigned long long size;
                   unsigned int flags;
               } CUDA_EXTERNAL_MEMORY_HANDLE_DESC;

       where CUDA_EXTERNAL_MEMORY_HANDLE_DESC::type specifies the type of handle being imported.
       CUexternalMemoryHandleType is defined as:

               typedef enum CUexternalMemoryHandleType_enum {
                   CU_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_FD        = 1,
                   CU_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32     = 2,
                   CU_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_KMT = 3,
                   CU_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_HEAP       = 4,
                   CU_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_RESOURCE   = 5
               } CUexternalMemoryHandleType;

       If CUDA_EXTERNAL_MEMORY_HANDLE_DESC::type is CU_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_FD,
       then CUDA_EXTERNAL_MEMORY_HANDLE_DESC::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 CUDA_EXTERNAL_MEMORY_HANDLE_DESC::type is CU_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32,
       then exactly one of CUDA_EXTERNAL_MEMORY_HANDLE_DESC::handle::win32::handle and
       CUDA_EXTERNAL_MEMORY_HANDLE_DESC::handle::win32::name must not be NULL. If
       CUDA_EXTERNAL_MEMORY_HANDLE_DESC::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
       CUDA_EXTERNAL_MEMORY_HANDLE_DESC::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 CUDA_EXTERNAL_MEMORY_HANDLE_DESC::type is
       CU_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_KMT, then
       CUDA_EXTERNAL_MEMORY_HANDLE_DESC::handle::win32::handle must be non-NULL and
       CUDA_EXTERNAL_MEMORY_HANDLE_DESC::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 CUDA_EXTERNAL_MEMORY_HANDLE_DESC::type is CU_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_HEAP,
       then exactly one of CUDA_EXTERNAL_MEMORY_HANDLE_DESC::handle::win32::handle and
       CUDA_EXTERNAL_MEMORY_HANDLE_DESC::handle::win32::name must not be NULL. If
       CUDA_EXTERNAL_MEMORY_HANDLE_DESC::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 CUDA_EXTERNAL_MEMORY_HANDLE_DESC::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 CUDA_EXTERNAL_MEMORY_HANDLE_DESC::type is
       CU_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_RESOURCE, then exactly one of
       CUDA_EXTERNAL_MEMORY_HANDLE_DESC::handle::win32::handle and
       CUDA_EXTERNAL_MEMORY_HANDLE_DESC::handle::win32::name must not be NULL. If
       CUDA_EXTERNAL_MEMORY_HANDLE_DESC::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 CUDA_EXTERNAL_MEMORY_HANDLE_DESC::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 CUDA_EXTERNAL_MEMORY_HANDLE_DESC::size.

       Specifying the flag CUDA_EXTERNAL_MEMORY_DEDICATED in
       CUDA_EXTERNAL_MEMORY_HANDLE_DESC::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:
           CUDA_SUCCESS, CUDA_ERROR_NOT_INITIALIZED, CUDA_ERROR_INVALID_HANDLE

       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:
           cuDestroyExternalMemory, cuExternalMemoryGetMappedBuffer,
           cuExternalMemoryGetMappedMipmappedArray

   CUresult cuImportExternalSemaphore (CUexternalSemaphore * extSem_out, const
       CUDA_EXTERNAL_SEMAPHORE_HANDLE_DESC * 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
       CUDA_EXTERNAL_SEMAPHORE_HANDLE_DESC is defined as follows:

               typedef struct CUDA_EXTERNAL_SEMAPHORE_HANDLE_DESC_st {
                   CUexternalSemaphoreHandleType type;
                   union {
                       int fd;
                       struct {
                           void *handle;
                           const void *name;
                       } win32;
                   } handle;
                   unsigned int flags;
               } CUDA_EXTERNAL_SEMAPHORE_HANDLE_DESC;

       where CUDA_EXTERNAL_SEMAPHORE_HANDLE_DESC::type specifies the type of handle being
       imported. CUexternalSemaphoreHandleType is defined as:

               typedef enum CUexternalSemaphoreHandleType_enum {
                   CU_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_FD        = 1,
                   CU_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32     = 2,
                   CU_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32_KMT = 3,
                   CU_EXTERNAL_SEMAPHORE_HANDLE_TYPE_D3D12_FENCE      = 4
               } CUexternalSemaphoreHandleType;

       If CUDA_EXTERNAL_SEMAPHORE_HANDLE_DESC::type is
       CU_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_FD, then
       CUDA_EXTERNAL_SEMAPHORE_HANDLE_DESC::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 CUDA_EXTERNAL_SEMAPHORE_HANDLE_DESC::type is
       CU_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32, then exactly one of
       CUDA_EXTERNAL_SEMAPHORE_HANDLE_DESC::handle::win32::handle and
       CUDA_EXTERNAL_SEMAPHORE_HANDLE_DESC::handle::win32::name must not be NULL. If
       CUDA_EXTERNAL_SEMAPHORE_HANDLE_DESC::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
       CUDA_EXTERNAL_SEMAPHORE_HANDLE_DESC::handle::win32::name is not NULL, then it must name a
       valid synchronization object.

       If CUDA_EXTERNAL_SEMAPHORE_HANDLE_DESC::type is
       CU_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32_KMT, then
       CUDA_EXTERNAL_SEMAPHORE_HANDLE_DESC::handle::win32::handle must be non-NULL and
       CUDA_EXTERNAL_SEMAPHORE_HANDLE_DESC::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 CUDA_EXTERNAL_SEMAPHORE_HANDLE_DESC::type is
       CU_EXTERNAL_SEMAPHORE_HANDLE_TYPE_D3D12_FENCE, then exactly one of
       CUDA_EXTERNAL_SEMAPHORE_HANDLE_DESC::handle::win32::handle and
       CUDA_EXTERNAL_SEMAPHORE_HANDLE_DESC::handle::win32::name must not be NULL. If
       CUDA_EXTERNAL_SEMAPHORE_HANDLE_DESC::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 CUDA_EXTERNAL_SEMAPHORE_HANDLE_DESC::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:
           CUDA_SUCCESS, CUDA_ERROR_NOT_INITIALIZED, CUDA_ERROR_INVALID_HANDLE

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

       See also:
           cuDestroyExternalSemaphore, cuSignalExternalSemaphoresAsync,
           cuWaitExternalSemaphoresAsync

   CUresult cuSignalExternalSemaphoresAsync (const CUexternalSemaphore * extSemArray, const
       CUDA_EXTERNAL_SEMAPHORE_SIGNAL_PARAMS * paramsArray, unsigned int numExtSems, CUstream
       stream)
       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:
       CU_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_FD,
       CU_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32,
       CU_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32_KMT then signaling the semaphore will set
       it to the signaled state.

       If the semaphore object is of the type CU_EXTERNAL_SEMAPHORE_HANDLE_TYPE_D3D12_FENCE, then
       the semaphore will be set to the value specified in
       CUDA_EXTERNAL_SEMAPHORE_SIGNAL_PARAMS::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:
           CUDA_SUCCESS, CUDA_ERROR_NOT_INITIALIZED, CUDA_ERROR_INVALID_HANDLE

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

       See also:
           cuImportExternalSemaphore, cuDestroyExternalSemaphore, cuWaitExternalSemaphoresAsync

   CUresult cuWaitExternalSemaphoresAsync (const CUexternalSemaphore * extSemArray, const
       CUDA_EXTERNAL_SEMAPHORE_WAIT_PARAMS * paramsArray, unsigned int numExtSems, CUstream
       stream)
       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:
       CU_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_FD,
       CU_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32,
       CU_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32_KMT 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 CU_EXTERNAL_SEMAPHORE_HANDLE_TYPE_D3D12_FENCE, then
       waiting on the semaphore will wait until the value of the semaphore is greater than or
       equal to CUDA_EXTERNAL_SEMAPHORE_WAIT_PARAMS::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:
           CUDA_SUCCESS, CUDA_ERROR_NOT_INITIALIZED, CUDA_ERROR_INVALID_HANDLE

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

       See also:
           cuImportExternalSemaphore, cuDestroyExternalSemaphore, cuSignalExternalSemaphoresAsync

Author

       Generated automatically by Doxygen from the source code.