CUDA Driver API. API Reference Manual (January 2024) - page 9

 

  Index      Manuals     CUDA Driver API. API Reference Manual (January 2024)

 

Search            copyright infringement  

 

   

 

    

 

Content      ..     7      8      9      10     ..

 

 

 

CUDA Driver API. API Reference Manual (January 2024) - page 9

 

 

Modules
CUresult cuDeviceGetP2PAttribute (int *value,
CUdevice_P2PAttribute attrib, CUdevice srcDevice,
CUdevice dstDevice)
Queries attributes of the link between two devices.
Parameters
value
- Returned value of the requested attribute
attrib
- The requested attribute of the link between srcDevice and dstDevice.
srcDevice
- The source device of the target link.
dstDevice
- The destination device of the target link.
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_DEVICE, CUDA_ERROR_INVALID_VALUE
Description
Returns in *value the value of the requested attribute attrib of the link between srcDevice and
dstDevice. The supported attributes are:
‣ CU_DEVICE_P2P_ATTRIBUTE_PERFORMANCE_RANK: A relative value indicating the
performance of the link between two devices.
‣ CU_DEVICE_P2P_ATTRIBUTE_ACCESS_SUPPORTED P2P: 1 if P2P Access is enable.
‣ CU_DEVICE_P2P_ATTRIBUTE_NATIVE_ATOMIC_SUPPORTED: 1 if Atomic operations
over the link are supported.
‣ CU_DEVICE_P2P_ATTRIBUTE_CUDA_ARRAY_ACCESS_SUPPORTED: 1 if cudaArray can
be accessed over the link.
Returns CUDA_ERROR_INVALID_DEVICE if srcDevice or dstDevice are not valid or if they
represent the same device.
Returns CUDA_ERROR_INVALID_VALUE if attrib is not valid or if value is a null pointer.
Note:
Note that this function may also return error codes from previous, asynchronous launches.
See also:
|
562
Modules
cuCtxEnablePeerAccess, cuCtxDisablePeerAccess, cuDeviceCanAccessPeer,
cudaDeviceGetP2PAttribute
6.32. Graphics Interoperability
This section describes the graphics interoperability functions of the low-level CUDA driver application
programming interface.
CUresult cuGraphicsMapResources (unsigned int count,
CUgraphicsResource *resources, CUstream hStream)
Map graphics resources for access by CUDA.
Parameters
count
- Number of resources to map
resources
- Resources to map for CUDA usage
hStream
- Stream with which to synchronize
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_HANDLE,
CUDA_ERROR_ALREADY_MAPPED, CUDA_ERROR_UNKNOWN
Description
Maps the count graphics resources in resources for access by CUDA.
The resources in resources may be accessed by CUDA until they are unmapped. The graphics API
from which resources were registered should not access any resources while they are mapped by
CUDA. If an application does so, the results are undefined.
This function provides the synchronization guarantee that any graphics calls issued before
cuGraphicsMapResources() will complete before any subsequent CUDA work issued in stream
begins.
If resources includes any duplicate entries then CUDA_ERROR_INVALID_HANDLE
is returned. If any of resources are presently mapped for access by CUDA then
CUDA_ERROR_ALREADY_MAPPED is returned.
Note:
|
563
Modules
‣ This function uses standard default stream semantics.
‣ Note that this function may also return error codes from previous, asynchronous launches.
See also:
cuGraphicsResourceGetMappedPointer, cuGraphicsSubResourceGetMappedArray,
cuGraphicsUnmapResources, cudaGraphicsMapResources
CUresult cuGraphicsResourceGetMappedMipmappedArray
(CUmipmappedArray *pMipmappedArray,
CUgraphicsResource resource)
Get a mipmapped array through which to access a mapped graphics resource.
Parameters
pMipmappedArray
- Returned mipmapped array through which resource may be accessed
resource
- Mapped resource to access
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_VALUE,
CUDA_ERROR_INVALID_HANDLE, CUDA_ERROR_NOT_MAPPED,
CUDA_ERROR_NOT_MAPPED_AS_ARRAY
Description
Returns in *pMipmappedArray a mipmapped array through which the mapped graphics resource
resource. The value set in *pMipmappedArray may change every time that resource is
mapped.
If resource is not a texture then it cannot be accessed via a mipmapped array and
CUDA_ERROR_NOT_MAPPED_AS_ARRAY is returned. If resource is not mapped then
CUDA_ERROR_NOT_MAPPED is returned.
Note:
Note that this function may also return error codes from previous, asynchronous launches.
See also:
cuGraphicsResourceGetMappedPointer, cudaGraphicsResourceGetMappedMipmappedArray
|
564
Modules
CUresult cuGraphicsResourceGetMappedPointer
(CUdeviceptr *pDevPtr, size_t *pSize,
CUgraphicsResource resource)
Get a device pointer through which to access a mapped graphics resource.
Parameters
pDevPtr
- Returned pointer through which resource may be accessed
pSize
- Returned size of the buffer accessible starting at *pPointer
resource
- Mapped resource to access
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_VALUE,
CUDA_ERROR_INVALID_HANDLE, CUDA_ERROR_NOT_MAPPED,
CUDA_ERROR_NOT_MAPPED_AS_POINTER
Description
Returns in *pDevPtr a pointer through which the mapped graphics resource resource may be
accessed. Returns in pSize the size of the memory in bytes which may be accessed from that pointer.
The value set in pPointer may change every time that resource is mapped.
If resource is not a buffer then it cannot be accessed via a pointer and
CUDA_ERROR_NOT_MAPPED_AS_POINTER is returned. If resource is not mapped then
CUDA_ERROR_NOT_MAPPED is returned. *
Note:
Note that this function may also return error codes from previous, asynchronous launches.
See also:
cuGraphicsMapResources, cuGraphicsSubResourceGetMappedArray,
cudaGraphicsResourceGetMappedPointer
|
565
Modules
CUresult cuGraphicsResourceSetMapFlags
(CUgraphicsResource resource, unsigned int flags)
Set usage flags for mapping a graphics resource.
Parameters
resource
- Registered resource to set flags for
flags
- Parameters for resource mapping
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_VALUE,
CUDA_ERROR_INVALID_HANDLE, CUDA_ERROR_ALREADY_MAPPED
Description
Set flags for mapping the graphics resource resource.
Changes to flags will take effect the next time resource is mapped. The flags argument may be
any of the following:
‣ CU_GRAPHICS_MAP_RESOURCE_FLAGS_NONE: Specifies no hints about how this resource
will be used. It is therefore assumed that this resource will be read from and written to by CUDA
kernels. This is the default value.
‣ CU_GRAPHICS_MAP_RESOURCE_FLAGS_READONLY: Specifies that CUDA kernels which
access this resource will not write to this resource.
‣ CU_GRAPHICS_MAP_RESOURCE_FLAGS_WRITEDISCARD: Specifies that CUDA kernels
which access this resource will not read from this resource and will write over the entire contents of
the resource, so none of the data previously stored in the resource will be preserved.
If resource is presently mapped for access by CUDA then CUDA_ERROR_ALREADY_MAPPED
is returned. If flags is not one of the above values then CUDA_ERROR_INVALID_VALUE is
returned.
Note:
Note that this function may also return error codes from previous, asynchronous launches.
See also:
cuGraphicsMapResources, cudaGraphicsResourceSetMapFlags
|
566
Modules
CUresult cuGraphicsSubResourceGetMappedArray
(CUarray *pArray, CUgraphicsResource resource,
unsigned int arrayIndex, unsigned int mipLevel)
Get an array through which to access a subresource of a mapped graphics resource.
Parameters
pArray
- Returned array through which a subresource of resource may be accessed
resource
- Mapped resource to access
arrayIndex
- Array index for array textures or cubemap face index as defined by CUarray_cubemap_face for
cubemap textures for the subresource to access
mipLevel
- Mipmap level for the subresource to access
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_VALUE,
CUDA_ERROR_INVALID_HANDLE, CUDA_ERROR_NOT_MAPPED,
CUDA_ERROR_NOT_MAPPED_AS_ARRAY
Description
Returns in *pArray an array through which the subresource of the mapped graphics resource
resource which corresponds to array index arrayIndex and mipmap level mipLevel may be
accessed. The value set in *pArray may change every time that resource is mapped.
If resource is not a texture then it cannot be accessed via an array and
CUDA_ERROR_NOT_MAPPED_AS_ARRAY is returned. If arrayIndex is not a valid array
index for resource then CUDA_ERROR_INVALID_VALUE is returned. If mipLevel is not
a valid mipmap level for resource then CUDA_ERROR_INVALID_VALUE is returned. If
resource is not mapped then CUDA_ERROR_NOT_MAPPED is returned.
Note:
Note that this function may also return error codes from previous, asynchronous launches.
See also:
cuGraphicsResourceGetMappedPointer, cudaGraphicsSubResourceGetMappedArray
|
567
Modules
CUresult cuGraphicsUnmapResources (unsigned int count,
CUgraphicsResource *resources, CUstream hStream)
Unmap graphics resources.
Parameters
count
- Number of resources to unmap
resources
- Resources to unmap
hStream
- Stream with which to synchronize
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_HANDLE,
CUDA_ERROR_NOT_MAPPED, CUDA_ERROR_UNKNOWN
Description
Unmaps the count graphics resources in resources.
Once unmapped, the resources in resources may not be accessed by CUDA until they are mapped
again.
This function provides the synchronization guarantee that any CUDA work issued in stream before
cuGraphicsUnmapResources() will complete before any subsequently issued graphics work begins.
If resources includes any duplicate entries then CUDA_ERROR_INVALID_HANDLE
is returned. If any of resources are not presently mapped for access by CUDA then
CUDA_ERROR_NOT_MAPPED is returned.
Note:
‣ This function uses standard default stream semantics.
‣ Note that this function may also return error codes from previous, asynchronous launches.
See also:
cuGraphicsMapResources, cudaGraphicsUnmapResources
|
568
Modules
CUresult cuGraphicsUnregisterResource
(CUgraphicsResource resource)
Unregisters a graphics resource for access by CUDA.
Parameters
resource
- Resource to unregister
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_HANDLE,
CUDA_ERROR_UNKNOWN
Description
Unregisters the graphics resource resource so it is not accessible by CUDA unless registered again.
If resource is invalid then CUDA_ERROR_INVALID_HANDLE is returned.
Note:
Note that this function may also return error codes from previous, asynchronous launches.
See also:
cuGraphicsD3D9RegisterResource, cuGraphicsD3D10RegisterResource,
cuGraphicsD3D11RegisterResource, cuGraphicsGLRegisterBuffer, cuGraphicsGLRegisterImage,
cudaGraphicsUnregisterResource
6.33. Driver Entry Point Access
This section describes the driver entry point access functions of the low-level CUDA driver application
programming interface.
|
569
Modules
CUresult cuGetProcAddress (const char *symbol,
void **pfn, int cudaVersion, cuuint64_t flags,
CUdriverProcAddressQueryResult *symbolStatus)
Returns the requested driver API function pointer.
Parameters
symbol
- The base name of the driver API function to look for. As an example, for the driver API
cuMemAlloc_v2, symbol would be cuMemAlloc and cudaVersion would be the ABI
compatible CUDA version for the _v2 variant.
pfn
- Location to return the function pointer to the requested driver function
cudaVersion
- The CUDA version to look for the requested driver symbol
flags
- Flags to specify search options.
symbolStatus
- Optional location to store the status of the search for symbol based on cudaVersion. See
CUdriverProcAddressQueryResult for possible values.
Returns
CUDA_SUCCESS, CUDA_ERROR_INVALID_VALUE, CUDA_ERROR_NOT_SUPPORTED
Description
Returns in **pfn the address of the CUDA driver function for the requested CUDA version and flags.
The CUDA version is specified as (1000 * major + 10 * minor), so CUDA 11.2 should be specified
as 11020. For a requested driver symbol, if the specified CUDA version is greater than or equal to the
CUDA version in which the driver symbol was introduced, this API will return the function pointer to
the corresponding versioned function.
The pointer returned by the API should be cast to a function pointer matching the requested driver
function's definition in the API header file. The function pointer typedef can be picked up from the
corresponding typedefs header file. For example, cudaTypedefs.h consists of function pointer typedefs
for driver APIs defined in cuda.h.
The API will return CUDA_SUCCESS and set the returned pfn to NULL if the requested driver
function is not supported on the platform, no ABI compatible driver function exists for the specified
cudaVersion or if the driver symbol is invalid.
It will also set the optional symbolStatus to one of the values in CUdriverProcAddressQueryResult
with the following meanings:
|
570
Modules
‣ CU_GET_PROC_ADDRESS_SUCCESS - The requested symbol was succesfully found based on
input arguments and pfn is valid
‣ CU_GET_PROC_ADDRESS_SYMBOL_NOT_FOUND - The requested symbol was not found
‣ CU_GET_PROC_ADDRESS_VERSION_NOT_SUFFICIENT - The requested symbol was found
but is not supported by cudaVersion specified
The requested flags can be:
‣ CU_GET_PROC_ADDRESS_DEFAULT: This is the default mode. This is
equivalent to CU_GET_PROC_ADDRESS_PER_THREAD_DEFAULT_STREAM
if the code is compiled with --default-stream per-thread compilation flag or
the macro CUDA_API_PER_THREAD_DEFAULT_STREAM is defined;
CU_GET_PROC_ADDRESS_LEGACY_STREAM otherwise.
‣ CU_GET_PROC_ADDRESS_LEGACY_STREAM: This will enable the search for all driver
symbols that match the requested driver symbol name except the corresponding per-thread
versions.
‣ CU_GET_PROC_ADDRESS_PER_THREAD_DEFAULT_STREAM: This will enable the
search for all driver symbols that match the requested driver symbol name including the per-thread
versions. If a per-thread version is not found, the API will return the legacy version of the driver
function.
Note:
Version mixing among CUDA-defined types and driver API versions is strongly discouraged and doing
so can result in an undefined behavior. More here.
See also:
cudaGetDriverEntryPoint
6.34. Coredump Attributes Control API
This section describes the coredump attribute control functions of the low-level CUDA driver
application programming interface.
enum CUCoredumpGenerationFlags
Flags for controlling coredump contents
Values
CU_COREDUMP_DEFAULT_FLAGS = 0
CU_COREDUMP_SKIP_NONRELOCATED_ELF_IMAGES = (1<<0)
|
571
Modules
CU_COREDUMP_SKIP_GLOBAL_MEMORY = (1<<1)
CU_COREDUMP_SKIP_SHARED_MEMORY = (1<<2)
CU_COREDUMP_SKIP_LOCAL_MEMORY = (1<<3)
CU_COREDUMP_SKIP_ABORT = (1<<4)
CU_COREDUMP_SKIP_CONSTBANK_MEMORY = (1<<5)
CU_COREDUMP_LIGHTWEIGHT_FLAGS =
CU_COREDUMP_SKIP_NONRELOCATED_ELF_IMAGES |
CU_COREDUMP_SKIP_GLOBAL_MEMORY |
CU_COREDUMP_SKIP_SHARED_MEMORY |CU_COREDUMP_SKIP_LOCAL_MEMORY |
CU_COREDUMP_SKIP_CONSTBANK_MEMORY
enum CUcoredumpSettings
Flags for choosing a coredump attribute to get/set
Values
CU_COREDUMP_ENABLE_ON_EXCEPTION = 1
CU_COREDUMP_TRIGGER_HOST
CU_COREDUMP_LIGHTWEIGHT
CU_COREDUMP_ENABLE_USER_TRIGGER
CU_COREDUMP_FILE
CU_COREDUMP_PIPE
CU_COREDUMP_GENERATION_FLAGS
CU_COREDUMP_MAX
CUresult cuCoredumpGetAttribute (CUcoredumpSettings
attrib, void *value, size_t *size)
Allows caller to fetch a coredump attribute value for the current context.
Parameters
attrib
- The enum defining which value to fetch.
value
- void* containing the requested data.
size
- The size of the memory region value points to.
Returns
CUDA_SUCCESS, CUDA_ERROR_INVALID_VALUE, CUDA_ERROR_NOT_PERMITTED,
CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_CONTEXT_IS_DESTROYED
|
572
Modules
Description
Returns in *value the requested value specified by attrib. It is up to the caller to ensure that the
data type and size of *value matches the request.
If the caller calls this function with *value equal to NULL, the size of the memory region (in bytes)
expected for attrib will be placed in size.
The supported attributes are:
‣ CU_COREDUMP_ENABLE_ON_EXCEPTION: Bool where true means that GPU
exceptions from this context will create a coredump at the location specified by
CU_COREDUMP_FILE. The default value is false unless set to true globally or locally, or the
CU_CTX_USER_COREDUMP_ENABLE flag was set during context creation.
‣ CU_COREDUMP_TRIGGER_HOST: Bool where true means that the host CPU will also create
a coredump. The default value is true unless set to false globally or or locally. This value is
deprecated as of CUDA 12.5 - raise the CU_COREDUMP_SKIP_ABORT flag to disable host
device abort() if needed.
‣ CU_COREDUMP_LIGHTWEIGHT: Bool where true means that any resulting coredumps
will not have a dump of GPU memory or non-reloc ELF images. The default value is false
unless set to true globally or locally. This attribute is deprecated as of CUDA 12.5, please use
CU_COREDUMP_GENERATION_FLAGS instead.
‣ CU_COREDUMP_ENABLE_USER_TRIGGER: Bool where true means that a coredump can be
created by writing to the system pipe specified by CU_COREDUMP_PIPE. The default value is
false unless set to true globally or locally.
‣ CU_COREDUMP_FILE: String of up to 1023 characters that defines the location
where any coredumps generated by this context will be written. The default value is
core.cuda.HOSTNAME.PID where HOSTNAME is the host name of the machine running the
CUDA applications and PID is the process ID of the CUDA application.
‣ CU_COREDUMP_PIPE: String of up to 1023 characters that defines the name of the
pipe that will be monitored if user-triggered coredumps are enabled. The default value is
corepipe.cuda.HOSTNAME.PID where HOSTNAME is the host name of the machine running the
CUDA application and PID is the process ID of the CUDA application.
‣ CU_COREDUMP_GENERATION_FLAGS: An integer with values to allow granular
control the data contained in a coredump specified as a bitwise OR combination of the
following values: + CU_COREDUMP_DEFAULT_FLAGS - if set by itself, coredump
generation returns to its default settings of including all memory regions that it is able
to access + CU_COREDUMP_SKIP_NONRELOCATED_ELF_IMAGES - Coredump
will not include the data from CUDA source modules that are not relocated at runtime. +
CU_COREDUMP_SKIP_GLOBAL_MEMORY - Coredump will not include device-side global
data that does not belong to any context. + CU_COREDUMP_SKIP_SHARED_MEMORY
- Coredump will not include grid-scale shared memory for the warp that the dumped kernel
belonged to. + CU_COREDUMP_SKIP_LOCAL_MEMORY - Coredump will not include local
|
573
Modules
memory from the kernel. + CU_COREDUMP_LIGHTWEIGHT_FLAGS - Enables all of the
above options. Equiavlent to setting the CU_COREDUMP_LIGHTWEIGHT attribute to true. +
CU_COREDUMP_SKIP_ABORT - If set, GPU exceptions will not raise an abort() in the host
CPU process. Same functional goal as CU_COREDUMP_TRIGGER_HOST but better reflects the
default behavior.
See also:
cuCoredumpGetAttributeGlobal, cuCoredumpSetAttribute, cuCoredumpSetAttributeGlobal
CUresult cuCoredumpGetAttributeGlobal
(CUcoredumpSettings attrib, void *value, size_t *size)
Allows caller to fetch a coredump attribute value for the entire application.
Parameters
attrib
- The enum defining which value to fetch.
value
- void* containing the requested data.
size
- The size of the memory region value points to.
Returns
CUDA_SUCCESS, CUDA_ERROR_INVALID_VALUE
Description
Returns in *value the requested value specified by attrib. It is up to the caller to ensure that the
data type and size of *value matches the request.
If the caller calls this function with *value equal to NULL, the size of the memory region (in bytes)
expected for attrib will be placed in size.
The supported attributes are:
‣ CU_COREDUMP_ENABLE_ON_EXCEPTION: Bool where true means that GPU exceptions
from this context will create a coredump at the location specified by CU_COREDUMP_FILE. The
default value is false.
‣ CU_COREDUMP_TRIGGER_HOST: Bool where true means that the host CPU will also create
a coredump. The default value is true unless set to false globally or or locally. This value is
deprecated as of CUDA 12.5 - raise the CU_COREDUMP_SKIP_ABORT flag to disable host
device abort() if needed.
|
574
Modules
‣ CU_COREDUMP_LIGHTWEIGHT: Bool where true means that any resulting coredumps will not
have a dump of GPU memory or non-reloc ELF images. The default value is false. This attribute is
deprecated as of CUDA 12.5, please use CU_COREDUMP_GENERATION_FLAGS instead.
‣ CU_COREDUMP_ENABLE_USER_TRIGGER: Bool where true means that a coredump can be
created by writing to the system pipe specified by CU_COREDUMP_PIPE. The default value is
false.
‣ CU_COREDUMP_FILE: String of up to 1023 characters that defines the location
where any coredumps generated by this context will be written. The default value is
core.cuda.HOSTNAME.PID where HOSTNAME is the host name of the machine running the
CUDA applications and PID is the process ID of the CUDA application.
‣ CU_COREDUMP_PIPE: String of up to 1023 characters that defines the name of the
pipe that will be monitored if user-triggered coredumps are enabled. The default value is
corepipe.cuda.HOSTNAME.PID where HOSTNAME is the host name of the machine running the
CUDA application and PID is the process ID of the CUDA application.
‣ CU_COREDUMP_GENERATION_FLAGS: An integer with values to allow granular
control the data contained in a coredump specified as a bitwise OR combination of the
following values: + CU_COREDUMP_DEFAULT_FLAGS - if set by itself, coredump
generation returns to its default settings of including all memory regions that it is able
to access + CU_COREDUMP_SKIP_NONRELOCATED_ELF_IMAGES - Coredump
will not include the data from CUDA source modules that are not relocated at runtime. +
CU_COREDUMP_SKIP_GLOBAL_MEMORY - Coredump will not include device-side global
data that does not belong to any context. + CU_COREDUMP_SKIP_SHARED_MEMORY
- Coredump will not include grid-scale shared memory for the warp that the dumped kernel
belonged to. + CU_COREDUMP_SKIP_LOCAL_MEMORY - Coredump will not include local
memory from the kernel. + CU_COREDUMP_LIGHTWEIGHT_FLAGS - Enables all of the
above options. Equiavlent to setting the CU_COREDUMP_LIGHTWEIGHT attribute to true. +
CU_COREDUMP_SKIP_ABORT - If set, GPU exceptions will not raise an abort() in the host
CPU process. Same functional goal as CU_COREDUMP_TRIGGER_HOST but better reflects the
default behavior.
See also:
cuCoredumpGetAttribute, cuCoredumpSetAttribute, cuCoredumpSetAttributeGlobal
CUresult cuCoredumpSetAttribute (CUcoredumpSettings
attrib, void *value, size_t *size)
Allows caller to set a coredump attribute value for the current context.
Parameters
attrib
- The enum defining which value to set.
|
575
Modules
value
- void* containing the requested data.
size
- The size of the memory region value points to.
Returns
CUDA_SUCCESS, CUDA_ERROR_INVALID_VALUE, CUDA_ERROR_NOT_PERMITTED,
CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_CONTEXT_IS_DESTROYED,
CUDA_ERROR_NOT_SUPPORTED
Description
This function should be considered an alternate interface to the CUDA-GDB environment variables
defined in this document: https://docs.nvidia.com/cuda/cuda-gdb/index.html#gpu-coredump
An important design decision to note is that any coredump environment variable values set before
CUDA initializes will take permanent precedence over any values set with this function. This decision
was made to ensure no change in behavior for any users that may be currently using these variables to
get coredumps.
*value shall contain the requested value specified by set. It is up to the caller to ensure that the data
type and size of *value matches the request.
If the caller calls this function with *value equal to NULL, the size of the memory region (in bytes)
expected for set will be placed in size.
/note This function will return CUDA_ERROR_NOT_SUPPORTED if the caller attempts to set
CU_COREDUMP_ENABLE_ON_EXCEPTION on a GPU of with Compute Capability < 6.0.
cuCoredumpSetAttributeGlobal works on those platforms as an alternative.
/note CU_COREDUMP_ENABLE_USER_TRIGGER and CU_COREDUMP_PIPE cannot be set on a
per-context basis.
The supported attributes are:
‣ CU_COREDUMP_ENABLE_ON_EXCEPTION: Bool where true means that GPU exceptions
from this context will create a coredump at the location specified by CU_COREDUMP_FILE. The
default value is false.
‣ CU_COREDUMP_TRIGGER_HOST: Bool where true means that the host CPU will also create
a coredump. The default value is true unless set to false globally or or locally. This value is
deprecated as of CUDA 12.5 - raise the CU_COREDUMP_SKIP_ABORT flag to disable host
device abort() if needed.
‣ CU_COREDUMP_LIGHTWEIGHT: Bool where true means that any resulting coredumps will not
have a dump of GPU memory or non-reloc ELF images. The default value is false. This attribute is
deprecated as of CUDA 12.5, please use CU_COREDUMP_GENERATION_FLAGS instead.
|
576
Modules
‣ CU_COREDUMP_FILE: String of up to 1023 characters that defines the location
where any coredumps generated by this context will be written. The default value is
core.cuda.HOSTNAME.PID where HOSTNAME is the host name of the machine running the
CUDA applications and PID is the process ID of the CUDA application.
‣ CU_COREDUMP_GENERATION_FLAGS: An integer with values to allow granular
control the data contained in a coredump specified as a bitwise OR combination of the
following values: + CU_COREDUMP_DEFAULT_FLAGS - if set by itself, coredump
generation returns to its default settings of including all memory regions that it is able
to access + CU_COREDUMP_SKIP_NONRELOCATED_ELF_IMAGES - Coredump
will not include the data from CUDA source modules that are not relocated at runtime. +
CU_COREDUMP_SKIP_GLOBAL_MEMORY - Coredump will not include device-side global
data that does not belong to any context. + CU_COREDUMP_SKIP_SHARED_MEMORY
- Coredump will not include grid-scale shared memory for the warp that the dumped kernel
belonged to. + CU_COREDUMP_SKIP_LOCAL_MEMORY - Coredump will not include local
memory from the kernel. + CU_COREDUMP_LIGHTWEIGHT_FLAGS - Enables all of the
above options. Equiavlent to setting the CU_COREDUMP_LIGHTWEIGHT attribute to true. +
CU_COREDUMP_SKIP_ABORT - If set, GPU exceptions will not raise an abort() in the host
CPU process. Same functional goal as CU_COREDUMP_TRIGGER_HOST but better reflects the
default behavior.
See also:
cuCoredumpGetAttributeGlobal, cuCoredumpGetAttribute, cuCoredumpSetAttributeGlobal
CUresult cuCoredumpSetAttributeGlobal
(CUcoredumpSettings attrib, void *value, size_t *size)
Allows caller to set a coredump attribute value globally.
Parameters
attrib
- The enum defining which value to set.
value
- void* containing the requested data.
size
- The size of the memory region value points to.
Returns
CUDA_SUCCESS, CUDA_ERROR_INVALID_VALUE, CUDA_ERROR_NOT_PERMITTED
|
577
Modules
Description
This function should be considered an alternate interface to the CUDA-GDB environment variables
defined in this document: https://docs.nvidia.com/cuda/cuda-gdb/index.html#gpu-coredump
An important design decision to note is that any coredump environment variable values set before
CUDA initializes will take permanent precedence over any values set with this function. This decision
was made to ensure no change in behavior for any users that may be currently using these variables to
get coredumps.
*value shall contain the requested value specified by set. It is up to the caller to ensure that the data
type and size of *value matches the request.
If the caller calls this function with *value equal to NULL, the size of the memory region (in bytes)
expected for set will be placed in size.
The supported attributes are:
‣ CU_COREDUMP_ENABLE_ON_EXCEPTION: Bool where true means that GPU exceptions
from this context will create a coredump at the location specified by CU_COREDUMP_FILE. The
default value is false.
‣ CU_COREDUMP_TRIGGER_HOST: Bool where true means that the host CPU will also create
a coredump. The default value is true unless set to false globally or or locally. This value is
deprecated as of CUDA 12.5 - raise the CU_COREDUMP_SKIP_ABORT flag to disable host
device abort() if needed.
‣ CU_COREDUMP_LIGHTWEIGHT: Bool where true means that any resulting coredumps will not
have a dump of GPU memory or non-reloc ELF images. The default value is false. This attribute is
deprecated as of CUDA 12.5, please use CU_COREDUMP_GENERATION_FLAGS instead.
‣ CU_COREDUMP_ENABLE_USER_TRIGGER: Bool where true means that a coredump can be
created by writing to the system pipe specified by CU_COREDUMP_PIPE. The default value is
false.
‣ CU_COREDUMP_FILE: String of up to 1023 characters that defines the location
where any coredumps generated by this context will be written. The default value is
core.cuda.HOSTNAME.PID where HOSTNAME is the host name of the machine running the
CUDA applications and PID is the process ID of the CUDA application.
‣ CU_COREDUMP_PIPE: String of up to 1023 characters that defines the name of the pipe that
will be monitored if user-triggered coredumps are enabled. This value may not be changed
after CU_COREDUMP_ENABLE_USER_TRIGGER is set to true. The default value is
corepipe.cuda.HOSTNAME.PID where HOSTNAME is the host name of the machine running the
CUDA application and PID is the process ID of the CUDA application.
‣ CU_COREDUMP_GENERATION_FLAGS: An integer with values to allow granular
control the data contained in a coredump specified as a bitwise OR combination of the
following values: + CU_COREDUMP_DEFAULT_FLAGS - if set by itself, coredump
generation returns to its default settings of including all memory regions that it is able
to access + CU_COREDUMP_SKIP_NONRELOCATED_ELF_IMAGES - Coredump
|
578
Modules
will not include the data from CUDA source modules that are not relocated at runtime. +
CU_COREDUMP_SKIP_GLOBAL_MEMORY - Coredump will not include device-side global
data that does not belong to any context. + CU_COREDUMP_SKIP_SHARED_MEMORY
- Coredump will not include grid-scale shared memory for the warp that the dumped kernel
belonged to. + CU_COREDUMP_SKIP_LOCAL_MEMORY - Coredump will not include local
memory from the kernel. + CU_COREDUMP_LIGHTWEIGHT_FLAGS - Enables all of the
above options. Equiavlent to setting the CU_COREDUMP_LIGHTWEIGHT attribute to true. +
CU_COREDUMP_SKIP_ABORT - If set, GPU exceptions will not raise an abort() in the host
CPU process. Same functional goal as CU_COREDUMP_TRIGGER_HOST but better reflects the
default behavior.
See also:
cuCoredumpGetAttribute, cuCoredumpGetAttributeGlobal, cuCoredumpSetAttribute
6.35. Green Contexts
This section describes the APIs for creation and manipulation of green contexts in the CUDA driver.
Green contexts are a lightweight alternative to traditional contexts, with the ability to pass in a set of
resources that they should be initialized with. This allows the developer to represent distinct spatial
partitions of the GPU, provision resources for them, and target them via the same programming model
that CUDA exposes (streams, kernel launches, etc.).
There are 4 main steps to using these new set of APIs.
‣ (1) Start with an initial set of resources, for example via cuDeviceGetDevResource. Only SM type
is supported today.
‣ (2) Partition this set of resources by providing them as input to a partition API, for example:
cuDevSmResourceSplitByCount.
‣ (3) Finalize the specification of resources by creating a descriptor via
cuDevResourceGenerateDesc.
‣ (4) Provision the resources and create a green context via cuGreenCtxCreate.
For CU_DEV_RESOURCE_TYPE_SM, the partitions created have minimum SM count requirements,
often rounding up and aligning the minCount provided to cuDevSmResourceSplitByCount. The
following is a guideline for each architecture and may be subject to change:
‣ On Compute Architecture 6.X: The minimum count is 1 SM.
‣ On Compute Architecture 7.X: The minimum count is 2 SMs and must be a multiple of 2.
‣ On Compute Architecture 8.X: The minimum count is 4 SMs and must be a multiple of 2.
‣ On Compute Architecture 9.0+: The minimum count is 8 SMs and must be a multiple of 8.
In the future, flags can be provided to tradeoff functional and performance characteristics versus finer
grained SM partitions.
|
579
Modules
Even if the green contexts have disjoint SM partitions, it is not guaranteed that the kernels launched
in them will run concurrently or have forward progress guarantees. This is due to other resources (like
HW connections, see CUDA_DEVICE_MAX_CONNECTIONS) that could cause a dependency.
Additionally, in certain scenarios, it is possible for the workload to run on more SMs than was
provisioned (but never less). The following are two scenarios which can exhibit this behavior:
‣ On Volta+ MPS: When CUDA_MPS_ACTIVE_THREAD_PERCENTAGE is used, the set of SMs
that are used for running kernels can be scaled up to the value of SMs used for the MPS client.
‣ On Compute Architecture 9.x: When a module with dynamic parallelism (CDP) is loaded, all
future kernels running under green contexts may use and share an additional set of 2 SMs.
struct CUdevResource
struct CUdevSmResource
enum CUdevResourceType
Type of resource
Values
CU_DEV_RESOURCE_TYPE_INVALID = 0
CU_DEV_RESOURCE_TYPE_SM = 1
Streaming multiprocessors related information
typedef struct CUdevResourceDesc_st
*CUdevResourceDesc
An opaque descriptor handle. The descriptor encapsulates multiple created and configured resources.
Created via cuDevResourceGenerateDesc
CUresult cuCtxFromGreenCtx (CUcontext *pContext,
CUgreenCtx hCtx)
Converts a green context into the primary context.
Parameters
pContext
Returned primary context with green context resources
hCtx
Green context to convert
|
580
Modules
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_VALUE
Description
The API converts a green context into the primary context returned in pContext. It is important
to note that the converted context pContext is a normal primary context but with the resources of
the specified green context hCtx. Once converted, it can then be used to set the context current with
cuCtxSetCurrent or with any of the CUDA APIs that accept a CUcontext parameter.
Users are expected to call this API before calling any CUDA APIs that accept a CUcontext. Failing to
do so will result in the APIs returning CUDA_ERROR_INVALID_CONTEXT.
See also:
cuGreenCtxCreate
CUresult cuCtxGetDevResource (CUcontext hCtx,
CUdevResource *resource, CUdevResourceType type)
Get context resources.
Parameters
hCtx
- Context to get resource for
resource
- Output pointer to a CUdevResource structure
type
- Type of resource to retrieve
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_RESOURCE_TYPE, CUDA_ERROR_INVALID_VALUE,
CUDA_ERROR_INVALID_CONTEXT
Description
Get the type resources available to the context represented by hCtx Note: The API is not supported
on 32-bit platforms.
See also:
cuDevResourceGenerateDesc
|
581
Modules
CUresult cuDeviceGetDevResource (CUdevice device,
CUdevResource *resource, CUdevResourceType type)
Get device resources.
Parameters
device
- Device to get resource for
resource
- Output pointer to a CUdevResource structure
type
- Type of resource to retrieve
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_RESOURCE_TYPE, CUDA_ERROR_INVALID_VALUE,
CUDA_ERROR_INVALID_DEVICE
Description
Get the type resources available to the device. This may often be the starting point for further
partitioning or configuring of resources.
Note: The API is not supported on 32-bit platforms.
See also:
cuDevResourceGenerateDesc
CUresult cuDevResourceGenerateDesc
(CUdevResourceDesc *phDesc, CUdevResource
*resources, unsigned int nbResources)
Generate a resource descriptor.
Parameters
phDesc
- Output descriptor
resources
- Array of resources to be included in the descriptor
nbResources
- Number of resources passed in resources
|
582
Modules
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_VALUE, CUDA_ERROR_INVALID_RESOURCE_TYPE,
CUDA_ERROR_INVALID_RESOURCE_CONFIGURATION
Description
Generates a single resource descriptor with the set of resources specified in resources. The
generated resource descriptor is necessary for the creation of green contexts via the cuGreenCtxCreate
API. Resources of the same type can be passed in, provided they meet the requirements as noted below.
A successful API call must have:
‣ A valid output pointer for the phDesc descriptor as well as a valid array of resources
pointers, with the array size passed in nbResources. If multiple resources are
provided in resources, the device they came from must be the same, otherwise
CUDA_ERROR_INVALID_RESOURCE_CONFIGURATION is returned. If multiple resources
are provided in resources and they are of type CU_DEV_RESOURCE_TYPE_SM, they
must be outputs (whether result or remaining) from the same split API instance, otherwise
CUDA_ERROR_INVALID_RESOURCE_CONFIGURATION is returned.
Note: The API is not supported on 32-bit platforms.
See also:
cuDevSmResourceSplitByCount
CUresult cuDevSmResourceSplitByCount
(CUdevResource *result, unsigned int *nbGroups, const
CUdevResource *input, CUdevResource *remaining,
unsigned int useFlags, unsigned int minCount)
Splits CU_DEV_RESOURCE_TYPE_SM resources.
Parameters
result
- Output array of CUdevResource resources. Can be NULL to query the number of groups.
nbGroups
- This is a pointer, specifying the number of groups that would be or should be created as described
below.
input
- Input SM resource to be split. Must be a valid CU_DEV_RESOURCE_TYPE_SM resource.
|
583
Modules
remaining
- If the input resource cannot be cleanly split among nbGroups, the remaining is placed in here.
Can be ommitted (NULL) if the user does not need the remaining set.
useFlags
- Flags specifying how these partitions are used or which constraints to abide by when splitting the
input. Zero is valid for default behavior.
minCount
- Minimum number of SMs required
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_DEVICE, CUDA_ERROR_INVALID_VALUE,
CUDA_ERROR_INVALID_RESOURCE_TYPE,
CUDA_ERROR_INVALID_RESOURCE_CONFIGURATION
Description
Splits CU_DEV_RESOURCE_TYPE_SM resources into nbGroups, adhering to the minimum SM
count specified in minCount and the usage flags in useFlags. If result is NULL, the API
simulates a split and provides the amount of groups that would be created in nbGroups. Otherwise,
nbGroups must point to the amount of elements in result and on return, the API will overwrite
nbGroups with the amount actually created. The groups are written to the array in result.
nbGroups can be less than the total amount if a smaller number of groups is needed.
This API is used to spatially partition the input resource. The input resource needs to come from one of
cuDeviceGetDevResource, cuCtxGetDevResource, or cuGreenCtxGetDevResource. A limitation of the
API is that the output results cannot be split again without first creating a descriptor and a green context
with that descriptor.
When creating the groups, the API will take into account the performance and functional characteristics
of the input resource, and guarantee a split that will create a disjoint set of symmetrical partitions. This
may lead to fewer groups created than purely dividing the total SM count by the minCount due to
cluster requirements or alignment and granularity requirements for the minCount.
The remainder set does not have the same functional or performance guarantees as the groups
in result. Its use should be carefully planned and future partitions of the remainder set are
discouraged.
The following flags are supported:
‣ CU_DEV_SM_RESOURCE_SPLIT_IGNORE_SM_COSCHEDULING : Lower the minimum SM
count and alignment, and treat each SM independent of its hierarchy. This allows more fine grained
partitions but at the cost of advanced features (such as large clusters on compute capability 9.0+).
‣ CU_DEV_SM_RESOURCE_SPLIT_MAX_POTENTIAL_CLUSTER_SIZE : Compute Capability
9.0+ only. Attempt to create groups that may allow for maximally sized thread clusters. This can be
queried post green context creation using cuOccupancyMaxPotentialClusterSize.
|
584
Modules
A successful API call must either have:
‣ A valid array of result pointers of size passed in nbGroups, with input of type
CU_DEV_RESOURCE_TYPE_SM. Value of minCount must be between 0 and the SM count
specified in input. remaining may be NULL.
‣ NULL passed in for result, with a valid integer pointer in nbGroups and input of type
CU_DEV_RESOURCE_TYPE_SM. Value of minCount must be between 0 and the SM count
specified in input. remaining may be NULL. This queries the number of groups that would be
created by the API.
Note: The API is not supported on 32-bit platforms.
See also:
cuGreenCtxGetDevResource, cuCtxGetDevResource, cuDeviceGetDevResource
CUresult cuGreenCtxCreate (CUgreenCtx *phCtx,
CUdevResourceDesc desc, CUdevice dev, unsigned int
flags)
Creates a green context with a specified set of resources.
Parameters
phCtx
- Pointer for the output handle to the green context
desc
- Descriptor generated via cuDevResourceGenerateDesc which contains the set of resources to be
used
dev
- Device on which to create the green context.
flags
- One of the supported green context creation flags. CU_GREEN_CTX_DEFAULT_STREAM is
required.
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_DEVICE, CUDA_ERROR_INVALID_VALUE,
CUDA_ERROR_NOT_SUPPORTED, CUDA_ERROR_OUT_OF_MEMORY
Description
This API creates a green context with the resources specified in the descriptor desc and returns it in
the handle represented by phCtx. This API will retain the primary context on device dev, which will
is released when the green context is destroyed. It is advised to have the primary context active before
|
585
Modules
calling this API to avoid the heavy cost of triggering primary context initialization and deinitialization
multiple times.
The API does not set the green context current. In order to set it current, you need to explicitly
set it current by first converting the green context to a CUcontext using cuCtxFromGreenCtx and
subsequently calling cuCtxSetCurrent / cuCtxPushCurrent. It should be noted that a green context
can be current to only one thread at a time. There is no internal synchronization to make API calls
accessing the same green context from multiple threads work.
Note: The API is not supported on 32-bit platforms.
The supported flags are:
‣ CU_GREEN_CTX_DEFAULT_STREAM : Creates a default stream to use inside the green context.
Required.
See also:
cuGreenCtxDestroy, cuCtxFromGreenCtx, cuCtxSetCurrent, cuCtxPushCurrent,
cuDevResourceGenerateDesc, cuDevicePrimaryCtxRetain, cuCtxCreate, cuCtxCreate_v3
CUresult cuGreenCtxDestroy (CUgreenCtx hCtx)
Destroys a green context.
Parameters
hCtx
- Green context to be destroyed
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_CONTEXT_IS_DESTROYED
Description
Destroys the green context, releasing the primary context of the device that this green context was
created for. Any resources provisioned for this green context (that were initially available via the
resource descriptor) are released as well.
See also:
cuGreenCtxCreate, cuCtxDestroy
|
586
Modules
CUresult cuGreenCtxGetDevResource (CUgreenCtx hCtx,
CUdevResource *resource, CUdevResourceType type)
Get green context resources.
Parameters
hCtx
- Green context to get resource for
resource
- Output pointer to a CUdevResource structure
type
- Type of resource to retrieve
Returns
CUDA_SUCCESS CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_RESOURCE_TYPE,
CUDA_ERROR_INVALID_VALUE
Description
Get the type resources available to the green context represented by hCtx
See also:
cuDevResourceGenerateDesc
CUresult cuGreenCtxRecordEvent (CUgreenCtx hCtx,
CUevent hEvent)
Records an event.
Parameters
hCtx
- Green context to record event for
hEvent
- Event to record
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_HANDLE,
CUDA_ERROR_STREAM_CAPTURE_UNSUPPORTED
|
587
Modules
Description
Captures in hEvent all the activities of the green context of hCtx at the time of this call. hEvent
and hCtx must be from the same primary context otherwise CUDA_ERROR_INVALID_HANDLE
is returned. Calls such as cuEventQuery() or cuGreenCtxWaitEvent() will then examine or wait for
completion of the work that was captured. Uses of hCtx after this call do not modify hEvent.
Note:
The API will return CUDA_ERROR_STREAM_CAPTURE_UNSUPPORTED if the specified green
context hCtx has a stream in the capture mode. In such a case, the call will invalidate all the conflicting
captures.
See also:
cuGreenCtxWaitEvent, cuEventRecord, cuCtxRecordEvent, cuCtxWaitEvent
CUresult cuGreenCtxStreamCreate (CUstream *phStream,
CUgreenCtx greenCtx, unsigned int flags, int priority)
Create a stream for use in the green context.
Parameters
phStream
- Returned newly created stream
greenCtx
- Green context for which to create the stream for
flags
- Flags for stream creation. CU_STREAM_NON_BLOCKING must be specified.
priority
- Stream priority. Lower numbers represent higher priorities. See cuCtxGetStreamPriorityRange for
more information about meaningful stream priorities that can be passed.
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_VALUE,
CUDA_ERROR_OUT_OF_MEMORY
Description
Creates a stream for use in the specified green context greenCtx and returns a handle in phStream.
The stream can be destroyed by calling cuStreamDestroy(). Note that the API ignores the context that
is current to the calling thread and creates a stream in the specified green context greenCtx.
|
588
Modules
The supported values for flags are:
‣ CU_STREAM_NON_BLOCKING: This must be specified. It indicates that work running in the
created stream may run concurrently with work in the default stream, and that the created stream
should perform no implicit synchronization with the default stream.
Specifying priority affects the scheduling priority of work in the stream. Priorities provide a hint
to preferentially run work with higher priority when possible, but do not preempt already-running work
or provide any other functional guarantee on execution order. priority follows a convention where
lower numbers represent higher priorities. '0' represents default priority. The range of meaningful
numerical priorities can be queried using cuCtxGetStreamPriorityRange. If the specified priority
is outside the numerical range returned by cuCtxGetStreamPriorityRange, it will automatically be
clamped to the lowest or the highest number in the range.
Note:
‣ Note that this function may also return error codes from previous, asynchronous launches.
‣ In the current implementation, only compute kernels launched in priority streams are affected by
the stream's priority. Stream priorities have no effect on host-to-device and device-to-host memory
operations.
See also:
cuStreamDestroy, cuGreenCtxCreate cuStreamCreate, cuStreamGetPriority,
cuCtxGetStreamPriorityRange, cuStreamGetFlags, cuStreamGetDevice, cuStreamWaitEvent,
cuStreamQuery, cuStreamSynchronize, cuStreamAddCallback, cudaStreamCreateWithPriority
CUresult cuGreenCtxWaitEvent (CUgreenCtx hCtx,
CUevent hEvent)
Make a green context wait on an event.
Parameters
hCtx
- Green context to wait
hEvent
- Event to wait on
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_HANDLE,
CUDA_ERROR_STREAM_CAPTURE_UNSUPPORTED
|
589
Modules
Description
Makes all future work submitted to green context hCtx wait for all work captured in hEvent. The
synchronization will be performed on the device and will not block the calling CPU thread. See
cuGreenCtxRecordEvent() or cuEventRecord(), for details on what is captured by an event.
Note:
‣ hEvent may be from a different context or device than hCtx.
‣ The API will return CUDA_ERROR_STREAM_CAPTURE_UNSUPPORTED and invalidate the
capture if the specified event hEvent is part of an ongoing capture sequence or if the specified
green context hCtx has a stream in the capture mode.
See also:
cuGreenCtxRecordEvent, cuStreamWaitEvent, cuCtxRecordEvent, cuCtxWaitEvent
CUresult cuStreamGetGreenCtx (CUstream hStream,
CUgreenCtx *phCtx)
Query the green context associated with a stream.
Parameters
hStream
- Handle to the stream to be queried
phCtx
- Returned green context associated with the stream
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_HANDLE,
Description
Returns the CUDA green context that the stream is associated with, or NULL if the stream is not
associated with any green context.
The stream handle hStream can refer to any of the following:
‣ a stream created via any of the CUDA driver APIs such as cuStreamCreate,
cuStreamCreateWithPriority and cuGreenCtxStreamCreate, or their runtime API equivalents
such as cudaStreamCreate, cudaStreamCreateWithFlags and cudaStreamCreateWithPriority.
If during stream creation the context that was active in the calling thread was obtained with
|
590
Modules
cuCtxFromGreenCtx, that green context is returned in phCtx. Otherwise, *phCtx is set to NULL
instead.
‣ special stream such as the NULL stream or CU_STREAM_LEGACY. In that case if context that is
active in the calling thread was obtained with cuCtxFromGreenCtx, that green context is returned.
Otherwise, *phCtx is set to NULL instead.
Passing an invalid handle will result in undefined behavior.
Note:
Note that this function may also return error codes from previous, asynchronous launches.
See also:
cuStreamDestroy, cuStreamCreate, cuStreamCreateWithPriority, cuStreamGetCtx_v2,
cuGreenCtxStreamCreate, cuStreamGetPriority, cuStreamGetFlags, cuStreamGetDevice,
cuStreamWaitEvent, cuStreamQuery, cuStreamSynchronize, cuStreamAddCallback,
cudaStreamCreate, cudaStreamCreateWithFlags
6.36. Error Log Management Functions
This section describes the error log management functions of the low-level CUDA driver application
programming interface.
CUresult cuLogsCurrent (CUlogIterator *iterator_out,
unsigned int flags)
Sets log iterator to point to the end of log buffer, where the next message would be written.
Parameters
iterator_out
- Location to store an iterator to the current tail of the logs
flags
- Reserved for future use, must be 0
Returns
CUDA_SUCCESS CUDA_ERROR_INVALID_VALUE
|
591
Modules
CUresult cuLogsDumpToFile (CUlogIterator *iterator,
const char *pathToFile, unsigned int flags)
Dump accumulated driver logs into a file.
Parameters
iterator
- Optional auto-advancing iterator specifying the starting log to read. NULL value dumps all logs.
pathToFile
- Path to output file for dumping logs
flags
- Reserved for future use, must be 0
Returns
CUDA_SUCCESS CUDA_ERROR_INVALID_VALUE
Description
Logs generated by the driver are stored in an internal buffer and can be copied out using this API. This
API dumps all driver logs starting from iterator into pathToFile provided.
Note:
‣ iterator is auto-advancing. Dumping logs will update the value of iterator to receive the
next generated log.
‣ The driver reserves limited memory for storing logs. The oldest logs may be overwritten and
become unrecoverable. An indication will appear in the destination outupt if the logs have been
truncated. Call dump after each failed API to mitigate this risk.
CUresult cuLogsDumpToMemory (CUlogIterator *iterator,
char *buffer, size_t *size, unsigned int flags)
Dump accumulated driver logs into a buffer.
Parameters
iterator
- Optional auto-advancing iterator specifying the starting log to read. NULL value dumps all logs.
buffer
- Pointer to dump logs
size
- See description
|
592
Modules
flags
- Reserved for future use, must be 0
Returns
CUDA_SUCCESS, CUDA_ERROR_INVALID_VALUE
Description
Logs generated by the driver are stored in an internal buffer and can be copied out using this API. This
API dumps driver logs from iterator into buffer up to the size specified in *size. The driver
will always null terminate the buffer but there will not be a null character between log entries, only
a newline \n. The driver will then return the actual number of bytes written in *size, excluding the
null terminator. If there are no messages to dump, *size will be set to 0 and the function will return
CUDA_SUCCESS. If the provided buffer is not large enough to hold any messages, *size will be
set to 0 and the function will return CUDA_ERROR_INVALID_VALUE.
Note:
‣ iterator is auto-advancing. Dumping logs will update the value of iterator to receive the
next generated log.
‣ The driver reserves limited memory for storing logs. The maximum size of the buffer is 25600
bytes. The oldest logs may be overwritten and become unrecoverable. An indication will appear in
the destination outupt if the logs have been truncated. Call dump after each failed API to mitigate
this risk.
‣ If the provided value in *size is not large enough to hold all buffered messages, a message will
be added at the head of the buffer indicating this. The driver then computes the number of messages
it is able to store in buffer and writes it out. The final message in buffer will always be the
most recent log message as of when the API is called.
CUresult cuLogsRegisterCallback (CUlogsCallback
callbackFunc, void *userData, CUlogsCallbackHandle
*callback_out)
Register a callback function to receive error log messages.
Parameters
callbackFunc
- The function to register as a callback
userData
- A generic pointer to user data. This is passed into the callback function.
callback_out
- Optional location to store the callback handle after it is registered
|
593
Modules
Returns
CUDA_SUCCESS CUDA_ERROR_INVALID_VALUE
CUresult cuLogsUnregisterCallback
(CUlogsCallbackHandle callback)
Unregister a log message callback.
Parameters
callback
- The callback instance to unregister from receiving log messages
Returns
CUDA_SUCCESS CUDA_ERROR_INVALID_VALUE
6.37. CUDA Checkpointing
CUDA API versioning support
This sections describes the checkpoint and restore functions of the low-level CUDA driver application
programming interface.
The CUDA checkpoint and restore API's provide a way to save and restore GPU state for full process
checkpoints when used with CPU side process checkpointing solutions. They can also be used to pause
GPU work and suspend a CUDA process to allow other applications to make use of GPU resources.
Checkpoint and restore capabilities are currently restricted to Linux.
CUresult cuCheckpointProcessCheckpoint (int pid,
CUcheckpointCheckpointArgs *args)
Checkpoint a CUDA process's GPU memory contents.
Parameters
pid
- The process ID of the CUDA process
args
- Optional checkpoint operation arguments
Returns
CUDA_SUCCESS CUDA_ERROR_INVALID_VALUE CUDA_ERROR_NOT_INITIALIZED
CUDA_ERROR_ILLEGAL_STATE CUDA_ERROR_NOT_SUPPORTED
|
594
Modules
Description
Checkpoints a CUDA process specified by pid that is in the LOCKED state. The GPU memory
contents will be brought into host memory and all underlying references will be released. Process must
be in the LOCKED state to checkpoint.
Upon successful return the process will be in the CHECKPOINTED state.
CUresult cuCheckpointProcessGetRestoreThreadId (int pid,
int *tid)
Returns the restore thread ID for a CUDA process.
Parameters
pid
- The process ID of the CUDA process
tid
- Returned restore thread ID
Returns
CUDA_SUCCESS CUDA_ERROR_INVALID_VALUE CUDA_ERROR_NOT_INITIALIZED
CUDA_ERROR_NOT_SUPPORTED
Description
Returns in *tid the thread ID of the CUDA restore thread for the process specified by pid.
CUresult cuCheckpointProcessGetState (int pid,
CUprocessState *state)
Returns the process state of a CUDA process.
Parameters
pid
- The process ID of the CUDA process
state
- Returned CUDA process state
Returns
CUDA_SUCCESS CUDA_ERROR_INVALID_VALUE CUDA_ERROR_NOT_INITIALIZED
CUDA_ERROR_NOT_SUPPORTED
|
595
Modules
Description
Returns in *state the current state of the CUDA process specified by pid.
CUresult cuCheckpointProcessLock (int pid,
CUcheckpointLockArgs *args)
Lock a running CUDA process.
Parameters
pid
- The process ID of the CUDA process
args
- Optional lock operation arguments
Returns
CUDA_SUCCESS CUDA_ERROR_INVALID_VALUE CUDA_ERROR_NOT_INITIALIZED
CUDA_ERROR_ILLEGAL_STATE CUDA_ERROR_NOT_SUPPORTED
CUDA_ERROR_NOT_READY
Description
Lock the CUDA process specified by pid which will block further CUDA API calls. Process must be
in the RUNNING state in order to lock.
Upon successful return the process will be in the LOCKED state.
If timeoutMs is specified and the timeout is reached the process will be left in the RUNNING state
upon return.
CUresult cuCheckpointProcessRestore (int pid,
CUcheckpointRestoreArgs *args)
Restore a CUDA process's GPU memory contents from its last checkpoint.
Parameters
pid
- The process ID of the CUDA process
args
- Optional restore operation arguments
|
596
Modules
Returns
CUDA_SUCCESS CUDA_ERROR_INVALID_VALUE CUDA_ERROR_NOT_INITIALIZED
CUDA_ERROR_ILLEGAL_STATE CUDA_ERROR_NOT_SUPPORTED
Description
Restores a CUDA process specified by pid from its last checkpoint. Process must be in the
CHECKPOINTED state to restore.
Upon successful return the process will be in the LOCKED state.
CUDA process restore requires persistence mode to be enabled or cuInit to have been called before
execution.
See also:
cuInit
CUresult cuCheckpointProcessUnlock (int pid,
CUcheckpointUnlockArgs *args)
Unlock a CUDA process to allow CUDA API calls.
Parameters
pid
- The process ID of the CUDA process
args
- Optional unlock operation arguments
Returns
CUDA_SUCCESS CUDA_ERROR_INVALID_VALUE CUDA_ERROR_NOT_INITIALIZED
CUDA_ERROR_ILLEGAL_STATE CUDA_ERROR_NOT_SUPPORTED
Description
Unlocks a process specified by pid allowing it to resume making CUDA API calls. Process must be in
the LOCKED state.
Upon successful return the process will be in the RUNNING state.
|
597
Modules
6.38. Profiler Control [DEPRECATED]
This section describes the profiler control functions of the low-level CUDA driver application
programming interface.
CUresult cuProfilerInitialize (const char *configFile, const
char *outputFile, CUoutput_mode outputMode)
Initialize the profiling.
Parameters
configFile
- Name of the config file that lists the counters/options for profiling.
outputFile
- Name of the outputFile where the profiling results will be stored.
outputMode
- outputMode, can be CU_OUT_KEY_VALUE_PAIR or CU_OUT_CSV.
Returns
CUDA_ERROR_NOT_SUPPORTED
Description
Deprecated
Note that this function is deprecated and should not be used. Starting with CUDA 12.0, it always
returns error code CUDA_ERROR_NOT_SUPPORTED.
Using this API user can initialize the CUDA profiler by specifying the configuration file, output file
and output file format. This API is generally used to profile different set of counters by looping the
kernel launch. The configFile parameter can be used to select profiling options including profiler
counters. Refer to the "Compute Command Line Profiler User Guide" for supported profiler options
and counters.
Limitation: The CUDA profiler cannot be initialized with this API if another profiling tool is already
active, as indicated by the CUDA_ERROR_PROFILER_DISABLED return code.
Typical usage of the profiling APIs is as follows:
for each set of counters/options { cuProfilerInitialize(); //Initialize profiling, set the counters or options
in the config file ... cuProfilerStart(); // code to be profiled cuProfilerStop(); ... cuProfilerStart(); // code
to be profiled cuProfilerStop(); ... }
|
598
Modules
Note:
Note that this function may also return error codes from previous, asynchronous launches.
See also:
cuProfilerStart, cuProfilerStop,
6.39. Profiler Control
This section describes the profiler control functions of the low-level CUDA driver application
programming interface.
CUresult cuProfilerStart (void)
Enable profiling.
Returns
CUDA_SUCCESS, CUDA_ERROR_INVALID_CONTEXT
Description
Enables profile collection by the active profiling tool for the current context. If profiling is already
enabled, then cuProfilerStart() has no effect.
cuProfilerStart and cuProfilerStop APIs are used to programmatically control the profiling granularity
by allowing profiling to be done only on selective pieces of code.
Note:
Note that this function may also return error codes from previous, asynchronous launches.
See also:
cuProfilerInitialize, cuProfilerStop, cudaProfilerStart
CUresult cuProfilerStop (void)
Disable profiling.
Returns
CUDA_SUCCESS, CUDA_ERROR_INVALID_CONTEXT
|
599
Modules
Description
Disables profile collection by the active profiling tool for the current context. If profiling is already
disabled, then cuProfilerStop() has no effect.
cuProfilerStart and cuProfilerStop APIs are used to programmatically control the profiling granularity
by allowing profiling to be done only on selective pieces of code.
Note:
Note that this function may also return error codes from previous, asynchronous launches.
See also:
cuProfilerInitialize, cuProfilerStart, cudaProfilerStop
6.40. OpenGL Interoperability
This section describes the OpenGL interoperability functions of the low-level CUDA driver application
programming interface. Note that mapping of OpenGL resources is performed with the graphics API
agnostic, resource mapping interface described in Graphics Interoperability.
OpenGL Interoperability [DEPRECATED]
enum CUGLDeviceList
CUDA devices corresponding to an OpenGL device
Values
CU_GL_DEVICE_LIST_ALL = 0x01
The CUDA devices for all GPUs used by the current OpenGL context
CU_GL_DEVICE_LIST_CURRENT_FRAME = 0x02
The CUDA devices for the GPUs used by the current OpenGL context in its currently rendering
frame
CU_GL_DEVICE_LIST_NEXT_FRAME = 0x03
The CUDA devices for the GPUs to be used by the current OpenGL context in the next frame
|
600
Modules
CUresult cuGLGetDevices (unsigned int
*pCudaDeviceCount, CUdevice *pCudaDevices, unsigned
int cudaDeviceCount, CUGLDeviceList deviceList)
Gets the CUDA devices associated with the current OpenGL context.
Parameters
pCudaDeviceCount
- Returned number of CUDA devices.
pCudaDevices
- Returned CUDA devices.
cudaDeviceCount
- The size of the output device array pCudaDevices.
deviceList
- The set of devices to return.
Returns
CUDA_SUCCESS, CUDA_ERROR_NO_DEVICE, CUDA_ERROR_INVALID_VALUE,
CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_GRAPHICS_CONTEXT,
CUDA_ERROR_OPERATING_SYSTEM
Description
Returns in *pCudaDeviceCount the number of CUDA-compatible devices corresponding
to the current OpenGL context. Also returns in *pCudaDevices at most cudaDeviceCount
of the CUDA-compatible devices corresponding to the current OpenGL context. If any of the
GPUs being used by the current OpenGL context are not CUDA capable then the call will return
CUDA_ERROR_NO_DEVICE.
The deviceList argument may be any of the following:
‣ CU_GL_DEVICE_LIST_ALL: Query all devices used by the current OpenGL context.
‣ CU_GL_DEVICE_LIST_CURRENT_FRAME: Query the devices used by the current OpenGL
context to render the current frame (in SLI).
‣ CU_GL_DEVICE_LIST_NEXT_FRAME: Query the devices used by the current OpenGL context
to render the next frame (in SLI). Note that this is a prediction, it can't be guaranteed that this is
correct in all cases.
Note:
Note that this function may also return error codes from previous, asynchronous launches.
|
601
Modules
See also:
cuWGLGetDevice, cudaGLGetDevices
CUresult cuGraphicsGLRegisterBuffer
(CUgraphicsResource *pCudaResource, GLuint buffer,
unsigned int Flags)
Registers an OpenGL buffer object.
Parameters
pCudaResource
- Pointer to the returned object handle
buffer
- name of buffer object to be registered
Flags
- Register flags
Returns
CUDA_SUCCESS, CUDA_ERROR_INVALID_HANDLE, CUDA_ERROR_ALREADY_MAPPED,
CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_OPERATING_SYSTEM
Description
Registers the buffer object specified by buffer for access by CUDA. A handle to the registered
object is returned as pCudaResource. The register flags Flags specify the intended usage, as
follows:
‣ CU_GRAPHICS_REGISTER_FLAGS_NONE: Specifies no hints about how this resource will be
used. It is therefore assumed that this resource will be read from and written to by CUDA. This is
the default value.
‣ CU_GRAPHICS_REGISTER_FLAGS_READ_ONLY: Specifies that CUDA will not write to this
resource.
‣ CU_GRAPHICS_REGISTER_FLAGS_WRITE_DISCARD: Specifies that CUDA will not read
from this resource and will write over the entire contents of the resource, so none of the data
previously stored in the resource will be preserved.
Note:
Note that this function may also return error codes from previous, asynchronous launches.
See also:
|
602
Modules
cuGraphicsUnregisterResource, cuGraphicsMapResources, cuGraphicsResourceGetMappedPointer,
cudaGraphicsGLRegisterBuffer
CUresult cuGraphicsGLRegisterImage
(CUgraphicsResource *pCudaResource, GLuint image,
GLenum target, unsigned int Flags)
Register an OpenGL texture or renderbuffer object.
Parameters
pCudaResource
- Pointer to the returned object handle
image
- name of texture or renderbuffer object to be registered
target
- Identifies the type of object specified by image
Flags
- Register flags
Returns
CUDA_SUCCESS, CUDA_ERROR_INVALID_HANDLE, CUDA_ERROR_ALREADY_MAPPED,
CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_OPERATING_SYSTEM
Description
Registers the texture or renderbuffer object specified by image for access by CUDA. A handle to the
registered object is returned as pCudaResource.
target must match the type of the object, and must be one of GL_TEXTURE_2D,
GL_TEXTURE_RECTANGLE, GL_TEXTURE_CUBE_MAP, GL_TEXTURE_3D,
GL_TEXTURE_2D_ARRAY, or GL_RENDERBUFFER.
The register flags Flags specify the intended usage, as follows:
‣ CU_GRAPHICS_REGISTER_FLAGS_NONE: Specifies no hints about how this resource will be
used. It is therefore assumed that this resource will be read from and written to by CUDA. This is
the default value.
‣ CU_GRAPHICS_REGISTER_FLAGS_READ_ONLY: Specifies that CUDA will not write to this
resource.
‣ CU_GRAPHICS_REGISTER_FLAGS_WRITE_DISCARD: Specifies that CUDA will not read
from this resource and will write over the entire contents of the resource, so none of the data
previously stored in the resource will be preserved.
‣ CU_GRAPHICS_REGISTER_FLAGS_SURFACE_LDST: Specifies that CUDA will bind this
resource to a surface reference.
|
603
Modules
‣ CU_GRAPHICS_REGISTER_FLAGS_TEXTURE_GATHER: Specifies that CUDA will perform
texture gather operations on this resource.
The following image formats are supported. For brevity's sake, the list is abbreviated. For ex.,
{GL_R, GL_RG} X {8, 16} would expand to the following 4 formats {GL_R8, GL_R16, GL_RG8,
GL_RG16} :
‣ GL_RED, GL_RG, GL_RGBA, GL_LUMINANCE, GL_ALPHA, GL_LUMINANCE_ALPHA,
GL_INTENSITY
‣ {GL_R, GL_RG, GL_RGBA} X {8, 16, 16F, 32F, 8UI, 16UI, 32UI, 8I, 16I, 32I}
‣ {GL_LUMINANCE, GL_ALPHA, GL_LUMINANCE_ALPHA, GL_INTENSITY} X {8, 16,
16F_ARB, 32F_ARB, 8UI_EXT, 16UI_EXT, 32UI_EXT, 8I_EXT, 16I_EXT, 32I_EXT}
The following image classes are currently disallowed:
‣ Textures with borders
‣ Multisampled renderbuffers
Note:
Note that this function may also return error codes from previous, asynchronous launches.
See also:
cuGraphicsUnregisterResource, cuGraphicsMapResources, cuGraphicsSubResourceGetMappedArray,
cudaGraphicsGLRegisterImage
CUresult cuWGLGetDevice (CUdevice *pDevice,
HGPUNV hGpu)
Gets the CUDA device associated with hGpu.
Parameters
pDevice
- Device associated with hGpu
hGpu
- Handle to a GPU, as queried via WGL_NV_gpu_affinity()
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_VALUE
Description
Returns in *pDevice the CUDA device associated with a hGpu, if applicable.
|
604
Modules
Note:
Note that this function may also return error codes from previous, asynchronous launches.
See also:
cuGLMapBufferObject, cuGLRegisterBufferObject, cuGLUnmapBufferObject,
cuGLUnregisterBufferObject, cuGLUnmapBufferObjectAsync, cuGLSetBufferObjectMapFlags,
cudaWGLGetDevice
6.40.1. OpenGL Interoperability [DEPRECATED]
OpenGL Interoperability
This section describes deprecated OpenGL interoperability functionality.
enum CUGLmap_flags
Flags to map or unmap a resource
Values
CU_GL_MAP_RESOURCE_FLAGS_NONE = 0x00
CU_GL_MAP_RESOURCE_FLAGS_READ_ONLY = 0x01
CU_GL_MAP_RESOURCE_FLAGS_WRITE_DISCARD = 0x02
CUresult cuGLCtxCreate (CUcontext *pCtx, unsigned int Flags,
CUdevice device)
Create a CUDA context for interoperability with OpenGL.
Parameters
pCtx
- Returned CUDA context
Flags
- Options for CUDA context creation
device
- Device on which to create the context
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_VALUE,
CUDA_ERROR_OUT_OF_MEMORY
|
605
Modules
Description
Deprecated This function is deprecated as of Cuda 5.0.
This function is deprecated and should no longer be used. It is no longer necessary to associate a
CUDA context with an OpenGL context in order to achieve maximum interoperability performance.
Note:
Note that this function may also return error codes from previous, asynchronous launches.
See also:
cuCtxCreate, cuGLInit, cuGLMapBufferObject, cuGLRegisterBufferObject,
cuGLUnmapBufferObject, cuGLUnregisterBufferObject, cuGLMapBufferObjectAsync,
cuGLUnmapBufferObjectAsync, cuGLSetBufferObjectMapFlags, cuWGLGetDevice
CUresult cuGLInit (void)
Initializes OpenGL interoperability.
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_UNKNOWN
Description
Deprecated This function is deprecated as of Cuda 3.0.
Initializes OpenGL interoperability. This function is deprecated and calling it is no longer required. It
may fail if the needed OpenGL driver facilities are not available.
Note:
Note that this function may also return error codes from previous, asynchronous launches.
See also:
cuGLMapBufferObject, cuGLRegisterBufferObject, cuGLUnmapBufferObject,
cuGLUnregisterBufferObject, cuGLMapBufferObjectAsync, cuGLUnmapBufferObjectAsync,
cuGLSetBufferObjectMapFlags, cuWGLGetDevice
|
606
Modules
CUresult cuGLMapBufferObject (CUdeviceptr *dptr, size_t *size,
GLuint buffer)
Maps an OpenGL buffer object.
Parameters
dptr
- Returned mapped base pointer
size
- Returned size of mapping
buffer
- The name of the buffer object to map
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_VALUE,
CUDA_ERROR_MAP_FAILED
Description
Deprecated This function is deprecated as of Cuda 3.0.
Maps the buffer object specified by buffer into the address space of the current CUDA context and
returns in *dptr and *size the base pointer and size of the resulting mapping.
There must be a valid OpenGL context bound to the current thread when this function is called. This
must be the same context, or a member of the same shareGroup, as the context that was bound when
the buffer was registered.
All streams in the current CUDA context are synchronized with the current GL context.
Note:
Note that this function may also return error codes from previous, asynchronous launches.
See also:
cuGraphicsMapResources
|
607
Modules
CUresult cuGLMapBufferObjectAsync (CUdeviceptr *dptr, size_t
*size, GLuint buffer, CUstream hStream)
Maps an OpenGL buffer object.
Parameters
dptr
- Returned mapped base pointer
size
- Returned size of mapping
buffer
- The name of the buffer object to map
hStream
- Stream to synchronize
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_VALUE,
CUDA_ERROR_MAP_FAILED
Description
Deprecated This function is deprecated as of Cuda 3.0.
Maps the buffer object specified by buffer into the address space of the current CUDA context and
returns in *dptr and *size the base pointer and size of the resulting mapping.
There must be a valid OpenGL context bound to the current thread when this function is called. This
must be the same context, or a member of the same shareGroup, as the context that was bound when
the buffer was registered.
Stream hStream in the current CUDA context is synchronized with the current GL context.
Note:
Note that this function may also return error codes from previous, asynchronous launches.
See also:
cuGraphicsMapResources
|
608
Modules
CUresult cuGLRegisterBufferObject (GLuint buffer)
Registers an OpenGL buffer object.
Parameters
buffer
- The name of the buffer object to register.
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_ALREADY_MAPPED
Description
Deprecated This function is deprecated as of Cuda 3.0.
Registers the buffer object specified by buffer for access by CUDA. This function must be called
before CUDA can map the buffer object. There must be a valid OpenGL context bound to the current
thread when this function is called, and the buffer name is resolved by that context.
Note:
Note that this function may also return error codes from previous, asynchronous launches.
See also:
cuGraphicsGLRegisterBuffer
CUresult cuGLSetBufferObjectMapFlags (GLuint buffer,
unsigned int Flags)
Set the map flags for an OpenGL buffer object.
Parameters
buffer
- Buffer object to unmap
Flags
- Map flags
Returns
CUDA_SUCCESS, CUDA_ERROR_NOT_INITIALIZED, CUDA_ERROR_INVALID_HANDLE,
CUDA_ERROR_ALREADY_MAPPED, CUDA_ERROR_INVALID_CONTEXT,
|
609
Modules
Description
Deprecated This function is deprecated as of Cuda 3.0.
Sets the map flags for the buffer object specified by buffer.
Changes to Flags will take effect the next time buffer is mapped. The Flags argument may be
any of the following:
‣ CU_GL_MAP_RESOURCE_FLAGS_NONE: Specifies no hints about how this resource will be
used. It is therefore assumed that this resource will be read from and written to by CUDA kernels.
This is the default value.
‣ CU_GL_MAP_RESOURCE_FLAGS_READ_ONLY: Specifies that CUDA kernels which access
this resource will not write to this resource.
‣ CU_GL_MAP_RESOURCE_FLAGS_WRITE_DISCARD: Specifies that CUDA kernels which
access this resource will not read from this resource and will write over the entire contents of the
resource, so none of the data previously stored in the resource will be preserved.
If buffer has not been registered for use with CUDA, then CUDA_ERROR_INVALID_HANDLE
is returned. If buffer is presently mapped for access by CUDA, then
CUDA_ERROR_ALREADY_MAPPED is returned.
There must be a valid OpenGL context bound to the current thread when this function is called. This
must be the same context, or a member of the same shareGroup, as the context that was bound when
the buffer was registered.
Note:
Note that this function may also return error codes from previous, asynchronous launches.
See also:
cuGraphicsResourceSetMapFlags
CUresult cuGLUnmapBufferObject (GLuint buffer)
Unmaps an OpenGL buffer object.
Parameters
buffer
- Buffer object to unmap
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_VALUE
|
610
Modules
Description
Deprecated This function is deprecated as of Cuda 3.0.
Unmaps the buffer object specified by buffer for access by CUDA.
There must be a valid OpenGL context bound to the current thread when this function is called. This
must be the same context, or a member of the same shareGroup, as the context that was bound when
the buffer was registered.
All streams in the current CUDA context are synchronized with the current GL context.
Note:
Note that this function may also return error codes from previous, asynchronous launches.
See also:
cuGraphicsUnmapResources
CUresult cuGLUnmapBufferObjectAsync (GLuint buffer,
CUstream hStream)
Unmaps an OpenGL buffer object.
Parameters
buffer
- Name of the buffer object to unmap
hStream
- Stream to synchronize
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_VALUE
Description
Deprecated This function is deprecated as of Cuda 3.0.
Unmaps the buffer object specified by buffer for access by CUDA.
There must be a valid OpenGL context bound to the current thread when this function is called. This
must be the same context, or a member of the same shareGroup, as the context that was bound when
the buffer was registered.
Stream hStream in the current CUDA context is synchronized with the current GL context.
|
611
Modules
Note:
Note that this function may also return error codes from previous, asynchronous launches.
See also:
cuGraphicsUnmapResources
CUresult cuGLUnregisterBufferObject (GLuint buffer)
Unregister an OpenGL buffer object.
Parameters
buffer
- Name of the buffer object to unregister
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_VALUE
Description
Deprecated This function is deprecated as of Cuda 3.0.
Unregisters the buffer object specified by buffer. This releases any resources associated with the
registered buffer. After this call, the buffer may no longer be mapped for access by CUDA.
There must be a valid OpenGL context bound to the current thread when this function is called. This
must be the same context, or a member of the same shareGroup, as the context that was bound when
the buffer was registered.
Note:
Note that this function may also return error codes from previous, asynchronous launches.
See also:
cuGraphicsUnregisterResource
6.41. Direct3D 9 Interoperability
This section describes the Direct3D 9 interoperability functions of the low-level CUDA driver
application programming interface. Note that mapping of Direct3D 9 resources is performed with the
graphics API agnostic, resource mapping interface described in Graphics Interoperability.
|
612
Modules
Direct3D 9 Interoperability [DEPRECATED]
enum CUd3d9DeviceList
CUDA devices corresponding to a D3D9 device
Values
CU_D3D9_DEVICE_LIST_ALL = 0x01
The CUDA devices for all GPUs used by a D3D9 device
CU_D3D9_DEVICE_LIST_CURRENT_FRAME = 0x02
The CUDA devices for the GPUs used by a D3D9 device in its currently rendering frame
CU_D3D9_DEVICE_LIST_NEXT_FRAME = 0x03
The CUDA devices for the GPUs to be used by a D3D9 device in the next frame
CUresult cuD3D9CtxCreate (CUcontext *pCtx, CUdevice
*pCudaDevice, unsigned int Flags, IDirect3DDevice9
*pD3DDevice)
Create a CUDA context for interoperability with Direct3D 9.
Parameters
pCtx
- Returned newly created CUDA context
pCudaDevice
- Returned pointer to the device on which the context was created
Flags
- Context creation flags (see cuCtxCreate() for details)
pD3DDevice
- Direct3D device to create interoperability context with
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_VALUE, CUDA_ERROR_OUT_OF_MEMORY,
CUDA_ERROR_UNKNOWN
Description
Creates a new CUDA context, enables interoperability for that context with the Direct3D device
pD3DDevice, and associates the created CUDA context with the calling thread. The created
CUcontext will be returned in *pCtx. Direct3D resources from this device may be registered
and mapped through the lifetime of this CUDA context. If pCudaDevice is non-NULL then the
CUdevice on which this CUDA context was created will be returned in *pCudaDevice.
|
613
Modules
On success, this call will increase the internal reference count on pD3DDevice. This reference count
will be decremented upon destruction of this context through cuCtxDestroy(). This context will cease
to function if pD3DDevice is destroyed or encounters an error.
Note that this function is never required for correct functionality. Use of this function will result in
accelerated interoperability only when the operating system is Windows Vista or Windows 7, and the
device pD3DDdevice is not an IDirect3DDevice9Ex. In all other circumstances, this function is not
necessary.
Note:
Note that this function may also return error codes from previous, asynchronous launches.
See also:
cuD3D9GetDevice, cuGraphicsD3D9RegisterResource
CUresult cuD3D9CtxCreateOnDevice (CUcontext *pCtx,
unsigned int flags, IDirect3DDevice9 *pD3DDevice,
CUdevice cudaDevice)
Create a CUDA context for interoperability with Direct3D 9.
Parameters
pCtx
- Returned newly created CUDA context
flags
- Context creation flags (see cuCtxCreate() for details)
pD3DDevice
- Direct3D device to create interoperability context with
cudaDevice
- The CUDA device on which to create the context. This device must be among the devices returned
when querying CU_D3D9_DEVICES_ALL from cuD3D9GetDevices.
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_VALUE, CUDA_ERROR_OUT_OF_MEMORY,
CUDA_ERROR_UNKNOWN
Description
Creates a new CUDA context, enables interoperability for that context with the Direct3D device
pD3DDevice, and associates the created CUDA context with the calling thread. The created
|
614
Modules
CUcontext will be returned in *pCtx. Direct3D resources from this device may be registered and
mapped through the lifetime of this CUDA context.
On success, this call will increase the internal reference count on pD3DDevice. This reference count
will be decremented upon destruction of this context through cuCtxDestroy(). This context will cease
to function if pD3DDevice is destroyed or encounters an error.
Note that this function is never required for correct functionality. Use of this function will result in
accelerated interoperability only when the operating system is Windows Vista or Windows 7, and the
device pD3DDdevice is not an IDirect3DDevice9Ex. In all other circumstances, this function is not
necessary.
Note:
Note that this function may also return error codes from previous, asynchronous launches.
See also:
cuD3D9GetDevices, cuGraphicsD3D9RegisterResource
CUresult cuD3D9GetDevice (CUdevice *pCudaDevice,
const char *pszAdapterName)
Gets the CUDA device corresponding to a display adapter.
Parameters
pCudaDevice
- Returned CUDA device corresponding to pszAdapterName
pszAdapterName
- Adapter name to query for device
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_VALUE, CUDA_ERROR_NOT_FOUND,
CUDA_ERROR_UNKNOWN
Description
Returns in *pCudaDevice the CUDA-compatible device corresponding to the adapter name
pszAdapterName obtained from EnumDisplayDevices() or IDirect3D9::GetAdapterIdentifier().
If no device on the adapter with name pszAdapterName is CUDA-compatible, then the call will
fail.
|
615
Modules
Note:
Note that this function may also return error codes from previous, asynchronous launches.
See also:
cuD3D9CtxCreate, cudaD3D9GetDevice
CUresult cuD3D9GetDevices (unsigned int
*pCudaDeviceCount, CUdevice *pCudaDevices, unsigned
int cudaDeviceCount, IDirect3DDevice9 *pD3D9Device,
CUd3d9DeviceList deviceList)
Gets the CUDA devices corresponding to a Direct3D 9 device.
Parameters
pCudaDeviceCount
- Returned number of CUDA devices corresponding to pD3D9Device
pCudaDevices
- Returned CUDA devices corresponding to pD3D9Device
cudaDeviceCount
- The size of the output device array pCudaDevices
pD3D9Device
- Direct3D 9 device to query for CUDA devices
deviceList
- The set of devices to return. This set may be CU_D3D9_DEVICE_LIST_ALL for all devices,
CU_D3D9_DEVICE_LIST_CURRENT_FRAME for the devices used to render the current frame
(in SLI), or CU_D3D9_DEVICE_LIST_NEXT_FRAME for the devices used to render the next
frame (in SLI).
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_NO_DEVICE, CUDA_ERROR_INVALID_VALUE,
CUDA_ERROR_NOT_FOUND, CUDA_ERROR_UNKNOWN
Description
Returns in *pCudaDeviceCount the number of CUDA-compatible device corresponding to the
Direct3D 9 device pD3D9Device. Also returns in *pCudaDevices at most cudaDeviceCount
of the CUDA-compatible devices corresponding to the Direct3D 9 device pD3D9Device.
If any of the GPUs being used to render pDevice are not CUDA capable then the call will return
CUDA_ERROR_NO_DEVICE.
|
616
Modules
Note:
Note that this function may also return error codes from previous, asynchronous launches.
See also:
cuD3D9CtxCreate, cudaD3D9GetDevices
CUresult cuD3D9GetDirect3DDevice (IDirect3DDevice9
**ppD3DDevice)
Get the Direct3D 9 device against which the current CUDA context was created.
Parameters
ppD3DDevice
- Returned Direct3D device corresponding to CUDA context
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_CONTEXT CUDA_ERROR_INVALID_GRAPHICS_CONTEXT
Description
Returns in *ppD3DDevice the Direct3D device against which this CUDA context was created in
cuD3D9CtxCreate().
Note:
Note that this function may also return error codes from previous, asynchronous launches.
See also:
cuD3D9GetDevice, cudaD3D9GetDirect3DDevice
|
617
Modules
CUresult cuGraphicsD3D9RegisterResource
(CUgraphicsResource *pCudaResource,
IDirect3DResource9 *pD3DResource, unsigned int Flags)
Register a Direct3D 9 resource for access by CUDA.
Parameters
pCudaResource
- Returned graphics resource handle
pD3DResource
- Direct3D resource to register
Flags
- Parameters for resource registration
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_VALUE,
CUDA_ERROR_INVALID_HANDLE, CUDA_ERROR_OUT_OF_MEMORY,
CUDA_ERROR_UNKNOWN
Description
Registers the Direct3D 9 resource pD3DResource for access by CUDA and returns a CUDA handle
to pD3Dresource in pCudaResource. The handle returned in pCudaResource may be used
to map and unmap this resource until it is unregistered. On success this call will increase the internal
reference count on pD3DResource. This reference count will be decremented when this resource is
unregistered through cuGraphicsUnregisterResource().
This call is potentially high-overhead and should not be called every frame in interactive applications.
The type of pD3DResource must be one of the following.
‣ IDirect3DVertexBuffer9: may be accessed through a device pointer
‣ IDirect3DIndexBuffer9: may be accessed through a device pointer
‣ IDirect3DSurface9: may be accessed through an array. Only stand-alone objects of type
IDirect3DSurface9 may be explicitly shared. In particular, individual mipmap levels and faces of
cube maps may not be registered directly. To access individual surfaces associated with a texture,
one must register the base texture object.
‣ IDirect3DBaseTexture9: individual surfaces on this texture may be accessed through an array.
The Flags argument may be used to specify additional parameters at register time. The valid values
for this parameter are
|
618
Modules
‣ CU_GRAPHICS_REGISTER_FLAGS_NONE: Specifies no hints about how this resource will be
used.
‣ CU_GRAPHICS_REGISTER_FLAGS_SURFACE_LDST: Specifies that CUDA will bind this
resource to a surface reference.
‣ CU_GRAPHICS_REGISTER_FLAGS_TEXTURE_GATHER: Specifies that CUDA will perform
texture gather operations on this resource.
Not all Direct3D resources of the above types may be used for interoperability with CUDA. The
following are some limitations.
‣ The primary rendertarget may not be registered with CUDA.
‣ Resources allocated as shared may not be registered with CUDA.
‣ Textures which are not of a format which is 1, 2, or 4 channels of 8, 16, or 32-bit integer or
floating-point data cannot be shared.
‣ Surfaces of depth or stencil formats cannot be shared.
A complete list of supported formats is as follows:
‣ D3DFMT_L8
‣ D3DFMT_L16
‣ D3DFMT_A8R8G8B8
‣ D3DFMT_X8R8G8B8
‣ D3DFMT_G16R16
‣ D3DFMT_A8B8G8R8
‣ D3DFMT_A8
‣ D3DFMT_A8L8
‣ D3DFMT_Q8W8V8U8
‣ D3DFMT_V16U16
‣ D3DFMT_A16B16G16R16F
‣ D3DFMT_A16B16G16R16
‣ D3DFMT_R32F
‣ D3DFMT_G16R16F
‣ D3DFMT_A32B32G32R32F
‣ D3DFMT_G32R32F
‣ D3DFMT_R16F
If Direct3D interoperability is not initialized for this context using cuD3D9CtxCreate then
CUDA_ERROR_INVALID_CONTEXT is returned. If pD3DResource is of incorrect type or
is already registered then CUDA_ERROR_INVALID_HANDLE is returned. If pD3DResource
cannot be registered then CUDA_ERROR_UNKNOWN is returned. If Flags is not one of the above
specified value then CUDA_ERROR_INVALID_VALUE is returned.
|
619
Modules
Note:
Note that this function may also return error codes from previous, asynchronous launches.
See also:
cuD3D9CtxCreate, cuGraphicsUnregisterResource, cuGraphicsMapResources,
cuGraphicsSubResourceGetMappedArray, cuGraphicsResourceGetMappedPointer,
cudaGraphicsD3D9RegisterResource
6.41.1. Direct3D 9 Interoperability [DEPRECATED]
Direct3D 9 Interoperability
This section describes deprecated Direct3D 9 interoperability functionality.
enum CUd3d9map_flags
Flags to map or unmap a resource
Values
CU_D3D9_MAPRESOURCE_FLAGS_NONE = 0x00
CU_D3D9_MAPRESOURCE_FLAGS_READONLY = 0x01
CU_D3D9_MAPRESOURCE_FLAGS_WRITEDISCARD = 0x02
enum CUd3d9register_flags
Flags to register a resource
Values
CU_D3D9_REGISTER_FLAGS_NONE = 0x00
CU_D3D9_REGISTER_FLAGS_ARRAY = 0x01
CUresult cuD3D9MapResources (unsigned int count,
IDirect3DResource9 **ppResource)
Map Direct3D resources for access by CUDA.
Parameters
count
- Number of resources in ppResource
ppResource
- Resources to map for CUDA usage
|
620
Modules
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_HANDLE,
CUDA_ERROR_ALREADY_MAPPED, CUDA_ERROR_UNKNOWN
Description
Deprecated This function is deprecated as of CUDA 3.0.
Maps the count Direct3D resources in ppResource for access by CUDA.
The resources in ppResource may be accessed in CUDA kernels until they are unmapped. Direct3D
should not access any resources while they are mapped by CUDA. If an application does so the results
are undefined.
This function provides the synchronization guarantee that any Direct3D calls issued before
cuD3D9MapResources() will complete before any CUDA kernels issued after cuD3D9MapResources()
begin.
If any of ppResource have not been registered for use with CUDA or if ppResource contains any
duplicate entries, then CUDA_ERROR_INVALID_HANDLE is returned. If any of ppResource are
presently mapped for access by CUDA, then CUDA_ERROR_ALREADY_MAPPED is returned.
Note:
Note that this function may also return error codes from previous, asynchronous launches.
See also:
cuGraphicsMapResources
CUresult cuD3D9RegisterResource (IDirect3DResource9
*pResource, unsigned int Flags)
Register a Direct3D resource for access by CUDA.
Parameters
pResource
- Resource to register for CUDA access
Flags
- Flags for resource registration
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_VALUE,
|
621
Modules
CUDA_ERROR_INVALID_HANDLE, CUDA_ERROR_OUT_OF_MEMORY,
CUDA_ERROR_UNKNOWN
Description
Deprecated This function is deprecated as of CUDA 3.0.
Registers the Direct3D resource pResource for access by CUDA.
If this call is successful, then the application will be able to map and unmap this resource until it is
unregistered through cuD3D9UnregisterResource(). Also on success, this call will increase the internal
reference count on pResource. This reference count will be decremented when this resource is
unregistered through cuD3D9UnregisterResource().
This call is potentially high-overhead and should not be called every frame in interactive applications.
The type of pResource must be one of the following.
‣ IDirect3DVertexBuffer9: Cannot be used with Flags set to
CU_D3D9_REGISTER_FLAGS_ARRAY.
‣ IDirect3DIndexBuffer9: Cannot be used with Flags set to
CU_D3D9_REGISTER_FLAGS_ARRAY.
‣ IDirect3DSurface9: Only stand-alone objects of type IDirect3DSurface9 may be explicitly shared.
In particular, individual mipmap levels and faces of cube maps may not be registered directly. To
access individual surfaces associated with a texture, one must register the base texture object. For
restrictions on the Flags parameter, see type IDirect3DBaseTexture9.
‣ IDirect3DBaseTexture9: When a texture is registered, all surfaces associated with the all mipmap
levels of all faces of the texture will be accessible to CUDA.
The Flags argument specifies the mechanism through which CUDA will access the Direct3D
resource. The following values are allowed.
‣ CU_D3D9_REGISTER_FLAGS_NONE: Specifies that CUDA will access this resource through a
CUdeviceptr. The pointer, size, and (for textures), pitch for each subresource of this allocation may
be queried through cuD3D9ResourceGetMappedPointer(), cuD3D9ResourceGetMappedSize(), and
cuD3D9ResourceGetMappedPitch() respectively. This option is valid for all resource types.
‣ CU_D3D9_REGISTER_FLAGS_ARRAY: Specifies that CUDA will access this resource
through a CUarray queried on a sub-resource basis through cuD3D9ResourceGetMappedArray().
This option is only valid for resources of type IDirect3DSurface9 and subtypes of
IDirect3DBaseTexture9.
Not all Direct3D resources of the above types may be used for interoperability with CUDA. The
following are some limitations.
‣ The primary rendertarget may not be registered with CUDA.
‣ Resources allocated as shared may not be registered with CUDA.
‣ Any resources allocated in D3DPOOL_SYSTEMMEM or D3DPOOL_MANAGED may not be
registered with CUDA.
|
622
Modules
‣ Textures which are not of a format which is 1, 2, or 4 channels of 8, 16, or 32-bit integer or
floating-point data cannot be shared.
‣ Surfaces of depth or stencil formats cannot be shared.
If Direct3D interoperability is not initialized on this context, then
CUDA_ERROR_INVALID_CONTEXT is returned. If pResource is of incorrect type (e.g. is a non-
stand-alone IDirect3DSurface9) or is already registered, then CUDA_ERROR_INVALID_HANDLE is
returned. If pResource cannot be registered then CUDA_ERROR_UNKNOWN is returned.
Note:
Note that this function may also return error codes from previous, asynchronous launches.
See also:
cuGraphicsD3D9RegisterResource
CUresult cuD3D9ResourceGetMappedArray (CUarray *pArray,
IDirect3DResource9 *pResource, unsigned int Face, unsigned int
Level)
Get an array through which to access a subresource of a Direct3D resource which has been mapped for
access by CUDA.
Parameters
pArray
- Returned array corresponding to subresource
pResource
- Mapped resource to access
Face
- Face of resource to access
Level
- Level of resource to access
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_VALUE,
CUDA_ERROR_INVALID_HANDLE, CUDA_ERROR_NOT_MAPPED
Description
Deprecated This function is deprecated as of CUDA 3.0.
|
623
Modules
Returns in *pArray an array through which the subresource of the mapped Direct3D resource
pResource which corresponds to Face and Level may be accessed. The value set in pArray may
change every time that pResource is mapped.
If pResource is not registered then CUDA_ERROR_INVALID_HANDLE is returned. If
pResource was not registered with usage flags CU_D3D9_REGISTER_FLAGS_ARRAY
then CUDA_ERROR_INVALID_HANDLE is returned. If pResource is not mapped then
CUDA_ERROR_NOT_MAPPED is returned.
For usage requirements of Face and Level parameters, see cuD3D9ResourceGetMappedPointer().
Note:
Note that this function may also return error codes from previous, asynchronous launches.
See also:
cuGraphicsSubResourceGetMappedArray
CUresult cuD3D9ResourceGetMappedPitch (size_t *pPitch, size_t
*pPitchSlice, IDirect3DResource9 *pResource, unsigned int Face,
unsigned int Level)
Get the pitch of a subresource of a Direct3D resource which has been mapped for access by CUDA.
Parameters
pPitch
- Returned pitch of subresource
pPitchSlice
- Returned Z-slice pitch of subresource
pResource
- Mapped resource to access
Face
- Face of resource to access
Level
- Level of resource to access
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_VALUE,
CUDA_ERROR_INVALID_HANDLE, CUDA_ERROR_NOT_MAPPED
Description
Deprecated This function is deprecated as of CUDA 3.0.
|
624
Modules
Returns in *pPitch and *pPitchSlice the pitch and Z-slice pitch of the subresource of the
mapped Direct3D resource pResource, which corresponds to Face and Level. The values set in
pPitch and pPitchSlice may change every time that pResource is mapped.
The pitch and Z-slice pitch values may be used to compute the location of a sample on a surface as
follows.
For a 2D surface, the byte offset of the sample at position x, y from the base pointer of the surface is:
y * pitch + (bytes per pixel) * x
For a 3D surface, the byte offset of the sample at position x, y, z from the base pointer of the surface is:
z* slicePitch + y * pitch + (bytes per pixel) * x
Both parameters pPitch and pPitchSlice are optional and may be set to NULL.
If pResource is not of type IDirect3DBaseTexture9 or one of its sub-types or if pResource
has not been registered for use with CUDA, then cudaErrorInvalidResourceHandle is returned. If
pResource was not registered with usage flags CU_D3D9_REGISTER_FLAGS_NONE, then
CUDA_ERROR_INVALID_HANDLE is returned. If pResource is not mapped for access by
CUDA then CUDA_ERROR_NOT_MAPPED is returned.
For usage requirements of Face and Level parameters, see cuD3D9ResourceGetMappedPointer().
Note:
Note that this function may also return error codes from previous, asynchronous launches.
See also:
cuGraphicsSubResourceGetMappedArray
CUresult cuD3D9ResourceGetMappedPointer (CUdeviceptr
*pDevPtr, IDirect3DResource9 *pResource, unsigned int Face,
unsigned int Level)
Get the pointer through which to access a subresource of a Direct3D resource which has been mapped
for access by CUDA.
Parameters
pDevPtr
- Returned pointer corresponding to subresource
pResource
- Mapped resource to access
Face
- Face of resource to access
|
625
Modules
Level
- Level of resource to access
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_VALUE,
CUDA_ERROR_INVALID_HANDLE, CUDA_ERROR_NOT_MAPPED
Description
Deprecated This function is deprecated as of CUDA 3.0.
Returns in *pDevPtr the base pointer of the subresource of the mapped Direct3D resource
pResource, which corresponds to Face and Level. The value set in pDevPtr may change every
time that pResource is mapped.
If pResource is not registered, then CUDA_ERROR_INVALID_HANDLE is returned. If
pResource was not registered with usage flags CU_D3D9_REGISTER_FLAGS_NONE,
then CUDA_ERROR_INVALID_HANDLE is returned. If pResource is not mapped, then
CUDA_ERROR_NOT_MAPPED is returned.
If pResource is of type IDirect3DCubeTexture9, then Face must one of the values enumerated
by type D3DCUBEMAP_FACES. For all other types Face must be 0. If Face is invalid, then
CUDA_ERROR_INVALID_VALUE is returned.
If pResource is of type IDirect3DBaseTexture9, then Level must correspond to a valid mipmap
level. At present only mipmap level 0 is supported. For all other types Level must be 0. If Level is
invalid, then CUDA_ERROR_INVALID_VALUE is returned.
Note:
Note that this function may also return error codes from previous, asynchronous launches.
See also:
cuGraphicsResourceGetMappedPointer
CUresult cuD3D9ResourceGetMappedSize (size_t *pSize,
IDirect3DResource9 *pResource, unsigned int Face, unsigned int
Level)
Get the size of a subresource of a Direct3D resource which has been mapped for access by CUDA.
Parameters
pSize
- Returned size of subresource
|
626
Modules
pResource
- Mapped resource to access
Face
- Face of resource to access
Level
- Level of resource to access
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_VALUE,
CUDA_ERROR_INVALID_HANDLE, CUDA_ERROR_NOT_MAPPED
Description
Deprecated This function is deprecated as of CUDA 3.0.
Returns in *pSize the size of the subresource of the mapped Direct3D resource pResource, which
corresponds to Face and Level. The value set in pSize may change every time that pResource is
mapped.
If pResource has not been registered for use with CUDA, then
CUDA_ERROR_INVALID_HANDLE is returned. If pResource was not registered with usage flags
CU_D3D9_REGISTER_FLAGS_NONE, then CUDA_ERROR_INVALID_HANDLE is returned. If
pResource is not mapped for access by CUDA, then CUDA_ERROR_NOT_MAPPED is returned.
For usage requirements of Face and Level parameters, see cuD3D9ResourceGetMappedPointer.
Note:
Note that this function may also return error codes from previous, asynchronous launches.
See also:
cuGraphicsResourceGetMappedPointer
CUresult cuD3D9ResourceGetSurfaceDimensions (size_t
*pWidth, size_t *pHeight, size_t *pDepth, IDirect3DResource9
*pResource, unsigned int Face, unsigned int Level)
Get the dimensions of a registered surface.
Parameters
pWidth
- Returned width of surface
|
627
Modules
pHeight
- Returned height of surface
pDepth
- Returned depth of surface
pResource
- Registered resource to access
Face
- Face of resource to access
Level
- Level of resource to access
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_VALUE,
CUDA_ERROR_INVALID_HANDLE
Description
Deprecated This function is deprecated as of CUDA 3.0.
Returns in *pWidth, *pHeight, and *pDepth the dimensions of the subresource of the mapped
Direct3D resource pResource, which corresponds to Face and Level.
Because anti-aliased surfaces may have multiple samples per pixel, it is possible that the dimensions of
a resource will be an integer factor larger than the dimensions reported by the Direct3D runtime.
The parameters pWidth, pHeight, and pDepth are optional. For 2D surfaces, the value returned in
*pDepth will be 0.
If pResource is not of type IDirect3DBaseTexture9 or IDirect3DSurface9 or if pResource has not
been registered for use with CUDA, then CUDA_ERROR_INVALID_HANDLE is returned.
For usage requirements of Face and Level parameters, see cuD3D9ResourceGetMappedPointer().
Note:
Note that this function may also return error codes from previous, asynchronous launches.
See also:
cuGraphicsSubResourceGetMappedArray
|
628
Modules
CUresult cuD3D9ResourceSetMapFlags (IDirect3DResource9
*pResource, unsigned int Flags)
Set usage flags for mapping a Direct3D resource.
Parameters
pResource
- Registered resource to set flags for
Flags
- Parameters for resource mapping
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_VALUE,
CUDA_ERROR_INVALID_HANDLE, CUDA_ERROR_ALREADY_MAPPED
Description
Deprecated This function is deprecated as of Cuda 3.0.
Set Flags for mapping the Direct3D resource pResource.
Changes to Flags will take effect the next time pResource is mapped. The Flags argument may
be any of the following:
‣ CU_D3D9_MAPRESOURCE_FLAGS_NONE: Specifies no hints about how this resource will be
used. It is therefore assumed that this resource will be read from and written to by CUDA kernels.
This is the default value.
‣ CU_D3D9_MAPRESOURCE_FLAGS_READONLY: Specifies that CUDA kernels which access
this resource will not write to this resource.
‣ CU_D3D9_MAPRESOURCE_FLAGS_WRITEDISCARD: Specifies that CUDA kernels which
access this resource will not read from this resource and will write over the entire contents of the
resource, so none of the data previously stored in the resource will be preserved.
If pResource has not been registered for use with CUDA, then
CUDA_ERROR_INVALID_HANDLE is returned. If pResource is presently mapped for access by
CUDA, then CUDA_ERROR_ALREADY_MAPPED is returned.
Note:
Note that this function may also return error codes from previous, asynchronous launches.
See also:
cuGraphicsResourceSetMapFlags
|
629
Modules
CUresult cuD3D9UnmapResources (unsigned int count,
IDirect3DResource9 **ppResource)
Unmaps Direct3D resources.
Parameters
count
- Number of resources to unmap for CUDA
ppResource
- Resources to unmap for CUDA
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_HANDLE,
CUDA_ERROR_NOT_MAPPED, CUDA_ERROR_UNKNOWN
Description
Deprecated This function is deprecated as of CUDA 3.0.
Unmaps the count Direct3D resources in ppResource.
This function provides the synchronization guarantee that any CUDA kernels issued
before cuD3D9UnmapResources() will complete before any Direct3D calls issued after
cuD3D9UnmapResources() begin.
If any of ppResource have not been registered for use with CUDA or if ppResource contains any
duplicate entries, then CUDA_ERROR_INVALID_HANDLE is returned. If any of ppResource are
not presently mapped for access by CUDA, then CUDA_ERROR_NOT_MAPPED is returned.
Note:
Note that this function may also return error codes from previous, asynchronous launches.
See also:
cuGraphicsUnmapResources
|
630
Modules
CUresult cuD3D9UnregisterResource (IDirect3DResource9
*pResource)
Unregister a Direct3D resource.
Parameters
pResource
- Resource to unregister
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_HANDLE,
CUDA_ERROR_UNKNOWN
Description
Deprecated This function is deprecated as of CUDA 3.0.
Unregisters the Direct3D resource pResource so it is not accessible by CUDA unless registered
again.
If pResource is not registered, then CUDA_ERROR_INVALID_HANDLE is returned.
Note:
Note that this function may also return error codes from previous, asynchronous launches.
See also:
cuGraphicsUnregisterResource
6.42. Direct3D 10 Interoperability
This section describes the Direct3D 10 interoperability functions of the low-level CUDA driver
application programming interface. Note that mapping of Direct3D 10 resources is performed with the
graphics API agnostic, resource mapping interface described in Graphics Interoperability.
Direct3D 10 Interoperability [DEPRECATED]
enum CUd3d10DeviceList
CUDA devices corresponding to a D3D10 device
|
631
Modules
Values
CU_D3D10_DEVICE_LIST_ALL = 0x01
The CUDA devices for all GPUs used by a D3D10 device
CU_D3D10_DEVICE_LIST_CURRENT_FRAME = 0x02
The CUDA devices for the GPUs used by a D3D10 device in its currently rendering frame
CU_D3D10_DEVICE_LIST_NEXT_FRAME = 0x03
The CUDA devices for the GPUs to be used by a D3D10 device in the next frame
CUresult cuD3D10GetDevice (CUdevice *pCudaDevice,
IDXGIAdapter *pAdapter)
Gets the CUDA device corresponding to a display adapter.
Parameters
pCudaDevice
- Returned CUDA device corresponding to pAdapter
pAdapter
- Adapter to query for CUDA device
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_VALUE, CUDA_ERROR_NOT_FOUND,
CUDA_ERROR_UNKNOWN
Description
Returns in *pCudaDevice the CUDA-compatible device corresponding to the adapter pAdapter
obtained from IDXGIFactory::EnumAdapters.
If no device on pAdapter is CUDA-compatible then the call will fail.
Note:
Note that this function may also return error codes from previous, asynchronous launches.
See also:
cuD3D10GetDevices, cudaD3D10GetDevice
|
632
Modules
CUresult cuD3D10GetDevices (unsigned int
*pCudaDeviceCount, CUdevice *pCudaDevices, unsigned
int cudaDeviceCount, ID3D10Device *pD3D10Device,
CUd3d10DeviceList deviceList)
Gets the CUDA devices corresponding to a Direct3D 10 device.
Parameters
pCudaDeviceCount
- Returned number of CUDA devices corresponding to pD3D10Device
pCudaDevices
- Returned CUDA devices corresponding to pD3D10Device
cudaDeviceCount
- The size of the output device array pCudaDevices
pD3D10Device
- Direct3D 10 device to query for CUDA devices
deviceList
- The set of devices to return. This set may be CU_D3D10_DEVICE_LIST_ALL for all devices,
CU_D3D10_DEVICE_LIST_CURRENT_FRAME for the devices used to render the current frame
(in SLI), or CU_D3D10_DEVICE_LIST_NEXT_FRAME for the devices used to render the next
frame (in SLI).
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_NO_DEVICE, CUDA_ERROR_INVALID_VALUE,
CUDA_ERROR_NOT_FOUND, CUDA_ERROR_UNKNOWN
Description
Returns in *pCudaDeviceCount the number of CUDA-compatible device corresponding
to the Direct3D 10 device pD3D10Device. Also returns in *pCudaDevices at most
cudaDeviceCount of the CUDA-compatible devices corresponding to the Direct3D 10 device
pD3D10Device.
If any of the GPUs being used to render pDevice are not CUDA capable then the call will return
CUDA_ERROR_NO_DEVICE.
Note:
Note that this function may also return error codes from previous, asynchronous launches.
See also:
|
633
Modules
cuD3D10GetDevice, cudaD3D10GetDevices
CUresult cuGraphicsD3D10RegisterResource
(CUgraphicsResource *pCudaResource, ID3D10Resource
*pD3DResource, unsigned int Flags)
Register a Direct3D 10 resource for access by CUDA.
Parameters
pCudaResource
- Returned graphics resource handle
pD3DResource
- Direct3D resource to register
Flags
- Parameters for resource registration
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_VALUE,
CUDA_ERROR_INVALID_HANDLE, CUDA_ERROR_OUT_OF_MEMORY,
CUDA_ERROR_UNKNOWN
Description
Registers the Direct3D 10 resource pD3DResource for access by CUDA and returns a CUDA handle
to pD3Dresource in pCudaResource. The handle returned in pCudaResource may be used
to map and unmap this resource until it is unregistered. On success this call will increase the internal
reference count on pD3DResource. This reference count will be decremented when this resource is
unregistered through cuGraphicsUnregisterResource().
This call is potentially high-overhead and should not be called every frame in interactive applications.
The type of pD3DResource must be one of the following.
‣ ID3D10Buffer: may be accessed through a device pointer.
‣ ID3D10Texture1D: individual subresources of the texture may be accessed via arrays
‣ ID3D10Texture2D: individual subresources of the texture may be accessed via arrays
‣ ID3D10Texture3D: individual subresources of the texture may be accessed via arrays
The Flags argument may be used to specify additional parameters at register time. The valid values
for this parameter are
‣ CU_GRAPHICS_REGISTER_FLAGS_NONE: Specifies no hints about how this resource will be
used.
|
634
Modules
‣ CU_GRAPHICS_REGISTER_FLAGS_SURFACE_LDST: Specifies that CUDA will bind this
resource to a surface reference.
‣ CU_GRAPHICS_REGISTER_FLAGS_TEXTURE_GATHER: Specifies that CUDA will perform
texture gather operations on this resource.
Not all Direct3D resources of the above types may be used for interoperability with CUDA. The
following are some limitations.
‣ The primary rendertarget may not be registered with CUDA.
‣ Textures which are not of a format which is 1, 2, or 4 channels of 8, 16, or 32-bit integer or
floating-point data cannot be shared.
‣ Surfaces of depth or stencil formats cannot be shared.
A complete list of supported DXGI formats is as follows. For compactness the notation A_{B,C,D}
represents A_B, A_C, and A_D.
‣ DXGI_FORMAT_A8_UNORM
‣ DXGI_FORMAT_B8G8R8A8_UNORM
‣ DXGI_FORMAT_B8G8R8X8_UNORM
‣ DXGI_FORMAT_R16_FLOAT
‣ DXGI_FORMAT_R16G16B16A16_{FLOAT,SINT,SNORM,UINT,UNORM}
‣ DXGI_FORMAT_R16G16_{FLOAT,SINT,SNORM,UINT,UNORM}
‣ DXGI_FORMAT_R16_{SINT,SNORM,UINT,UNORM}
‣ DXGI_FORMAT_R32_FLOAT
‣ DXGI_FORMAT_R32G32B32A32_{FLOAT,SINT,UINT}
‣ DXGI_FORMAT_R32G32_{FLOAT,SINT,UINT}
‣ DXGI_FORMAT_R32_{SINT,UINT}
‣ DXGI_FORMAT_R8G8B8A8_{SINT,SNORM,UINT,UNORM,UNORM_SRGB}
‣ DXGI_FORMAT_R8G8_{SINT,SNORM,UINT,UNORM}
‣ DXGI_FORMAT_R8_{SINT,SNORM,UINT,UNORM}
If pD3DResource is of incorrect type or is already registered then
CUDA_ERROR_INVALID_HANDLE is returned. If pD3DResource cannot be registered then
CUDA_ERROR_UNKNOWN is returned. If Flags is not one of the above specified value then
CUDA_ERROR_INVALID_VALUE is returned.
Note:
Note that this function may also return error codes from previous, asynchronous launches.
See also:
|
635
Modules
cuGraphicsUnregisterResource, cuGraphicsMapResources, cuGraphicsSubResourceGetMappedArray,
cuGraphicsResourceGetMappedPointer, cudaGraphicsD3D10RegisterResource
6.42.1. Direct3D 10 Interoperability [DEPRECATED]
Direct3D 10 Interoperability
This section describes deprecated Direct3D 10 interoperability functionality.
enum CUD3D10map_flags
Flags to map or unmap a resource
Values
CU_D3D10_MAPRESOURCE_FLAGS_NONE = 0x00
CU_D3D10_MAPRESOURCE_FLAGS_READONLY = 0x01
CU_D3D10_MAPRESOURCE_FLAGS_WRITEDISCARD = 0x02
enum CUD3D10register_flags
Flags to register a resource
Values
CU_D3D10_REGISTER_FLAGS_NONE = 0x00
CU_D3D10_REGISTER_FLAGS_ARRAY = 0x01
CUresult cuD3D10CtxCreate (CUcontext *pCtx, CUdevice
*pCudaDevice, unsigned int Flags, ID3D10Device *pD3DDevice)
Create a CUDA context for interoperability with Direct3D 10.
Parameters
pCtx
- Returned newly created CUDA context
pCudaDevice
- Returned pointer to the device on which the context was created
Flags
- Context creation flags (see cuCtxCreate() for details)
pD3DDevice
- Direct3D device to create interoperability context with
|
636

 

 

 

 

 

 

 

Content      ..     7      8      9      10     ..