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

 

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

 

Search            copyright infringement  

 

   

 

    

 

Content      ..     1      2      3      4      ..

 

 

 

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

 

 

Modules
CUresult cuDeviceGetUuid_v2 (CUuuid *uuid, CUdevice
dev)
Return an UUID for the device (11.4+).
Parameters
uuid
- Returned UUID
dev
- Device to get identifier string for
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_VALUE, CUDA_ERROR_INVALID_DEVICE
Description
Returns 16-octets identifying the device dev in the structure pointed by the uuid. If the device is in
MIG mode, returns its MIG UUID which uniquely identifies the subscribed MIG compute instance.
Note:
Note that this function may also return error codes from previous, asynchronous launches.
See also:
cuDeviceGetAttribute, cuDeviceGetCount, cuDeviceGetName, cuDeviceGetLuid, cuDeviceGet,
cuDeviceTotalMem, cudaGetDeviceProperties
CUresult cuDeviceSetMemPool (CUdevice dev,
CUmemoryPool pool)
Sets the current memory pool of a device.
Returns
CUDA_SUCCESS, CUDA_ERROR_INVALID_VALUE
|
112
Modules
Description
The memory pool must be local to the specified device. cuMemAllocAsync allocates from the current
mempool of the provided stream's device. By default, a device's current memory pool is its default
memory pool.
Note:
Use cuMemAllocFromPoolAsync to specify asynchronous allocations from a device different than the
one the stream runs on.
See also:
cuDeviceGetDefaultMemPool, cuDeviceGetMemPool, cuMemPoolCreate, cuMemPoolDestroy,
cuMemAllocFromPoolAsync
CUresult cuDeviceTotalMem (size_t *bytes, CUdevice
dev)
Returns the total amount of memory on the device.
Parameters
bytes
- Returned memory available on device in bytes
dev
- Device handle
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_VALUE,
CUDA_ERROR_INVALID_DEVICE
Description
Returns in *bytes the total amount of memory available on the device dev in bytes.
Note:
Note that this function may also return error codes from previous, asynchronous launches.
See also:
|
113
Modules
cuDeviceGetAttribute, cuDeviceGetCount, cuDeviceGetName, cuDeviceGetUuid, cuDeviceGet,
cuDeviceGetExecAffinitySupport, cudaMemGetInfo
CUresult cuFlushGPUDirectRDMAWrites
(CUflushGPUDirectRDMAWritesTarget target,
CUflushGPUDirectRDMAWritesScope scope)
Blocks until remote writes are visible to the specified scope.
Parameters
target
- The target of the operation, see CUflushGPUDirectRDMAWritesTarget
scope
- The scope of the operation, see CUflushGPUDirectRDMAWritesScope
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_VALUE,
Description
Blocks until GPUDirect RDMA writes to the target context via mappings created through APIs like
nvidia_p2p_get_pages (see https://docs.nvidia.com/cuda/gpudirect-rdma for more information), are
visible to the specified scope.
If the scope equals or lies within the scope indicated by
CU_DEVICE_ATTRIBUTE_GPU_DIRECT_RDMA_WRITES_ORDERING, the call will be a no-op
and can be safely omitted for performance. This can be determined by comparing the numerical values
between the two enums, with smaller scopes having smaller values.
On platforms that support GPUDirect RDMA writes via more than one path in hardware (see
CU_MEM_RANGE_FLAG_DMA_BUF_MAPPING_TYPE_PCIE), the user should consider
those paths as belonging to separate ordering domains. Note that in such cases CUDA driver
will report both RDMA writes ordering and RDMA write scope as ALL_DEVICES and a call to
cuFlushGPUDirectRDMA will be a no-op, but when these multiple paths are used simultaneously, it is
the user's responsibility to ensure ordering by using mechanisms outside the scope of CUDA.
Users may query support for this API via
CU_DEVICE_ATTRIBUTE_FLUSH_FLUSH_GPU_DIRECT_RDMA_OPTIONS.
Note:
Note that this function may also return error codes from previous, asynchronous launches.
|
114
Modules
6.6.
Device Management [DEPRECATED]
This section describes the device management functions of the low-level CUDA driver application
programming interface.
CUresult cuDeviceComputeCapability (int *major, int
*minor, CUdevice dev)
Returns the compute capability of the device.
Parameters
major
- Major revision number
minor
- Minor revision number
dev
- Device handle
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_VALUE,
CUDA_ERROR_INVALID_DEVICE
Description
Deprecated
This function was deprecated as of CUDA 5.0 and its functionality superseded by
cuDeviceGetAttribute().
Returns in *major and *minor the major and minor revision numbers that define the compute
capability of the device dev.
Note:
Note that this function may also return error codes from previous, asynchronous launches.
See also:
cuDeviceGetAttribute, cuDeviceGetCount, cuDeviceGetName, cuDeviceGetUuid, cuDeviceGet,
cuDeviceTotalMem
|
115
Modules
CUresult cuDeviceGetProperties (CUdevprop *prop,
CUdevice dev)
Returns properties for a selected device.
Parameters
prop
- Returned properties of device
dev
- Device to get properties for
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_VALUE,
CUDA_ERROR_INVALID_DEVICE
Description
Deprecated
This function was deprecated as of CUDA 5.0 and replaced by cuDeviceGetAttribute().
Returns in *prop the properties of device dev. The CUdevprop structure is defined as:
‎
typedef struct CUdevprop_st {
int maxThreadsPerBlock;
int maxThreadsDim[3];
int maxGridSize[3];
int sharedMemPerBlock;
int totalConstantMemory;
int SIMDWidth;
int memPitch;
int regsPerBlock;
int clockRate;
int textureAlign
} CUdevprop;
where:
‣ maxThreadsPerBlock is the maximum number of threads per block;
‣ maxThreadsDim[3] is the maximum sizes of each dimension of a block;
‣ maxGridSize[3] is the maximum sizes of each dimension of a grid;
‣ sharedMemPerBlock is the total amount of shared memory available per block in bytes;
‣ totalConstantMemory is the total amount of constant memory available on the device in bytes;
‣ SIMDWidth is the warp size;
‣ memPitch is the maximum pitch allowed by the memory copy functions that involve memory
regions allocated through cuMemAllocPitch();
‣ regsPerBlock is the total number of registers available per block;
‣ clockRate is the clock frequency in kilohertz;
|
116
Modules
‣ textureAlign is the alignment requirement; texture base addresses that are aligned to textureAlign
bytes do not need an offset applied to texture fetches.
Note:
Note that this function may also return error codes from previous, asynchronous launches.
See also:
cuDeviceGetAttribute, cuDeviceGetCount, cuDeviceGetName, cuDeviceGetUuid, cuDeviceGet,
cuDeviceTotalMem
6.7.
Primary Context Management
This section describes the primary context management functions of the low-level CUDA driver
application programming interface.
The primary context is unique per device and shared with the CUDA runtime API. These functions
allow integration with other libraries using CUDA.
CUresult cuDevicePrimaryCtxGetState (CUdevice dev,
unsigned int *flags, int *active)
Get the state of the primary context.
Parameters
dev
- Device to get primary context flags for
flags
- Pointer to store flags
active
- Pointer to store context state; 0 = inactive, 1 = active
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_DEVICE, CUDA_ERROR_INVALID_VALUE,
Description
Returns in *flags the flags for the primary context of dev, and in *active whether it is active. See
cuDevicePrimaryCtxSetFlags for flag values.
|
117
Modules
Note:
Note that this function may also return error codes from previous, asynchronous launches.
See also:
cuDevicePrimaryCtxSetFlags, cuCtxGetFlags, cuCtxSetFlags, cudaGetDeviceFlags
CUresult cuDevicePrimaryCtxRelease (CUdevice dev)
Release the primary context on the GPU.
Parameters
dev
- Device which primary context is released
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_DEVICE, CUDA_ERROR_INVALID_CONTEXT
Description
Releases the primary context interop on the device. A retained context should always be released once
the user is done using it. The context is automatically reset once the last reference to it is released. This
behavior is different when the primary context was retained by the CUDA runtime from CUDA 4.0 and
earlier. In this case, the primary context remains always active.
Releasing a primary context that has not been previously retained will fail with
CUDA_ERROR_INVALID_CONTEXT.
Please note that unlike cuCtxDestroy() this method does not pop the context from stack in any
circumstances.
Note:
Note that this function may also return error codes from previous, asynchronous launches.
See also:
cuDevicePrimaryCtxRetain, cuCtxDestroy, cuCtxGetApiVersion, cuCtxGetCacheConfig,
cuCtxGetDevice, cuCtxGetFlags, cuCtxGetLimit, cuCtxPopCurrent, cuCtxPushCurrent,
cuCtxSetCacheConfig, cuCtxSetLimit, cuCtxSynchronize
|
118
Modules
CUresult cuDevicePrimaryCtxReset (CUdevice dev)
Destroy all allocations and reset all state on the primary context.
Parameters
dev
- Device for which primary context is destroyed
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_DEVICE, CUDA_ERROR_PRIMARY_CONTEXT_ACTIVE
Description
Explicitly destroys and cleans up all resources associated with the current device in the current process.
Note that it is responsibility of the calling function to ensure that no other module in the process is
using the device any more. For that reason it is recommended to use cuDevicePrimaryCtxRelease()
in most cases. However it is safe for other modules to call cuDevicePrimaryCtxRelease() even after
resetting the device. Resetting the primary context does not release it, an application that has retained
the primary context should explicitly release its usage.
Note:
Note that this function may also return error codes from previous, asynchronous launches.
See also:
cuDevicePrimaryCtxRetain, cuDevicePrimaryCtxRelease, cuCtxGetApiVersion,
cuCtxGetCacheConfig, cuCtxGetDevice, cuCtxGetFlags, cuCtxGetLimit, cuCtxPopCurrent,
cuCtxPushCurrent, cuCtxSetCacheConfig, cuCtxSetLimit, cuCtxSynchronize, cudaDeviceReset
CUresult cuDevicePrimaryCtxRetain (CUcontext *pctx,
CUdevice dev)
Retain the primary context on the GPU.
Parameters
pctx
- Returned context handle of the new context
dev
- Device for which primary context is requested
|
119
Modules
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_DEVICE,
CUDA_ERROR_INVALID_VALUE, CUDA_ERROR_OUT_OF_MEMORY,
CUDA_ERROR_UNKNOWN
Description
Retains the primary context on the device. Once the user successfully retains the primary
context, the primary context will be active and available to the user until the user releases it with
cuDevicePrimaryCtxRelease() or resets it with cuDevicePrimaryCtxReset(). Unlike cuCtxCreate() the
newly retained context is not pushed onto the stack.
Retaining the primary context for the first time will fail with CUDA_ERROR_UNKNOWN
if the compute mode of the device is CU_COMPUTEMODE_PROHIBITED. The function
cuDeviceGetAttribute() can be used with CU_DEVICE_ATTRIBUTE_COMPUTE_MODE to
determine the compute mode of the device. The nvidia-smi tool can be used to set the compute mode
for devices. Documentation for nvidia-smi can be obtained by passing a -h option to it.
Please note that the primary context always supports pinned allocations. Other flags can be specified by
cuDevicePrimaryCtxSetFlags().
Note:
Note that this function may also return error codes from previous, asynchronous launches.
See also:
cuDevicePrimaryCtxRelease, cuDevicePrimaryCtxSetFlags, cuCtxCreate, cuCtxGetApiVersion,
cuCtxGetCacheConfig, cuCtxGetDevice, cuCtxGetFlags, cuCtxGetLimit, cuCtxPopCurrent,
cuCtxPushCurrent, cuCtxSetCacheConfig, cuCtxSetLimit, cuCtxSynchronize
CUresult cuDevicePrimaryCtxSetFlags (CUdevice dev,
unsigned int flags)
Set flags for the primary context.
Parameters
dev
- Device for which the primary context flags are set
flags
- New flags for the device
|
120
Modules
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_DEVICE, CUDA_ERROR_INVALID_VALUE,
Description
Sets the flags for the primary context on the device overwriting perviously set ones.
The three LSBs of the flags parameter can be used to control how the OS thread, which owns the
CUDA context at the time of an API call, interacts with the OS scheduler when waiting for results from
the GPU. Only one of the scheduling flags can be set when creating a context.
‣ CU_CTX_SCHED_SPIN: Instruct CUDA to actively spin when waiting for results from the GPU.
This can decrease latency when waiting for the GPU, but may lower the performance of CPU
threads if they are performing work in parallel with the CUDA thread.
‣ CU_CTX_SCHED_YIELD: Instruct CUDA to yield its thread when waiting for results from the
GPU. This can increase latency when waiting for the GPU, but can increase the performance of
CPU threads performing work in parallel with the GPU.
‣ CU_CTX_SCHED_BLOCKING_SYNC: Instruct CUDA to block the CPU thread on a
synchronization primitive when waiting for the GPU to finish work.
‣ CU_CTX_BLOCKING_SYNC: Instruct CUDA to block the CPU thread on a synchronization
primitive when waiting for the GPU to finish work.
Deprecated: This flag was deprecated as of CUDA 4.0 and was replaced with
CU_CTX_SCHED_BLOCKING_SYNC.
‣ CU_CTX_SCHED_AUTO: The default value if the flags parameter is zero, uses a heuristic
based on the number of active CUDA contexts in the process C and the number of logical
processors in the system P. If C > P, then CUDA will yield to other OS threads when waiting for
the GPU (CU_CTX_SCHED_YIELD), otherwise CUDA will not yield while waiting for results
and actively spin on the processor (CU_CTX_SCHED_SPIN). Additionally, on Tegra devices,
CU_CTX_SCHED_AUTO uses a heuristic based on the power profile of the platform and may
choose CU_CTX_SCHED_BLOCKING_SYNC for low-powered devices.
‣ CU_CTX_LMEM_RESIZE_TO_MAX: Instruct CUDA to not reduce local memory after resizing
local memory for a kernel. This can prevent thrashing by local memory allocations when launching
many kernels with high local memory usage at the cost of potentially increased memory usage.
Deprecated: This flag is deprecated and the behavior enabled by this flag is now the default and
cannot be disabled.
‣ CU_CTX_COREDUMP_ENABLE: If GPU coredumps have not been enabled globally with
cuCoredumpSetAttributeGlobal or environment variables, this flag can be set during context
creation to instruct CUDA to create a coredump if this context raises an exception during
execution. These environment variables are described in the CUDA-GDB user guide under the
|
121
Modules
"GPU core dump support" section. The initial settings will be taken from the global settings at
the time of context creation. The other settings that control coredump output can be modified by
calling cuCoredumpSetAttribute from the created context after it becomes current.
‣ CU_CTX_USER_COREDUMP_ENABLE: If user-triggered GPU coredumps have not been
enabled globally with cuCoredumpSetAttributeGlobal or environment variables, this flag can be
set during context creation to instruct CUDA to create a coredump if data is written to a certain
pipe that is present in the OS space. These environment variables are described in the CUDA-GDB
user guide under the "GPU core dump support" section. It is important to note that the pipe name
*must* be set with cuCoredumpSetAttributeGlobal before creating the context if this flag is used.
Setting this flag implies that CU_CTX_COREDUMP_ENABLE is set. The initial settings will
be taken from the global settings at the time of context creation. The other settings that control
coredump output can be modified by calling cuCoredumpSetAttribute from the created context
after it becomes current.
‣ CU_CTX_SYNC_MEMOPS: Ensures that synchronous memory operations initiated on
this context will always synchronize. See further documentation in the section titled "API
Synchronization behavior" to learn more about cases when synchronous memory operations can
exhibit asynchronous behavior.
Note:
Note that this function may also return error codes from previous, asynchronous launches.
See also:
cuDevicePrimaryCtxRetain, cuDevicePrimaryCtxGetState, cuCtxCreate, cuCtxGetFlags,
cuCtxSetFlags, cudaSetDeviceFlags
6.8.
Context Management
This section describes the context management functions of the low-level CUDA driver application
programming interface.
Please note that some functions are described in Primary Context Management section.
|
122
Modules
CUresult cuCtxCreate (CUcontext *pctx, unsigned int
flags, CUdevice dev)
Create a CUDA context.
Parameters
pctx
- Returned context handle of the new context
flags
- Context creation flags
dev
- Device to create context on
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_DEVICE,
CUDA_ERROR_INVALID_VALUE, CUDA_ERROR_OUT_OF_MEMORY,
CUDA_ERROR_UNKNOWN
Description
Note:
In most cases it is recommended to use cuDevicePrimaryCtxRetain.
Creates a new CUDA context and associates it with the calling thread. The flags parameter is
described below. The context is created with a usage count of 1 and the caller of cuCtxCreate()
must call cuCtxDestroy() when done using the context. If a context is already current to the
thread, it is supplanted by the newly created context and may be restored by a subsequent call to
cuCtxPopCurrent().
The three LSBs of the flags parameter can be used to control how the OS thread, which owns the
CUDA context at the time of an API call, interacts with the OS scheduler when waiting for results from
the GPU. Only one of the scheduling flags can be set when creating a context.
‣ CU_CTX_SCHED_SPIN: Instruct CUDA to actively spin when waiting for results from the GPU.
This can decrease latency when waiting for the GPU, but may lower the performance of CPU
threads if they are performing work in parallel with the CUDA thread.
‣ CU_CTX_SCHED_YIELD: Instruct CUDA to yield its thread when waiting for results from the
GPU. This can increase latency when waiting for the GPU, but can increase the performance of
CPU threads performing work in parallel with the GPU.
‣ CU_CTX_SCHED_BLOCKING_SYNC: Instruct CUDA to block the CPU thread on a
synchronization primitive when waiting for the GPU to finish work.
|
123
Modules
‣ CU_CTX_BLOCKING_SYNC: Instruct CUDA to block the CPU thread on a synchronization
primitive when waiting for the GPU to finish work.
Deprecated: This flag was deprecated as of CUDA 4.0 and was replaced with
CU_CTX_SCHED_BLOCKING_SYNC.
‣ CU_CTX_SCHED_AUTO: The default value if the flags parameter is zero, uses a heuristic
based on the number of active CUDA contexts in the process C and the number of logical
processors in the system P. If C > P, then CUDA will yield to other OS threads when waiting for
the GPU (CU_CTX_SCHED_YIELD), otherwise CUDA will not yield while waiting for results
and actively spin on the processor (CU_CTX_SCHED_SPIN). Additionally, on Tegra devices,
CU_CTX_SCHED_AUTO uses a heuristic based on the power profile of the platform and may
choose CU_CTX_SCHED_BLOCKING_SYNC for low-powered devices.
‣ CU_CTX_MAP_HOST: Instruct CUDA to support mapped pinned allocations. This flag must be
set in order to allocate pinned host memory that is accessible to the GPU.
‣ CU_CTX_LMEM_RESIZE_TO_MAX: Instruct CUDA to not reduce local memory after resizing
local memory for a kernel. This can prevent thrashing by local memory allocations when launching
many kernels with high local memory usage at the cost of potentially increased memory usage.
Deprecated: This flag is deprecated and the behavior enabled by this flag is now the default and
cannot be disabled. Instead, the per-thread stack size can be controlled with cuCtxSetLimit().
‣ CU_CTX_COREDUMP_ENABLE: If GPU coredumps have not been enabled globally with
cuCoredumpSetAttributeGlobal or environment variables, this flag can be set during context
creation to instruct CUDA to create a coredump if this context raises an exception during
execution. These environment variables are described in the CUDA-GDB user guide under the
"GPU core dump support" section. The initial attributes will be taken from the global attributes at
the time of context creation. The other attributes that control coredump output can be modified by
calling cuCoredumpSetAttribute from the created context after it becomes current.
‣ CU_CTX_USER_COREDUMP_ENABLE: If user-triggered GPU coredumps have not been
enabled globally with cuCoredumpSetAttributeGlobal or environment variables, this flag can be
set during context creation to instruct CUDA to create a coredump if data is written to a certain
pipe that is present in the OS space. These environment variables are described in the CUDA-
GDB user guide under the "GPU core dump support" section. It is important to note that the pipe
name *must* be set with cuCoredumpSetAttributeGlobal before creating the context if this flag is
used. Setting this flag implies that CU_CTX_COREDUMP_ENABLE is set. The initial attributes
will be taken from the global attributes at the time of context creation. The other attributes that
control coredump output can be modified by calling cuCoredumpSetAttribute from the created
context after it becomes current. Setting this flag on any context creation is equivalent to setting the
CU_COREDUMP_ENABLE_USER_TRIGGER attribute to true globally.
‣ CU_CTX_SYNC_MEMOPS: Ensures that synchronous memory operations initiated on
this context will always synchronize. See further documentation in the section titled "API
Synchronization behavior" to learn more about cases when synchronous memory operations can
exhibit asynchronous behavior.
|
124
Modules
Context creation will fail with CUDA_ERROR_UNKNOWN if the compute mode of the device
is CU_COMPUTEMODE_PROHIBITED. The function cuDeviceGetAttribute() can be used with
CU_DEVICE_ATTRIBUTE_COMPUTE_MODE to determine the compute mode of the device. The
nvidia-smi tool can be used to set the compute mode for * devices. Documentation for nvidia-smi can
be obtained by passing a -h option to it.
Note:
Note that this function may also return error codes from previous, asynchronous launches.
See also:
cuCtxDestroy, cuCtxGetApiVersion, cuCtxGetCacheConfig, cuCtxGetDevice, cuCtxGetFlags,
cuCtxGetLimit, cuCtxPopCurrent, cuCtxPushCurrent, cuCtxSetCacheConfig, cuCtxSetLimit,
cuCoredumpSetAttributeGlobal, cuCoredumpSetAttribute, cuCtxSynchronize
CUresult cuCtxCreate_v3 (CUcontext *pctx,
CUexecAffinityParam *paramsArray, int numParams,
unsigned int flags, CUdevice dev)
Create a CUDA context with execution affinity.
Parameters
pctx
- Returned context handle of the new context
paramsArray
- Execution affinity parameters
numParams
- Number of execution affinity parameters
flags
- Context creation flags
dev
- Device to create context on
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_DEVICE,
CUDA_ERROR_INVALID_VALUE, CUDA_ERROR_OUT_OF_MEMORY,
CUDA_ERROR_UNSUPPORTED_EXEC_AFFINITY, CUDA_ERROR_UNKNOWN
|
125
Modules
Description
Creates a new CUDA context with execution affinity and associates it with the calling thread. The
paramsArray and flags parameter are described below. The context is created with a usage count
of 1 and the caller of cuCtxCreate() must call cuCtxDestroy() when done using the context. If a context
is already current to the thread, it is supplanted by the newly created context and may be restored by a
subsequent call to cuCtxPopCurrent().
The type and the amount of execution resource the context can use is limited by paramsArray and
numParams. The paramsArray is an array of CUexecAffinityParam and the numParams
describes the size of the array. If two CUexecAffinityParam in the array have the same type, the
latter execution affinity parameter overrides the former execution affinity parameter. The supported
execution affinity types are:
‣ CU_EXEC_AFFINITY_TYPE_SM_COUNT limits the portion of SMs that the context can use.
The portion of SMs is specified as the number of SMs via CUexecAffinitySmCount. This
limit will be internally rounded up to the next hardware-supported amount. Hence, it is imperative
to query the actual execution affinity of the context via cuCtxGetExecAffinity after context
creation. Currently, this attribute is only supported under Volta+ MPS.
The three LSBs of the flags parameter can be used to control how the OS thread, which owns the
CUDA context at the time of an API call, interacts with the OS scheduler when waiting for results from
the GPU. Only one of the scheduling flags can be set when creating a context.
‣ CU_CTX_SCHED_SPIN: Instruct CUDA to actively spin when waiting for results from the GPU.
This can decrease latency when waiting for the GPU, but may lower the performance of CPU
threads if they are performing work in parallel with the CUDA thread.
‣ CU_CTX_SCHED_YIELD: Instruct CUDA to yield its thread when waiting for results from the
GPU. This can increase latency when waiting for the GPU, but can increase the performance of
CPU threads performing work in parallel with the GPU.
‣ CU_CTX_SCHED_BLOCKING_SYNC: Instruct CUDA to block the CPU thread on a
synchronization primitive when waiting for the GPU to finish work.
‣ CU_CTX_BLOCKING_SYNC: Instruct CUDA to block the CPU thread on a synchronization
primitive when waiting for the GPU to finish work.
Deprecated: This flag was deprecated as of CUDA 4.0 and was replaced with
CU_CTX_SCHED_BLOCKING_SYNC.
‣ CU_CTX_SCHED_AUTO: The default value if the flags parameter is zero, uses a heuristic
based on the number of active CUDA contexts in the process C and the number of logical
processors in the system P. If C > P, then CUDA will yield to other OS threads when waiting for
the GPU (CU_CTX_SCHED_YIELD), otherwise CUDA will not yield while waiting for results
and actively spin on the processor (CU_CTX_SCHED_SPIN). Additionally, on Tegra devices,
CU_CTX_SCHED_AUTO uses a heuristic based on the power profile of the platform and may
choose CU_CTX_SCHED_BLOCKING_SYNC for low-powered devices.
|
126
Modules
‣ CU_CTX_MAP_HOST: Instruct CUDA to support mapped pinned allocations. This flag must be
set in order to allocate pinned host memory that is accessible to the GPU.
‣ CU_CTX_LMEM_RESIZE_TO_MAX: Instruct CUDA to not reduce local memory after resizing
local memory for a kernel. This can prevent thrashing by local memory allocations when launching
many kernels with high local memory usage at the cost of potentially increased memory usage.
Deprecated: This flag is deprecated and the behavior enabled by this flag is now the default and
cannot be disabled. Instead, the per-thread stack size can be controlled with cuCtxSetLimit().
‣ CU_CTX_COREDUMP_ENABLE: If GPU coredumps have not been enabled globally with
cuCoredumpSetAttributeGlobal or environment variables, this flag can be set during context
creation to instruct CUDA to create a coredump if this context raises an exception during
execution. These environment variables are described in the CUDA-GDB user guide under the
"GPU core dump support" section. The initial attributes will be taken from the global attributes at
the time of context creation. The other attributes that control coredump output can be modified by
calling cuCoredumpSetAttribute from the created context after it becomes current.
‣ CU_CTX_USER_COREDUMP_ENABLE: If user-triggered GPU coredumps have not been
enabled globally with cuCoredumpSetAttributeGlobal or environment variables, this flag can be
set during context creation to instruct CUDA to create a coredump if data is written to a certain
pipe that is present in the OS space. These environment variables are described in the CUDA-
GDB user guide under the "GPU core dump support" section. It is important to note that the pipe
name *must* be set with cuCoredumpSetAttributeGlobal before creating the context if this flag is
used. Setting this flag implies that CU_CTX_COREDUMP_ENABLE is set. The initial attributes
will be taken from the global attributes at the time of context creation. The other attributes that
control coredump output can be modified by calling cuCoredumpSetAttribute from the created
context after it becomes current. Setting this flag on any context creation is equivalent to setting the
CU_COREDUMP_ENABLE_USER_TRIGGER attribute to true globally.
Context creation will fail with CUDA_ERROR_UNKNOWN if the compute mode of the device
is CU_COMPUTEMODE_PROHIBITED. The function cuDeviceGetAttribute() can be used with
CU_DEVICE_ATTRIBUTE_COMPUTE_MODE to determine the compute mode of the device. The
nvidia-smi tool can be used to set the compute mode for * devices. Documentation for nvidia-smi can
be obtained by passing a -h option to it.
Note:
Note that this function may also return error codes from previous, asynchronous launches.
See also:
cuCtxDestroy, cuCtxGetApiVersion, cuCtxGetCacheConfig, cuCtxGetDevice, cuCtxGetFlags,
cuCtxGetLimit, cuCtxPopCurrent, cuCtxPushCurrent, cuCtxSetCacheConfig, cuCtxSetLimit,
cuCtxSynchronize, cuCoredumpSetAttributeGlobal, cuCoredumpSetAttribute, CUexecAffinityParam
|
127
Modules
CUresult cuCtxCreate_v4 (CUcontext *pctx,
CUctxCreateParams *ctxCreateParams, unsigned int flags,
CUdevice dev)
Create a CUDA context.
Parameters
pctx
- Returned context handle of the new context
ctxCreateParams
- Context creation parameters
flags
- Context creation flags
dev
- Device to create context on
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_DEVICE,
CUDA_ERROR_INVALID_VALUE, CUDA_ERROR_NOT_SUPPORTED,
CUDA_ERROR_OUT_OF_MEMORY, CUDA_ERROR_UNKNOWN
Description
Creates a new CUDA context and associates it with the calling thread. The flags parameter is
described below. The context is created with a usage count of 1 and the caller of cuCtxCreate()
must call cuCtxDestroy() when done using the context. If a context is already current to the
thread, it is supplanted by the newly created context and may be restored by a subsequent call to
cuCtxPopCurrent().
CUDA context can be created with execution affinity. The type and the amount of execution
resource the context can use is limited by paramsArray and numExecAffinityParams
in execAffinity. The paramsArray is an array of CUexecAffinityParam
and the numExecAffinityParams describes the size of the paramsArray. If two
CUexecAffinityParam in the array have the same type, the latter execution affinity parameter
overrides the former execution affinity parameter. The supported execution affinity types are:
‣ CU_EXEC_AFFINITY_TYPE_SM_COUNT limits the portion of SMs that the context can use.
The portion of SMs is specified as the number of SMs via CUexecAffinitySmCount. This
limit will be internally rounded up to the next hardware-supported amount. Hence, it is imperative
to query the actual execution affinity of the context via cuCtxGetExecAffinity after context
creation. Currently, this attribute is only supported under Volta+ MPS.
|
128
Modules
CUDA context can be created in CIG(CUDA in Graphics) mode by setting cigParams.
Data from graphics client is shared with CUDA via the sharedData in cigParams.
Support for D3D12 graphics client can be determined using cuDeviceGetAttribute()
with CU_DEVICE_ATTRIBUTE_D3D12_CIG_SUPPORTED. sharedData is a
ID3D12CommandQueue handle. Support for Vulkan graphics client can be determined using
cuDeviceGetAttribute() with CU_DEVICE_ATTRIBUTE_VULKAN_CIG_SUPPORTED.
sharedData is a Nvidia specific data blob populated by calling
vkGetExternalComputeQueueDataNV(). Either execAffinityParams or cigParams can be set
to a non-null value. Setting both to a non-null value will result in an undefined behavior.
The three LSBs of the flags parameter can be used to control how the OS thread, which owns the
CUDA context at the time of an API call, interacts with the OS scheduler when waiting for results from
the GPU. Only one of the scheduling flags can be set when creating a context.
‣ CU_CTX_SCHED_SPIN: Instruct CUDA to actively spin when waiting for results from the GPU.
This can decrease latency when waiting for the GPU, but may lower the performance of CPU
threads if they are performing work in parallel with the CUDA thread.
‣ CU_CTX_SCHED_YIELD: Instruct CUDA to yield its thread when waiting for results from the
GPU. This can increase latency when waiting for the GPU, but can increase the performance of
CPU threads performing work in parallel with the GPU.
‣ CU_CTX_SCHED_BLOCKING_SYNC: Instruct CUDA to block the CPU thread on a
synchronization primitive when waiting for the GPU to finish work.
‣ CU_CTX_BLOCKING_SYNC: Instruct CUDA to block the CPU thread on a synchronization
primitive when waiting for the GPU to finish work.
Deprecated: This flag was deprecated as of CUDA 4.0 and was replaced with
CU_CTX_SCHED_BLOCKING_SYNC.
‣ CU_CTX_SCHED_AUTO: The default value if the flags parameter is zero, uses a heuristic
based on the number of active CUDA contexts in the process C and the number of logical
processors in the system P. If C > P, then CUDA will yield to other OS threads when waiting for
the GPU (CU_CTX_SCHED_YIELD), otherwise CUDA will not yield while waiting for results
and actively spin on the processor (CU_CTX_SCHED_SPIN). Additionally, on Tegra devices,
CU_CTX_SCHED_AUTO uses a heuristic based on the power profile of the platform and may
choose CU_CTX_SCHED_BLOCKING_SYNC for low-powered devices.
‣ CU_CTX_MAP_HOST: Instruct CUDA to support mapped pinned allocations. This flag must be
set in order to allocate pinned host memory that is accessible to the GPU.
‣ CU_CTX_LMEM_RESIZE_TO_MAX: Instruct CUDA to not reduce local memory after resizing
local memory for a kernel. This can prevent thrashing by local memory allocations when launching
many kernels with high local memory usage at the cost of potentially increased memory usage.
Deprecated: This flag is deprecated and the behavior enabled by this flag is now the default and
cannot be disabled. Instead, the per-thread stack size can be controlled with cuCtxSetLimit().
|
129
Modules
‣ CU_CTX_COREDUMP_ENABLE: If GPU coredumps have not been enabled globally with
cuCoredumpSetAttributeGlobal or environment variables, this flag can be set during context
creation to instruct CUDA to create a coredump if this context raises an exception during
execution. These environment variables are described in the CUDA-GDB user guide under the
"GPU core dump support" section. The initial attributes will be taken from the global attributes at
the time of context creation. The other attributes that control coredump output can be modified by
calling cuCoredumpSetAttribute from the created context after it becomes current. This flag is not
supported when CUDA context is created in CIG(CUDA in Graphics) mode.
‣ CU_CTX_USER_COREDUMP_ENABLE: If user-triggered GPU coredumps have not been
enabled globally with cuCoredumpSetAttributeGlobal or environment variables, this flag can be
set during context creation to instruct CUDA to create a coredump if data is written to a certain
pipe that is present in the OS space. These environment variables are described in the CUDA-
GDB user guide under the "GPU core dump support" section. It is important to note that the pipe
name *must* be set with cuCoredumpSetAttributeGlobal before creating the context if this flag is
used. Setting this flag implies that CU_CTX_COREDUMP_ENABLE is set. The initial attributes
will be taken from the global attributes at the time of context creation. The other attributes that
control coredump output can be modified by calling cuCoredumpSetAttribute from the created
context after it becomes current. Setting this flag on any context creation is equivalent to setting
the CU_COREDUMP_ENABLE_USER_TRIGGER attribute to true globally. This flag is not
supported when CUDA context is created in CIG(CUDA in Graphics) mode.
‣ CU_CTX_SYNC_MEMOPS: Ensures that synchronous memory operations initiated on
this context will always synchronize. See further documentation in the section titled "API
Synchronization behavior" to learn more about cases when synchronous memory operations can
exhibit asynchronous behavior.
Context creation will fail with CUDA_ERROR_UNKNOWN if the compute mode of the device
is CU_COMPUTEMODE_PROHIBITED. The function cuDeviceGetAttribute() can be used with
CU_DEVICE_ATTRIBUTE_COMPUTE_MODE to determine the compute mode of the device. The
nvidia-smi tool can be used to set the compute mode for * devices. Documentation for nvidia-smi can
be obtained by passing a -h option to it.
Context creation will fail with :: CUDA_ERROR_INVALID_VALUE if invalid parameter was passed
by client to create the CUDA context.
Context creation in CIG mode will fail with CUDA_ERROR_NOT_SUPPORTED if CIG is not
supported by the device or the driver.
Note:
Note that this function may also return error codes from previous, asynchronous launches.
See also:
|
130
Modules
cuCtxDestroy, cuCtxGetApiVersion, cuCtxGetCacheConfig, cuCtxGetDevice, cuCtxGetFlags,
cuCtxGetLimit, cuCtxPopCurrent, cuCtxPushCurrent, cuCtxSetCacheConfig, cuCtxSetLimit,
cuCoredumpSetAttributeGlobal, cuCoredumpSetAttribute, cuCtxSynchronize
CUresult cuCtxDestroy (CUcontext ctx)
Destroy a CUDA context.
Parameters
ctx
- Context to destroy
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_VALUE
Description
Destroys the CUDA context specified by ctx. The context ctx will be destroyed regardless of how
many threads it is current to. It is the responsibility of the calling function to ensure that no API call
issues using ctx while cuCtxDestroy() is executing.
Destroys and cleans up all resources associated with the context. It is the caller's responsibility to
ensure that the context or its resources are not accessed or passed in subsequent API calls and doing
so will result in undefined behavior. These resources include CUDA types CUmodule, CUfunction,
CUstream, CUevent, CUarray, CUmipmappedArray, CUtexObject, CUsurfObject, CUtexref,
CUsurfref, CUgraphicsResource, CUlinkState, CUexternalMemory and CUexternalSemaphore.
These resources also include memory allocations by cuMemAlloc(), cuMemAllocHost(),
cuMemAllocManaged() and cuMemAllocPitch().
If ctx is current to the calling thread then ctx will also be popped from the current thread's context
stack (as though cuCtxPopCurrent() were called). If ctx is current to other threads, then ctx will
remain current to those threads, and attempting to access ctx from those threads will result in the error
CUDA_ERROR_CONTEXT_IS_DESTROYED.
Note:
cuCtxDestroy() will not destroy memory allocations by cuMemCreate(), cuMemAllocAsync() and
cuMemAllocFromPoolAsync(). These memory allocations are not associated with any CUDA context
and need to be destroyed explicitly.
Note:
Note that this function may also return error codes from previous, asynchronous launches.
|
131
Modules
See also:
cuCtxCreate, cuCtxGetApiVersion, cuCtxGetCacheConfig, cuCtxGetDevice, cuCtxGetFlags,
cuCtxGetLimit, cuCtxPopCurrent, cuCtxPushCurrent, cuCtxSetCacheConfig, cuCtxSetLimit,
cuCtxSynchronize
CUresult cuCtxGetApiVersion (CUcontext ctx, unsigned
int *version)
Gets the context's API version.
Parameters
ctx
- Context to check
version
- Pointer to version
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_VALUE,
CUDA_ERROR_UNKNOWN
Description
Returns a version number in version corresponding to the capabilities of the context (e.g. 3010 or
3020), which library developers can use to direct callers to a specific API version. If ctx is NULL,
returns the API version used to create the currently bound context.
Note that new API versions are only introduced when context capabilities are changed that break
binary compatibility, so the API version and driver version may be different. For example, it is valid
for the API version to be 3020 while the driver version is 4020.
Note:
Note that this function may also return error codes from previous, asynchronous launches.
See also:
cuCtxCreate, cuCtxDestroy, cuCtxGetDevice, cuCtxGetFlags, cuCtxGetLimit, cuCtxPopCurrent,
cuCtxPushCurrent, cuCtxSetCacheConfig, cuCtxSetLimit, cuCtxSynchronize
|
132
Modules
CUresult cuCtxGetCacheConfig (CUfunc_cache *pconfig)
Returns the preferred cache configuration for the current context.
Parameters
pconfig
- Returned cache configuration
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_VALUE
Description
On devices where the L1 cache and shared memory use the same hardware resources, this function
returns through pconfig the preferred cache configuration for the current context. This is only
a preference. The driver will use the requested configuration if possible, but it is free to choose a
different configuration if required to execute functions.
This will return a pconfig of CU_FUNC_CACHE_PREFER_NONE on devices where the size of
the L1 cache and shared memory are fixed.
The supported cache configurations are:
‣ CU_FUNC_CACHE_PREFER_NONE: no preference for shared memory or L1 (default)
‣ CU_FUNC_CACHE_PREFER_SHARED: prefer larger shared memory and smaller L1 cache
‣ CU_FUNC_CACHE_PREFER_L1: prefer larger L1 cache and smaller shared memory
‣ CU_FUNC_CACHE_PREFER_EQUAL: prefer equal sized L1 cache and shared memory
Note:
Note that this function may also return error codes from previous, asynchronous launches.
See also:
cuCtxCreate, cuCtxDestroy, cuCtxGetApiVersion, cuCtxGetDevice, cuCtxGetFlags, cuCtxGetLimit,
cuCtxPopCurrent, cuCtxPushCurrent, cuCtxSetCacheConfig, cuCtxSetLimit, cuCtxSynchronize,
cuFuncSetCacheConfig, cudaDeviceGetCacheConfig
|
133
Modules
CUresult cuCtxGetCurrent (CUcontext *pctx)
Returns the CUDA context bound to the calling CPU thread.
Parameters
pctx
- Returned context handle
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
Description
Returns in *pctx the CUDA context bound to the calling CPU thread. If no context is bound to the
calling CPU thread then *pctx is set to NULL and CUDA_SUCCESS is returned.
Note:
Note that this function may also return error codes from previous, asynchronous launches.
See also:
cuCtxSetCurrent, cuCtxCreate, cuCtxDestroy, cudaGetDevice
CUresult cuCtxGetDevice (CUdevice *device)
Returns the device handle for the current context.
Parameters
device
- Returned device handle for the current context
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_VALUE,
Description
Returns in *device the handle of the current context's device.
Note:
Note that this function may also return error codes from previous, asynchronous launches.
|
134
Modules
See also:
cuCtxCreate, cuCtxDestroy, cuCtxGetApiVersion, cuCtxGetCacheConfig, cuCtxGetFlags,
cuCtxGetLimit, cuCtxPopCurrent, cuCtxPushCurrent, cuCtxSetCacheConfig, cuCtxSetLimit,
cuCtxSynchronize, cudaGetDevice
CUresult cuCtxGetExecAffinity (CUexecAffinityParam
*pExecAffinity, CUexecAffinityType type)
Returns the execution affinity setting for the current context.
Parameters
pExecAffinity
- Returned execution affinity
type
- Execution affinity type to query
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_VALUE,
CUDA_ERROR_UNSUPPORTED_EXEC_AFFINITY
Description
Returns in *pExecAffinity the current value of type. The supported CUexecAffinityType values
are:
‣ CU_EXEC_AFFINITY_TYPE_SM_COUNT: number of SMs the context is limited to use.
Note:
Note that this function may also return error codes from previous, asynchronous launches.
See also:
CUexecAffinityParam
CUresult cuCtxGetFlags (unsigned int *flags)
Returns the flags for the current context.
Parameters
flags
- Pointer to store flags of current context
|
135
Modules
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_VALUE,
Description
Returns in *flags the flags of the current context. See cuCtxCreate for flag values.
Note:
Note that this function may also return error codes from previous, asynchronous launches.
See also:
cuCtxCreate, cuCtxGetApiVersion, cuCtxGetCacheConfig, cuCtxGetCurrent, cuCtxGetDevice,
cuCtxGetLimit, cuCtxGetSharedMemConfig, cuCtxGetStreamPriorityRange, cuCtxSetFlags,
cudaGetDeviceFlags
CUresult cuCtxGetId (CUcontext ctx, unsigned long long
*ctxId)
Returns the unique Id associated with the context supplied.
Parameters
ctx
- Context for which to obtain the Id
ctxId
- Pointer to store the Id of the context
Returns
CUDA_SUCCESS, CUDA_ERROR_CONTEXT_IS_DESTROYED,
CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_VALUE
Description
Returns in ctxId the unique Id which is associated with a given context. The Id is unique for the life
of the program for this instance of CUDA. If context is supplied as NULL and there is one current, the
Id of the current context is returned.
Note:
|
136
Modules
Note that this function may also return error codes from previous, asynchronous launches.
See also:
cuCtxCreate, cuCtxDestroy, cuCtxGetApiVersion, cuCtxGetCacheConfig, cuCtxGetDevice,
cuCtxGetFlags, cuCtxGetLimit, cuCtxPushCurrent
CUresult cuCtxGetLimit (size_t *pvalue, CUlimit limit)
Returns resource limits.
Parameters
pvalue
- Returned size of limit
limit
- Limit to query
Returns
CUDA_SUCCESS, CUDA_ERROR_INVALID_VALUE, CUDA_ERROR_UNSUPPORTED_LIMIT
Description
Returns in *pvalue the current size of limit. The supported CUlimit values are:
‣ CU_LIMIT_STACK_SIZE: stack size in bytes of each GPU thread.
‣ CU_LIMIT_PRINTF_FIFO_SIZE: size in bytes of the FIFO used by the printf() device system
call.
‣ CU_LIMIT_MALLOC_HEAP_SIZE: size in bytes of the heap used by the malloc() and free()
device system calls.
‣ CU_LIMIT_DEV_RUNTIME_SYNC_DEPTH: maximum grid depth at which a thread can issue
the device runtime call cudaDeviceSynchronize() to wait on child grid launches to complete.
‣ CU_LIMIT_DEV_RUNTIME_PENDING_LAUNCH_COUNT: maximum number of outstanding
device runtime launches that can be made from this context.
‣ CU_LIMIT_MAX_L2_FETCH_GRANULARITY: L2 cache fetch granularity.
‣ CU_LIMIT_PERSISTING_L2_CACHE_SIZE: Persisting L2 cache size in bytes
Note:
Note that this function may also return error codes from previous, asynchronous launches.
See also:
|
137
Modules
cuCtxCreate, cuCtxDestroy, cuCtxGetApiVersion, cuCtxGetCacheConfig, cuCtxGetDevice,
cuCtxGetFlags, cuCtxPopCurrent, cuCtxPushCurrent, cuCtxSetCacheConfig, cuCtxSetLimit,
cuCtxSynchronize, cudaDeviceGetLimit
CUresult cuCtxGetStreamPriorityRange (int *leastPriority,
int *greatestPriority)
Returns numerical values that correspond to the least and greatest stream priorities.
Parameters
leastPriority
- Pointer to an int in which the numerical value for least stream priority is returned
greatestPriority
- Pointer to an int in which the numerical value for greatest stream priority is returned
Returns
CUDA_SUCCESS, CUDA_ERROR_INVALID_VALUE,
Description
Returns in *leastPriority and *greatestPriority the numerical values that correspond
to the least and greatest stream priorities respectively. Stream priorities follow a convention where
lower numbers imply greater priorities. The range of meaningful stream priorities is given by
[*greatestPriority, *leastPriority]. If the user attempts to create a stream with a priority
value that is outside the meaningful range as specified by this API, the priority is automatically
clamped down or up to either *leastPriority or *greatestPriority respectively. See
cuStreamCreateWithPriority for details on creating a priority stream. A NULL may be passed in for
*leastPriority or *greatestPriority if the value is not desired.
This function will return '0' in both *leastPriority and *greatestPriority if the current
context's device does not support stream priorities (see cuDeviceGetAttribute).
Note:
Note that this function may also return error codes from previous, asynchronous launches.
See also:
cuStreamCreateWithPriority, cuStreamGetPriority, cuCtxGetDevice, cuCtxGetFlags, cuCtxSetLimit,
cuCtxSynchronize, cudaDeviceGetStreamPriorityRange
|
138
Modules
CUresult cuCtxPopCurrent (CUcontext *pctx)
Pops the current CUDA context from the current CPU thread.
Parameters
pctx
- Returned popped context handle
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_CONTEXT
Description
Pops the current CUDA context from the CPU thread and passes back the old context handle
in *pctx. That context may then be made current to a different CPU thread by calling
cuCtxPushCurrent().
If a context was current to the CPU thread before cuCtxCreate() or cuCtxPushCurrent() was called, this
function makes that context current to the CPU thread again.
Note:
Note that this function may also return error codes from previous, asynchronous launches.
See also:
cuCtxCreate, cuCtxDestroy, cuCtxGetApiVersion, cuCtxGetCacheConfig, cuCtxGetDevice,
cuCtxGetFlags, cuCtxGetLimit, cuCtxPushCurrent, cuCtxSetCacheConfig, cuCtxSetLimit,
cuCtxSynchronize
CUresult cuCtxPushCurrent (CUcontext ctx)
Pushes a context on the current CPU thread.
Parameters
ctx
- Context to push
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_VALUE
|
139
Modules
Description
Pushes the given context ctx onto the CPU thread's stack of current contexts. The specified context
becomes the CPU thread's current context, so all CUDA functions that operate on the current context
are affected.
The previous current context may be made current again by calling cuCtxDestroy() or
cuCtxPopCurrent().
Note:
Note that this function may also return error codes from previous, asynchronous launches.
See also:
cuCtxCreate, cuCtxDestroy, cuCtxGetApiVersion, cuCtxGetCacheConfig, cuCtxGetDevice,
cuCtxGetFlags, cuCtxGetLimit, cuCtxPopCurrent, cuCtxSetCacheConfig, cuCtxSetLimit,
cuCtxSynchronize
CUresult cuCtxRecordEvent (CUcontext hCtx, CUevent
hEvent)
Records an event.
Parameters
hCtx
- 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
Description
Captures in hEvent all the activities of the context hCtx at the time of this call. hEvent and hCtx
must be from the same CUDA context, otherwise CUDA_ERROR_INVALID_HANDLE will be
returned. Calls such as cuEventQuery() or cuCtxWaitEvent() will then examine or wait for completion
of the work that was captured. Uses of hCtx after this call do not modify hEvent. If the context
passed to hCtx is the primary context, hEvent will capture all the activities of the primary context
|
140
Modules
and its green contexts. If the context passed to hCtx is a context converted from green context via
cuCtxFromGreenCtx(), hEvent will capture only the activities of the green context.
Note:
The API will return CUDA_ERROR_STREAM_CAPTURE_UNSUPPORTED if the specified context
hCtx has a stream in the capture mode. In such a case, the call will invalidate all the conflicting
captures.
See also:
cuCtxWaitEvent, cuGreenCtxRecordEvent, cuGreenCtxWaitEvent, cuEventRecord
CUresult cuCtxResetPersistingL2Cache (void)
Resets all persisting lines in cache to normal status.
Returns
CUDA_SUCCESS, CUDA_ERROR_NOT_SUPPORTED
Description
cuCtxResetPersistingL2Cache Resets all persisting lines in cache to normal status. Takes effect on
function return.
Note:
Note that this function may also return error codes from previous, asynchronous launches.
See also:
CUaccessPolicyWindow
CUresult cuCtxSetCacheConfig (CUfunc_cache config)
Sets the preferred cache configuration for the current context.
Parameters
config
- Requested cache configuration
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_VALUE
|
141
Modules
Description
On devices where the L1 cache and shared memory use the same hardware resources, this sets through
config the preferred cache configuration for the current context. This is only a preference. The
driver will use the requested configuration if possible, but it is free to choose a different configuration
if required to execute the function. Any function preference set via cuFuncSetCacheConfig() or
cuKernelSetCacheConfig() will be preferred over this context-wide setting. Setting the context-wide
cache configuration to CU_FUNC_CACHE_PREFER_NONE will cause subsequent kernel launches
to prefer to not change the cache configuration unless required to launch the kernel.
This setting does nothing on devices where the size of the L1 cache and shared memory are fixed.
Launching a kernel with a different preference than the most recent preference setting may insert a
device-side synchronization point.
The supported cache configurations are:
‣ CU_FUNC_CACHE_PREFER_NONE: no preference for shared memory or L1 (default)
‣ CU_FUNC_CACHE_PREFER_SHARED: prefer larger shared memory and smaller L1 cache
‣ CU_FUNC_CACHE_PREFER_L1: prefer larger L1 cache and smaller shared memory
‣ CU_FUNC_CACHE_PREFER_EQUAL: prefer equal sized L1 cache and shared memory
Note:
Note that this function may also return error codes from previous, asynchronous launches.
See also:
cuCtxCreate, cuCtxDestroy, cuCtxGetApiVersion, cuCtxGetCacheConfig, cuCtxGetDevice,
cuCtxGetFlags, cuCtxGetLimit, cuCtxPopCurrent, cuCtxPushCurrent, cuCtxSetLimit,
cuCtxSynchronize, cuFuncSetCacheConfig, cudaDeviceSetCacheConfig, cuKernelSetCacheConfig
CUresult cuCtxSetCurrent (CUcontext ctx)
Binds the specified CUDA context to the calling CPU thread.
Parameters
ctx
- Context to bind to the calling CPU thread
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_CONTEXT
|
142
Modules
Description
Binds the specified CUDA context to the calling CPU thread. If ctx is NULL then the CUDA context
previously bound to the calling CPU thread is unbound and CUDA_SUCCESS is returned.
If there exists a CUDA context stack on the calling CPU thread, this will replace the top of that stack
with ctx. If ctx is NULL then this will be equivalent to popping the top of the calling CPU thread's
CUDA context stack (or a no-op if the calling CPU thread's CUDA context stack is empty).
Note:
Note that this function may also return error codes from previous, asynchronous launches.
See also:
cuCtxGetCurrent, cuCtxCreate, cuCtxDestroy, cudaSetDevice
CUresult cuCtxSetFlags (unsigned int flags)
Sets the flags for the current context.
Parameters
flags
- Flags to set on the current context
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_VALUE,
Description
Sets the flags for the current context overwriting previously set ones. See cuDevicePrimaryCtxSetFlags
for flag values.
Note:
Note that this function may also return error codes from previous, asynchronous launches.
See also:
cuCtxCreate, cuCtxGetApiVersion, cuCtxGetCacheConfig, cuCtxGetCurrent, cuCtxGetDevice,
cuCtxGetLimit, cuCtxGetSharedMemConfig, cuCtxGetStreamPriorityRange, cuCtxGetFlags,
cudaGetDeviceFlags, cuDevicePrimaryCtxSetFlags,
|
143
Modules
CUresult cuCtxSetLimit (CUlimit limit, size_t value)
Set resource limits.
Parameters
limit
- Limit to set
value
- Size of limit
Returns
CUDA_SUCCESS, CUDA_ERROR_INVALID_VALUE,
CUDA_ERROR_UNSUPPORTED_LIMIT, CUDA_ERROR_OUT_OF_MEMORY,
CUDA_ERROR_INVALID_CONTEXT
Description
Setting limit to value is a request by the application to update the current limit maintained by
the context. The driver is free to modify the requested value to meet h/w requirements (this could be
clamping to minimum or maximum values, rounding up to nearest element size, etc). The application
can use cuCtxGetLimit() to find out exactly what the limit has been set to.
Setting each CUlimit has its own specific restrictions, so each is discussed here.
‣ CU_LIMIT_STACK_SIZE controls the stack size in bytes of each GPU thread. The driver
automatically increases the per-thread stack size for each kernel launch as needed. This size isn't
reset back to the original value after each launch. Setting this value will take effect immediately,
and if necessary, the device will block until all preceding requested tasks are complete.
‣ CU_LIMIT_PRINTF_FIFO_SIZE controls the size in bytes of the FIFO used by the printf() device
system call. Setting CU_LIMIT_PRINTF_FIFO_SIZE must be performed before launching any
kernel that uses the printf() device system call, otherwise CUDA_ERROR_INVALID_VALUE
will be returned.
‣ CU_LIMIT_MALLOC_HEAP_SIZE controls the size in bytes of the heap used by the malloc()
and free() device system calls. Setting CU_LIMIT_MALLOC_HEAP_SIZE must be performed
before launching any kernel that uses the malloc() or free() device system calls, otherwise
CUDA_ERROR_INVALID_VALUE will be returned.
‣ CU_LIMIT_DEV_RUNTIME_SYNC_DEPTH controls the maximum nesting depth of a grid
at which a thread can safely call cudaDeviceSynchronize(). Setting this limit must be performed
before any launch of a kernel that uses the device runtime and calls cudaDeviceSynchronize()
above the default sync depth, two levels of grids. Calls to cudaDeviceSynchronize() will fail
with error code cudaErrorSyncDepthExceeded if the limitation is violated. This limit can be
set smaller than the default or up the maximum launch depth of 24. When setting this limit,
keep in mind that additional levels of sync depth require the driver to reserve large amounts of
|
144
Modules
device memory which can no longer be used for user allocations. If these reservations of device
memory fail, cuCtxSetLimit() will return CUDA_ERROR_OUT_OF_MEMORY, and the limit
can be reset to a lower value. This limit is only applicable to devices of compute capability < 9.0.
Attempting to set this limit on devices of other compute capability versions will result in the error
CUDA_ERROR_UNSUPPORTED_LIMIT being returned.
‣ CU_LIMIT_DEV_RUNTIME_PENDING_LAUNCH_COUNT controls the maximum
number of outstanding device runtime launches that can be made from the current
context. A grid is outstanding from the point of launch up until the grid is known to have
been completed. Device runtime launches which violate this limitation fail and return
cudaErrorLaunchPendingCountExceeded when cudaGetLastError() is called after launch. If
more pending launches than the default (2048 launches) are needed for a module using the
device runtime, this limit can be increased. Keep in mind that being able to sustain additional
pending launches will require the driver to reserve larger amounts of device memory upfront
which can no longer be used for allocations. If these reservations fail, cuCtxSetLimit() will
return CUDA_ERROR_OUT_OF_MEMORY, and the limit can be reset to a lower value.
This limit is only applicable to devices of compute capability 3.5 and higher. Attempting
to set this limit on devices of compute capability less than 3.5 will result in the error
CUDA_ERROR_UNSUPPORTED_LIMIT being returned.
‣ CU_LIMIT_MAX_L2_FETCH_GRANULARITY controls the L2 cache fetch granularity. Values
can range from 0B to 128B. This is purely a performance hint and it can be ignored or clamped
depending on the platform.
‣ CU_LIMIT_PERSISTING_L2_CACHE_SIZE controls size in bytes available for persisting
L2 cache. This is purely a performance hint and it can be ignored or clamped depending on the
platform.
Note:
Note that this function may also return error codes from previous, asynchronous launches.
See also:
cuCtxCreate, cuCtxDestroy, cuCtxGetApiVersion, cuCtxGetCacheConfig, cuCtxGetDevice,
cuCtxGetFlags, cuCtxGetLimit, cuCtxPopCurrent, cuCtxPushCurrent, cuCtxSetCacheConfig,
cuCtxSynchronize, cudaDeviceSetLimit
CUresult cuCtxSynchronize (void)
Block for the current context's tasks to complete.
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_CONTEXT
|
145
Modules
Description
Blocks until the current context has completed all preceding requested tasks. If the current
context is the primary context, green contexts that have been created will also be synchronized.
cuCtxSynchronize() returns an error if one of the preceding tasks failed. If the context was created with
the CU_CTX_SCHED_BLOCKING_SYNC flag, the CPU thread will block until the GPU context has
finished its work.
Note:
Note that this function may also return error codes from previous, asynchronous launches.
See also:
cuCtxCreate, cuCtxDestroy, cuCtxGetApiVersion, cuCtxGetCacheConfig, cuCtxGetDevice,
cuCtxGetFlags, cuCtxGetLimit, cuCtxPopCurrent, cuCtxPushCurrent, cuCtxSetCacheConfig,
cuCtxSetLimit, cudaDeviceSynchronize
CUresult cuCtxWaitEvent (CUcontext hCtx, CUevent
hEvent)
Make a context wait on an event.
Parameters
hCtx
- 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
Description
Makes all future work submitted to 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
cuCtxRecordEvent() for details on what is captured by an event. If the context passed to hCtx is the
primary context, the primary context and its green contexts will wait for hEvent. If the context passed
|
146
Modules
to hCtx is a context converted from green context via cuCtxFromGreenCtx(), the green context will
wait for hEvent.
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
context hCtx has a stream in the capture mode.
See also:
cuCtxRecordEvent, cuGreenCtxRecordEvent, cuGreenCtxWaitEvent, cuStreamWaitEvent
6.9.
Context Management [DEPRECATED]
This section describes the deprecated context management functions of the low-level CUDA driver
application programming interface.
CUresult cuCtxAttach (CUcontext *pctx, unsigned int
flags)
Increment a context's usage-count.
Parameters
pctx
- Returned context handle of the current context
flags
- Context attach flags (must be 0)
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_VALUE
Description
Deprecated
Note that this function is deprecated and should not be used.
Increments the usage count of the context and passes back a context handle in *pctx that must be
passed to cuCtxDetach() when the application is done with the context. cuCtxAttach() fails if there is
no context current to the thread.
|
147
Modules
Currently, the flags parameter must be 0.
Note:
Note that this function may also return error codes from previous, asynchronous launches.
See also:
cuCtxCreate, cuCtxDestroy, cuCtxDetach, cuCtxGetApiVersion, cuCtxGetCacheConfig,
cuCtxGetDevice, cuCtxGetFlags, cuCtxGetLimit, cuCtxPopCurrent, cuCtxPushCurrent,
cuCtxSetCacheConfig, cuCtxSetLimit, cuCtxSynchronize
CUresult cuCtxDetach (CUcontext ctx)
Decrement a context's usage-count.
Parameters
ctx
- Context to destroy
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_CONTEXT
Description
Deprecated
Note that this function is deprecated and should not be used.
Decrements the usage count of the context ctx, and destroys the context if the usage count goes to 0.
The context must be a handle that was passed back by cuCtxCreate() or cuCtxAttach(), and must be
current to the calling thread.
Note:
Note that this function may also return error codes from previous, asynchronous launches.
See also:
cuCtxCreate, cuCtxDestroy, cuCtxGetApiVersion, cuCtxGetCacheConfig, cuCtxGetDevice,
cuCtxGetFlags, cuCtxGetLimit, cuCtxPopCurrent, cuCtxPushCurrent, cuCtxSetCacheConfig,
cuCtxSetLimit, cuCtxSynchronize
|
148
Modules
CUresult cuCtxGetSharedMemConfig (CUsharedconfig
*pConfig)
Returns the current shared memory configuration for the current context.
Parameters
pConfig
- returned shared memory configuration
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_VALUE
Description
Deprecated
This function will return in pConfig the current size of shared memory banks in the current context.
On devices with configurable shared memory banks, cuCtxSetSharedMemConfig can be used to
change this setting, so that all subsequent kernel launches will by default use the new bank size. When
cuCtxGetSharedMemConfig is called on devices without configurable shared memory, it will return
the fixed bank size of the hardware.
The returned bank configurations can be either:
‣ CU_SHARED_MEM_CONFIG_FOUR_BYTE_BANK_SIZE: shared memory bank width is four
bytes.
‣ CU_SHARED_MEM_CONFIG_EIGHT_BYTE_BANK_SIZE: shared memory bank width will
eight bytes.
Note:
Note that this function may also return error codes from previous, asynchronous launches.
See also:
cuCtxCreate, cuCtxDestroy, cuCtxGetApiVersion, cuCtxGetCacheConfig,
cuCtxGetDevice, cuCtxGetFlags, cuCtxGetLimit, cuCtxPopCurrent, cuCtxPushCurrent,
cuCtxSetLimit, cuCtxSynchronize, cuCtxGetSharedMemConfig, cuFuncSetCacheConfig,
cudaDeviceGetSharedMemConfig
|
149
Modules
CUresult cuCtxSetSharedMemConfig (CUsharedconfig
config)
Sets the shared memory configuration for the current context.
Parameters
config
- requested shared memory configuration
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_VALUE
Description
Deprecated
On devices with configurable shared memory banks, this function will set the context's shared memory
bank size which is used for subsequent kernel launches.
Changed the shared memory configuration between launches may insert a device side synchronization
point between those launches.
Changing the shared memory bank size will not increase shared memory usage or affect occupancy of
kernels, but may have major effects on performance. Larger bank sizes will allow for greater potential
bandwidth to shared memory, but will change what kinds of accesses to shared memory will result in
bank conflicts.
This function will do nothing on devices with fixed shared memory bank size.
The supported bank configurations are:
‣ CU_SHARED_MEM_CONFIG_DEFAULT_BANK_SIZE: set bank width to the default initial
setting (currently, four bytes).
‣ CU_SHARED_MEM_CONFIG_FOUR_BYTE_BANK_SIZE: set shared memory bank width to
be natively four bytes.
‣ CU_SHARED_MEM_CONFIG_EIGHT_BYTE_BANK_SIZE: set shared memory bank width to
be natively eight bytes.
Note:
Note that this function may also return error codes from previous, asynchronous launches.
See also:
|
150
Modules
cuCtxCreate, cuCtxDestroy, cuCtxGetApiVersion, cuCtxGetCacheConfig,
cuCtxGetDevice, cuCtxGetFlags, cuCtxGetLimit, cuCtxPopCurrent, cuCtxPushCurrent,
cuCtxSetLimit, cuCtxSynchronize, cuCtxGetSharedMemConfig, cuFuncSetCacheConfig,
cudaDeviceSetSharedMemConfig
6.10. Module Management
This section describes the module management functions of the low-level CUDA driver application
programming interface.
enum CUmoduleLoadingMode
CUDA Lazy Loading status
Values
CU_MODULE_EAGER_LOADING = 0x1
Lazy Kernel Loading is not enabled
CU_MODULE_LAZY_LOADING = 0x2
Lazy Kernel Loading is enabled
CUresult cuLinkAddData (CUlinkState state,
CUjitInputType type, void *data, size_t size, const char
*name, unsigned int numOptions, CUjit_option *options,
void **optionValues)
Add an input to a pending linker invocation.
Parameters
state
A pending linker action.
type
The type of the input data.
data
The input data. PTX must be NULL-terminated.
size
The length of the input data.
name
An optional name for this input in log messages.
numOptions
Size of options.
|
151
Modules
options
Options to be applied only for this input (overrides options from cuLinkCreate).
optionValues
Array of option values, each cast to void *.
Returns
CUDA_SUCCESS, CUDA_ERROR_INVALID_HANDLE, CUDA_ERROR_INVALID_VALUE,
CUDA_ERROR_INVALID_IMAGE, CUDA_ERROR_INVALID_PTX,
CUDA_ERROR_UNSUPPORTED_PTX_VERSION, CUDA_ERROR_OUT_OF_MEMORY,
CUDA_ERROR_NO_BINARY_FOR_GPU
Description
Ownership of data is retained by the caller. No reference is retained to any inputs after this call
returns.
This method accepts only compiler options, which are used if the data must be compiled from
PTX, and does not accept any of CU_JIT_WALL_TIME, CU_JIT_INFO_LOG_BUFFER,
CU_JIT_ERROR_LOG_BUFFER, CU_JIT_TARGET_FROM_CUCONTEXT, or CU_JIT_TARGET.
Note:
For LTO-IR input, only LTO-IR compiled with toolkits prior to CUDA 12.0 will be accepted
See also:
cuLinkCreate, cuLinkAddFile, cuLinkComplete, cuLinkDestroy
CUresult cuLinkAddFile (CUlinkState state,
CUjitInputType type, const char *path, unsigned int
numOptions, CUjit_option *options, void **optionValues)
Add a file input to a pending linker invocation.
Parameters
state
A pending linker action
type
The type of the input data
path
Path to the input file
numOptions
Size of options
|
152
Modules
options
Options to be applied only for this input (overrides options from cuLinkCreate)
optionValues
Array of option values, each cast to void *
Returns
CUDA_SUCCESS, CUDA_ERROR_FILE_NOT_FOUND CUDA_ERROR_INVALID_HANDLE,
CUDA_ERROR_INVALID_VALUE, CUDA_ERROR_INVALID_IMAGE,
CUDA_ERROR_INVALID_PTX, CUDA_ERROR_UNSUPPORTED_PTX_VERSION,
CUDA_ERROR_OUT_OF_MEMORY, CUDA_ERROR_NO_BINARY_FOR_GPU
Description
No reference is retained to any inputs after this call returns.
This method accepts only compiler options, which are used if the input must be compiled from
PTX, and does not accept any of CU_JIT_WALL_TIME, CU_JIT_INFO_LOG_BUFFER,
CU_JIT_ERROR_LOG_BUFFER, CU_JIT_TARGET_FROM_CUCONTEXT, or CU_JIT_TARGET.
This method is equivalent to invoking cuLinkAddData on the contents of the file.
Note:
For LTO-IR input, only LTO-IR compiled with toolkits prior to CUDA 12.0 will be accepted
See also:
cuLinkCreate, cuLinkAddData, cuLinkComplete, cuLinkDestroy
CUresult cuLinkComplete (CUlinkState state, void
**cubinOut, size_t *sizeOut)
Complete a pending linker invocation.
Parameters
state
A pending linker invocation
cubinOut
On success, this will point to the output image
sizeOut
Optional parameter to receive the size of the generated image
Returns
CUDA_SUCCESS, CUDA_ERROR_INVALID_HANDLE, CUDA_ERROR_OUT_OF_MEMORY
|
153
Modules
Description
Completes the pending linker action and returns the cubin image for the linked device code, which can
be used with cuModuleLoadData. The cubin is owned by state, so it should be loaded before state
is destroyed via cuLinkDestroy. This call does not destroy state.
See also:
cuLinkCreate, cuLinkAddData, cuLinkAddFile, cuLinkDestroy, cuModuleLoadData
CUresult cuLinkCreate (unsigned int numOptions,
CUjit_option *options, void **optionValues, CUlinkState
*stateOut)
Creates a pending JIT linker invocation.
Parameters
numOptions
Size of options arrays
options
Array of linker and compiler options
optionValues
Array of option values, each cast to void *
stateOut
On success, this will contain a CUlinkState to specify and complete this action
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_VALUE,
CUDA_ERROR_OUT_OF_MEMORY, CUDA_ERROR_JIT_COMPILER_NOT_FOUND
Description
If the call is successful, the caller owns the returned CUlinkState, which should eventually be destroyed
with cuLinkDestroy. The device code machine size (32 or 64 bit) will match the calling application.
Both linker and compiler options may be specified. Compiler options will be applied to inputs
to this linker action which must be compiled from PTX. The options CU_JIT_WALL_TIME,
CU_JIT_INFO_LOG_BUFFER_SIZE_BYTES, and CU_JIT_ERROR_LOG_BUFFER_SIZE_BYTES
will accumulate data until the CUlinkState is destroyed.
The data passed in via cuLinkAddData and cuLinkAddFile will be treated as relocatable (-rdc=true
to nvcc) when linking the final cubin during cuLinkComplete and will have similar consequences as
offline relocatable device code linking.
|
154
Modules
optionValues must remain valid for the life of the CUlinkState if output options are used. No other
references to inputs are maintained after this call returns.
Note:
For LTO-IR input, only LTO-IR compiled with toolkits prior to CUDA 12.0 will be accepted
Note:
Note that this function may also return error codes from previous, asynchronous launches.
See also:
cuLinkAddData, cuLinkAddFile, cuLinkComplete, cuLinkDestroy
CUresult cuLinkDestroy (CUlinkState state)
Destroys state for a JIT linker invocation.
Parameters
state
State object for the linker invocation
Returns
CUDA_SUCCESS, CUDA_ERROR_INVALID_HANDLE
Description
See also:
cuLinkCreate
CUresult cuModuleEnumerateFunctions (CUfunction
*functions, unsigned int numFunctions, CUmodule mod)
Returns the function handles within a module.
Parameters
functions
- Buffer where the function handles are returned to
numFunctions
- Maximum number of function handles may be returned to the buffer
|
155
Modules
mod
- Module to query from
Returns
CUDA_SUCCESS, CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_HANDLE,
CUDA_ERROR_INVALID_VALUE
Description
Returns in functions a maximum number of numFunctions function handles within mod. When
function loading mode is set to LAZY the function retrieved may be partially loaded. The loading
state of a function can be queried using cuFunctionIsLoaded. CUDA APIs may load the function
automatically when called with partially loaded function handle which may incur additional latency.
Alternatively, cuFunctionLoad can be used to explicitly load a function. The returned function handles
become invalid when the module is unloaded.
See also:
cuModuleGetFunction, cuModuleGetFunctionCount, cuFuncIsLoaded, cuFuncLoad
CUresult cuModuleGetFunction (CUfunction *hfunc,
CUmodule hmod, const char *name)
Returns a function handle.
Parameters
hfunc
- Returned function handle
hmod
- Module to retrieve function from
name
- Name of function to retrieve
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_VALUE,
CUDA_ERROR_NOT_FOUND
Description
Returns in *hfunc the handle of the function of name name located in module hmod. If no function
of that name exists, cuModuleGetFunction() returns CUDA_ERROR_NOT_FOUND.
|
156
Modules
Note:
Note that this function may also return error codes from previous, asynchronous launches.
See also:
cuModuleGetGlobal, cuModuleGetTexRef, cuModuleLoad, cuModuleLoadData,
cuModuleLoadDataEx, cuModuleLoadFatBinary, cuModuleUnload
CUresult cuModuleGetFunctionCount (unsigned int
*count, CUmodule mod)
Returns the number of functions within a module.
Parameters
count
- Number of functions found within the module
mod
- Module to query
Returns
CUDA_SUCCESS, CUDA_ERROR_INVALID_HANDLE, CUDA_ERROR_INVALID_VALUE
Description
Returns in count the number of functions in mod.
CUresult cuModuleGetGlobal (CUdeviceptr *dptr, size_t
*bytes, CUmodule hmod, const char *name)
Returns a global pointer from a module.
Parameters
dptr
- Returned global device pointer
bytes
- Returned global size in bytes
hmod
- Module to retrieve global from
name
- Name of global to retrieve
|
157
Modules
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_VALUE,
CUDA_ERROR_NOT_FOUND
Description
Returns in *dptr and *bytes the base pointer and size of the global of name name
located in module hmod. If no variable of that name exists, cuModuleGetGlobal() returns
CUDA_ERROR_NOT_FOUND. One of the parameters dptr or bytes (not both) can be NULL in
which case it is ignored.
Note:
Note that this function may also return error codes from previous, asynchronous launches.
See also:
cuModuleGetFunction, cuModuleGetTexRef, cuModuleLoad, cuModuleLoadData,
cuModuleLoadDataEx, cuModuleLoadFatBinary, cuModuleUnload, cudaGetSymbolAddress,
cudaGetSymbolSize
CUresult cuModuleGetLoadingMode
(CUmoduleLoadingMode *mode)
Query lazy loading mode.
Parameters
mode
- Returns the lazy loading mode
Returns
CUDA_SUCCESS, CUDA_ERROR_INVALID_VALUE,
Description
Returns lazy loading mode Module loading mode is controlled by CUDA_MODULE_LOADING env
variable
Note:
Note that this function may also return error codes from previous, asynchronous launches.
|
158
Modules
See also:
cuModuleLoad,
CUresult cuModuleLoad (CUmodule *module, const char
*fname)
Loads a compute module.
Parameters
module
- Returned module
fname
- Filename of module to load
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_VALUE,
CUDA_ERROR_INVALID_PTX, CUDA_ERROR_UNSUPPORTED_PTX_VERSION,
CUDA_ERROR_NOT_FOUND, CUDA_ERROR_OUT_OF_MEMORY,
CUDA_ERROR_FILE_NOT_FOUND, CUDA_ERROR_NO_BINARY_FOR_GPU,
CUDA_ERROR_SHARED_OBJECT_SYMBOL_NOT_FOUND,
CUDA_ERROR_SHARED_OBJECT_INIT_FAILED,
CUDA_ERROR_JIT_COMPILER_NOT_FOUND
Description
Takes a filename fname and loads the corresponding module module into the current context.
The CUDA driver API does not attempt to lazily allocate the resources needed by a module; if the
memory for functions and data (constant and global) needed by the module cannot be allocated,
cuModuleLoad() fails. The file should be a cubin file as output by nvcc, or a PTX file either as output
by nvcc or handwritten, or a fatbin file as output by nvcc from toolchain 4.0 or later.
Note:
Note that this function may also return error codes from previous, asynchronous launches.
See also:
cuModuleGetFunction, cuModuleGetGlobal, cuModuleGetTexRef, cuModuleLoadData,
cuModuleLoadDataEx, cuModuleLoadFatBinary, cuModuleUnload
|
159
Modules
CUresult cuModuleLoadData (CUmodule *module, const
void *image)
Load a module's data.
Parameters
module
- Returned module
image
- Module data to load
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_VALUE,
CUDA_ERROR_INVALID_PTX, CUDA_ERROR_UNSUPPORTED_PTX_VERSION,
CUDA_ERROR_OUT_OF_MEMORY, CUDA_ERROR_NO_BINARY_FOR_GPU,
CUDA_ERROR_SHARED_OBJECT_SYMBOL_NOT_FOUND,
CUDA_ERROR_SHARED_OBJECT_INIT_FAILED,
CUDA_ERROR_JIT_COMPILER_NOT_FOUND
Description
Takes a pointer image and loads the corresponding module module into the current context. The
image may be a cubin or fatbin as output by nvcc, or a NULL-terminated PTX, either as output by
nvcc or hand-written.
Note:
Note that this function may also return error codes from previous, asynchronous launches.
See also:
cuModuleGetFunction, cuModuleGetGlobal, cuModuleGetTexRef, cuModuleLoad,
cuModuleLoadDataEx, cuModuleLoadFatBinary, cuModuleUnload
|
160
Modules
CUresult cuModuleLoadDataEx (CUmodule *module,
const void *image, unsigned int numOptions, CUjit_option
*options, void **optionValues)
Load a module's data with options.
Parameters
module
- Returned module
image
- Module data to load
numOptions
- Number of options
options
- Options for JIT
optionValues
- Option values for JIT
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_VALUE,
CUDA_ERROR_INVALID_PTX, CUDA_ERROR_UNSUPPORTED_PTX_VERSION,
CUDA_ERROR_OUT_OF_MEMORY, CUDA_ERROR_NO_BINARY_FOR_GPU,
CUDA_ERROR_SHARED_OBJECT_SYMBOL_NOT_FOUND,
CUDA_ERROR_SHARED_OBJECT_INIT_FAILED,
CUDA_ERROR_JIT_COMPILER_NOT_FOUND
Description
Takes a pointer image and loads the corresponding module module into the current context. The
image may be a cubin or fatbin as output by nvcc, or a NULL-terminated PTX, either as output by
nvcc or hand-written.
Note:
Note that this function may also return error codes from previous, asynchronous launches.
See also:
cuModuleGetFunction, cuModuleGetGlobal, cuModuleGetTexRef, cuModuleLoad,
cuModuleLoadData, cuModuleLoadFatBinary, cuModuleUnload
|
161
Modules
CUresult cuModuleLoadFatBinary (CUmodule *module,
const void *fatCubin)
Load a module's data.
Parameters
module
- Returned module
fatCubin
- Fat binary to load
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_VALUE,
CUDA_ERROR_INVALID_PTX, CUDA_ERROR_UNSUPPORTED_PTX_VERSION,
CUDA_ERROR_NOT_FOUND, CUDA_ERROR_OUT_OF_MEMORY,
CUDA_ERROR_NO_BINARY_FOR_GPU,
CUDA_ERROR_SHARED_OBJECT_SYMBOL_NOT_FOUND,
CUDA_ERROR_SHARED_OBJECT_INIT_FAILED,
CUDA_ERROR_JIT_COMPILER_NOT_FOUND
Description
Takes a pointer fatCubin and loads the corresponding module module into the current context.
The pointer represents a fat binary object, which is a collection of different cubin and/or PTX files, all
representing the same device code, but compiled and optimized for different architectures.
Prior to CUDA 4.0, there was no documented API for constructing and using fat binary objects by
programmers. Starting with CUDA 4.0, fat binary objects can be constructed by providing the -fatbin
option to nvcc. More information can be found in the nvcc document.
Note:
Note that this function may also return error codes from previous, asynchronous launches.
See also:
cuModuleGetFunction, cuModuleGetGlobal, cuModuleGetTexRef, cuModuleLoad,
cuModuleLoadData, cuModuleLoadDataEx, cuModuleUnload
|
162
Modules
CUresult cuModuleUnload (CUmodule hmod)
Unloads a module.
Parameters
hmod
- Module to unload
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_VALUE,
CUDA_ERROR_NOT_PERMITTED
Description
Unloads a module hmod from the current context. Attempting to unload a module which
was obtained from the Library Management API such as cuLibraryGetModule will return
CUDA_ERROR_NOT_PERMITTED.
Note:
‣ Note that this function may also return error codes from previous, asynchronous launches.
‣ Use of the handle after this call is undefined behavior.
See also:
cuModuleGetFunction, cuModuleGetGlobal, cuModuleGetTexRef, cuModuleLoad,
cuModuleLoadData, cuModuleLoadDataEx, cuModuleLoadFatBinary
6.11. Module Management [DEPRECATED]
This section describes the deprecated module management functions of the low-level CUDA driver
application programming interface.
|
163
Modules
CUresult cuModuleGetSurfRef (CUsurfref *pSurfRef,
CUmodule hmod, const char *name)
Returns a handle to a surface reference.
Parameters
pSurfRef
- Returned surface reference
hmod
- Module to retrieve surface reference from
name
- Name of surface reference to retrieve
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_VALUE,
CUDA_ERROR_NOT_FOUND
Description
Deprecated
Returns in *pSurfRef the handle of the surface reference of name name in the module hmod. If no
surface reference of that name exists, cuModuleGetSurfRef() returns CUDA_ERROR_NOT_FOUND.
Note:
Note that this function may also return error codes from previous, asynchronous launches.
See also:
cuModuleGetFunction, cuModuleGetGlobal, cuModuleGetTexRef, cuModuleLoad,
cuModuleLoadData, cuModuleLoadDataEx, cuModuleLoadFatBinary, cuModuleUnload
CUresult cuModuleGetTexRef (CUtexref *pTexRef,
CUmodule hmod, const char *name)
Returns a handle to a texture reference.
Parameters
pTexRef
- Returned texture reference
|
164
Modules
hmod
- Module to retrieve texture reference from
name
- Name of texture reference to retrieve
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_VALUE,
CUDA_ERROR_NOT_FOUND
Description
Deprecated
Returns in *pTexRef the handle of the texture reference of name name in the module hmod. If no
texture reference of that name exists, cuModuleGetTexRef() returns CUDA_ERROR_NOT_FOUND.
This texture reference handle should not be destroyed, since it will be destroyed when the module is
unloaded.
Note:
Note that this function may also return error codes from previous, asynchronous launches.
See also:
cuModuleGetFunction, cuModuleGetGlobal, cuModuleGetSurfRef, cuModuleLoad,
cuModuleLoadData, cuModuleLoadDataEx, cuModuleLoadFatBinary, cuModuleUnload
6.12. Library Management
This section describes the library management functions of the low-level CUDA driver application
programming interface.
CUresult cuKernelGetAttribute (int *pi,
CUfunction_attribute attrib, CUkernel kernel, CUdevice
dev)
Returns information about a kernel.
Parameters
pi
- Returned attribute value
|
165
Modules
attrib
- Attribute requested
kernel
- Kernel to query attribute of
dev
- Device to query attribute of
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_HANDLE, CUDA_ERROR_INVALID_VALUE,
CUDA_ERROR_INVALID_DEVICE
Description
Returns in *pi the integer value of the attribute attrib for the kernel kernel for the requested
device dev. The supported attributes are:
‣ CU_FUNC_ATTRIBUTE_MAX_THREADS_PER_BLOCK: The maximum number of threads
per block, beyond which a launch of the kernel would fail. This number depends on both the kernel
and the requested device.
‣ CU_FUNC_ATTRIBUTE_SHARED_SIZE_BYTES: The size in bytes of statically-allocated
shared memory per block required by this kernel. This does not include dynamically-allocated
shared memory requested by the user at runtime.
‣ CU_FUNC_ATTRIBUTE_CONST_SIZE_BYTES: The size in bytes of user-allocated constant
memory required by this kernel.
‣ CU_FUNC_ATTRIBUTE_LOCAL_SIZE_BYTES: The size in bytes of local memory used by
each thread of this kernel.
‣ CU_FUNC_ATTRIBUTE_NUM_REGS: The number of registers used by each thread of this
kernel.
‣ CU_FUNC_ATTRIBUTE_PTX_VERSION: The PTX virtual architecture version for which the
kernel was compiled. This value is the major PTX version * 10 + the minor PTX version, so a PTX
version 1.3 function would return the value 13. Note that this may return the undefined value of 0
for cubins compiled prior to CUDA 3.0.
‣ CU_FUNC_ATTRIBUTE_BINARY_VERSION: The binary architecture version for which the
kernel was compiled. This value is the major binary version * 10 + the minor binary version, so a
binary version 1.3 function would return the value 13. Note that this will return a value of 10 for
legacy cubins that do not have a properly-encoded binary architecture version.
‣ CU_FUNC_CACHE_MODE_CA: The attribute to indicate whether the kernel has been compiled
with user specified option "-Xptxas --dlcm=ca" set.
‣ CU_FUNC_ATTRIBUTE_MAX_DYNAMIC_SHARED_SIZE_BYTES: The maximum size in
bytes of dynamically-allocated shared memory.
‣ CU_FUNC_ATTRIBUTE_PREFERRED_SHARED_MEMORY_CARVEOUT: Preferred shared
memory-L1 cache split ratio in percent of total shared memory.
|
166
Modules
‣ CU_FUNC_ATTRIBUTE_CLUSTER_SIZE_MUST_BE_SET: If this attribute is set, the kernel
must launch with a valid cluster size specified.
‣ CU_FUNC_ATTRIBUTE_REQUIRED_CLUSTER_WIDTH: The required cluster width in
blocks.
‣ CU_FUNC_ATTRIBUTE_REQUIRED_CLUSTER_HEIGHT: The required cluster height in
blocks.
‣ CU_FUNC_ATTRIBUTE_REQUIRED_CLUSTER_DEPTH: The required cluster depth in
blocks.
‣ CU_FUNC_ATTRIBUTE_NON_PORTABLE_CLUSTER_SIZE_ALLOWED: Indicates whether
the function can be launched with non-portable cluster size. 1 is allowed, 0 is disallowed. A
non-portable cluster size may only function on the specific SKUs the program is tested on. The
launch might fail if the program is run on a different hardware platform. CUDA API provides
cudaOccupancyMaxActiveClusters to assist with checking whether the desired size can be
launched on the current device. A portable cluster size is guaranteed to be functional on all
compute capabilities higher than the target compute capability. The portable cluster size for sm_90
is 8 blocks per cluster. This value may increase for future compute capabilities. The specific
hardware unit may support higher cluster sizes that’s not guaranteed to be portable.
‣ CU_FUNC_ATTRIBUTE_CLUSTER_SCHEDULING_POLICY_PREFERENCE: The block
scheduling policy of a function. The value type is CUclusterSchedulingPolicy.
Note:
If another thread is trying to set the same attribute on the same device using cuKernelSetAttribute()
simultaneously, the attribute query will give the old or new value depending on the interleavings chosen
by the OS scheduler and memory consistency.
See also:
cuLibraryLoadData, cuLibraryLoadFromFile, cuLibraryUnload, cuKernelSetAttribute,
cuLibraryGetKernel, cuLaunchKernel, cuKernelGetFunction, cuLibraryGetModule,
cuModuleGetFunction, cuFuncGetAttribute
CUresult cuKernelGetFunction (CUfunction *pFunc,
CUkernel kernel)
Returns a function handle.
Parameters
pFunc
- Returned function handle
kernel
- Kernel to retrieve function for the requested context
|
167
Modules
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_VALUE, CUDA_ERROR_INVALID_HANDLE,
CUDA_ERROR_NOT_FOUND, CUDA_ERROR_INVALID_CONTEXT,
CUDA_ERROR_CONTEXT_IS_DESTROYED
Description
Returns in pFunc the handle of the function for the requested kernel kernel and the current context.
If function handle is not found, the call returns CUDA_ERROR_NOT_FOUND.
See also:
cuLibraryLoadData, cuLibraryLoadFromFile, cuLibraryUnload, cuLibraryGetKernel,
cuLibraryGetModule, cuModuleGetFunction
CUresult cuKernelGetLibrary (CUlibrary *pLib, CUkernel
kernel)
Returns a library handle.
Parameters
pLib
- Returned library handle
kernel
- Kernel to retrieve library handle
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_VALUE, CUDA_ERROR_INVALID_HANDLE,
CUDA_ERROR_NOT_FOUND
Description
Returns in pLib the handle of the library for the requested kernel kernel
See also:
cuLibraryLoadData, cuLibraryLoadFromFile, cuLibraryUnload, cuLibraryGetKernel
|
168
Modules
CUresult cuKernelGetName (const char **name, CUkernel
hfunc)
Returns the function name for a CUkernel handle.
Parameters
name
- The returned name of the function
hfunc
- The function handle to retrieve the name for
Returns
CUDA_SUCCESS, CUDA_ERROR_INVALID_VALUE
Description
Returns in **name the function name associated with the kernel handle hfunc . The function name is
returned as a null-terminated string. The returned name is only valid when the kernel handle is valid. If
the library is unloaded or reloaded, one must call the API again to get the updated name. This API may
return a mangled name if the function is not declared as having C linkage. If either **name or hfunc
is NULL, CUDA_ERROR_INVALID_VALUE is returned.
Note:
Note that this function may also return error codes from previous, asynchronous launches.
CUresult cuKernelGetParamInfo (CUkernel kernel, size_t
paramIndex, size_t *paramOffset, size_t *paramSize)
Returns the offset and size of a kernel parameter in the device-side parameter layout.
Parameters
kernel
- The kernel to query
paramIndex
- The parameter index to query
paramOffset
- Returns the offset into the device-side parameter layout at which the parameter resides
paramSize
- Optionally returns the size of the parameter in the device-side parameter layout
|
169
Modules
Returns
CUDA_SUCCESS, CUDA_ERROR_INVALID_VALUE,
Description
Queries the kernel parameter at paramIndex into kernel's list of parameters, and returns in
paramOffset and paramSize the offset and size, respectively, where the parameter will reside
in the device-side parameter layout. This information can be used to update kernel node parameters
from the device via cudaGraphKernelNodeSetParam() and cudaGraphKernelNodeUpdatesApply().
paramIndex must be less than the number of parameters that kernel takes. paramSize can be
set to NULL if only the parameter offset is desired.
Note:
Note that this function may also return error codes from previous, asynchronous launches.
See also:
cuFuncGetParamInfo
CUresult cuKernelSetAttribute (CUfunction_attribute
attrib, int val, CUkernel kernel, CUdevice dev)
Sets information about a kernel.
Parameters
attrib
- Attribute requested
val
- Value to set
kernel
- Kernel to set attribute of
dev
- Device to set attribute of
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_HANDLE, CUDA_ERROR_INVALID_VALUE,
CUDA_ERROR_INVALID_DEVICE, CUDA_ERROR_OUT_OF_MEMORY
|
170
Modules
Description
This call sets the value of a specified attribute attrib on the kernel kernel for the requested
device dev to an integer value specified by val. This function returns CUDA_SUCCESS if the new
value of the attribute could be successfully set. If the set fails, this call will return an error. Not all
attributes can have values set. Attempting to set a value on a read-only attribute will result in an error
(CUDA_ERROR_INVALID_VALUE)
Note that attributes set using cuFuncSetAttribute() will override the attribute set by this API
irrespective of whether the call to cuFuncSetAttribute() is made before or after this API call. However,
cuKernelGetAttribute() will always return the attribute value set by this API.
Supported attributes are:
‣ CU_FUNC_ATTRIBUTE_MAX_DYNAMIC_SHARED_SIZE_BYTES: This is the maximum
size in bytes of dynamically-allocated shared memory. The value should contain the requested
maximum size of dynamically-allocated shared memory. The sum of this value and the function
attribute CU_FUNC_ATTRIBUTE_SHARED_SIZE_BYTES cannot exceed the device attribute
CU_DEVICE_ATTRIBUTE_MAX_SHARED_MEMORY_PER_BLOCK_OPTIN. The maximal
size of requestable dynamic shared memory may differ by GPU architecture.
‣ CU_FUNC_ATTRIBUTE_PREFERRED_SHARED_MEMORY_CARVEOUT: On
devices where the L1 cache and shared memory use the same hardware resources, this
sets the shared memory carveout preference, in percent of the total shared memory. See
CU_DEVICE_ATTRIBUTE_MAX_SHARED_MEMORY_PER_MULTIPROCESSOR This is
only a hint, and the driver can choose a different ratio if required to execute the function.
‣ CU_FUNC_ATTRIBUTE_REQUIRED_CLUSTER_WIDTH: The required cluster width in
blocks. The width, height, and depth values must either all be 0 or all be positive. The validity of
the cluster dimensions is checked at launch time. If the value is set during compile time, it cannot
be set at runtime. Setting it at runtime will return CUDA_ERROR_NOT_PERMITTED.
‣ CU_FUNC_ATTRIBUTE_REQUIRED_CLUSTER_HEIGHT: The required cluster height in
blocks. The width, height, and depth values must either all be 0 or all be positive. The validity of
the cluster dimensions is checked at launch time. If the value is set during compile time, it cannot
be set at runtime. Setting it at runtime will return CUDA_ERROR_NOT_PERMITTED.
‣ CU_FUNC_ATTRIBUTE_REQUIRED_CLUSTER_DEPTH: The required cluster depth in
blocks. The width, height, and depth values must either all be 0 or all be positive. The validity of
the cluster dimensions is checked at launch time. If the value is set during compile time, it cannot
be set at runtime. Setting it at runtime will return CUDA_ERROR_NOT_PERMITTED.
‣ CU_FUNC_ATTRIBUTE_NON_PORTABLE_CLUSTER_SIZE_ALLOWED: Indicates whether
the function can be launched with non-portable cluster size. 1 is allowed, 0 is disallowed.
‣ CU_FUNC_ATTRIBUTE_CLUSTER_SCHEDULING_POLICY_PREFERENCE: The block
scheduling policy of a function. The value type is CUclusterSchedulingPolicy.
Note:
|
171
Modules
The API has stricter locking requirements in comparison to its legacy counterpart cuFuncSetAttribute()
due to device-wide semantics. If multiple threads are trying to set the same attribute on the same device
simultaneously, the attribute setting will depend on the interleavings chosen by the OS scheduler and
memory consistency.
See also:
cuLibraryLoadData, cuLibraryLoadFromFile, cuLibraryUnload, cuKernelGetAttribute,
cuLibraryGetKernel, cuLaunchKernel, cuKernelGetFunction, cuLibraryGetModule,
cuModuleGetFunction, cuFuncSetAttribute
CUresult cuKernelSetCacheConfig (CUkernel kernel,
CUfunc_cache config, CUdevice dev)
Sets the preferred cache configuration for a device kernel.
Parameters
kernel
- Kernel to configure cache for
config
- Requested cache configuration
dev
- Device to set attribute of
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_HANDLE, CUDA_ERROR_INVALID_VALUE,
CUDA_ERROR_INVALID_DEVICE, CUDA_ERROR_OUT_OF_MEMORY
Description
On devices where the L1 cache and shared memory use the same hardware resources, this sets through
config the preferred cache configuration for the device kernel kernel on the requested device dev.
This is only a preference. The driver will use the requested configuration if possible, but it is free to
choose a different configuration if required to execute kernel. Any context-wide preference set via
cuCtxSetCacheConfig() will be overridden by this per-kernel setting.
Note that attributes set using cuFuncSetCacheConfig() will override the attribute set by this API
irrespective of whether the call to cuFuncSetCacheConfig() is made before or after this API call.
This setting does nothing on devices where the size of the L1 cache and shared memory are fixed.
Launching a kernel with a different preference than the most recent preference setting may insert a
device-side synchronization point.
The supported cache configurations are:
|
172
Modules
‣ CU_FUNC_CACHE_PREFER_NONE: no preference for shared memory or L1 (default)
‣ CU_FUNC_CACHE_PREFER_SHARED: prefer larger shared memory and smaller L1 cache
‣ CU_FUNC_CACHE_PREFER_L1: prefer larger L1 cache and smaller shared memory
‣ CU_FUNC_CACHE_PREFER_EQUAL: prefer equal sized L1 cache and shared memory
Note:
The API has stricter locking requirements in comparison to its legacy counterpart
cuFuncSetCacheConfig() due to device-wide semantics. If multiple threads are trying to set a config on
the same device simultaneously, the cache config setting will depend on the interleavings chosen by the
OS scheduler and memory consistency.
See also:
cuLibraryLoadData, cuLibraryLoadFromFile, cuLibraryUnload, cuLibraryGetKernel,
cuKernelGetFunction, cuLibraryGetModule, cuModuleGetFunction, cuFuncSetCacheConfig,
cuCtxSetCacheConfig, cuLaunchKernel
CUresult cuLibraryEnumerateKernels (CUkernel *kernels,
unsigned int numKernels, CUlibrary lib)
Retrieve the kernel handles within a library.
Parameters
kernels
- Buffer where the kernel handles are returned to
numKernels
- Maximum number of kernel handles may be returned to the buffer
lib
- Library to query from
Returns
CUDA_SUCCESS, CUDA_ERROR_INVALID_HANDLE, CUDA_ERROR_INVALID_VALUE
Description
Returns in kernels a maximum number of numKernels kernel handles within lib. The returned
kernel handle becomes invalid when the library is unloaded.
See also:
cuLibraryGetKernelCount
|
173
Modules
CUresult cuLibraryGetGlobal (CUdeviceptr *dptr, size_t
*bytes, CUlibrary library, const char *name)
Returns a global device pointer.
Parameters
dptr
- Returned global device pointer for the requested context
bytes
- Returned global size in bytes
library
- Library to retrieve global from
name
- Name of global to retrieve
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_VALUE, CUDA_ERROR_INVALID_HANDLE,
CUDA_ERROR_NOT_FOUND, CUDA_ERROR_INVALID_CONTEXT,
CUDA_ERROR_CONTEXT_IS_DESTROYED
Description
Returns in *dptr and *bytes the base pointer and size of the global with name name for the
requested library library and the current context. If no global for the requested name name exists,
the call returns CUDA_ERROR_NOT_FOUND. One of the parameters dptr or bytes (not both) can
be NULL in which case it is ignored.
See also:
cuLibraryLoadData, cuLibraryLoadFromFile, cuLibraryUnload, cuLibraryGetModule,
cuModuleGetGlobal
CUresult cuLibraryGetKernel (CUkernel *pKernel,
CUlibrary library, const char *name)
Returns a kernel handle.
Parameters
pKernel
- Returned kernel handle
library
- Library to retrieve kernel from
|
174
Modules
name
- Name of kernel to retrieve
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_VALUE, CUDA_ERROR_INVALID_HANDLE,
CUDA_ERROR_NOT_FOUND
Description
Returns in pKernel the handle of the kernel with name name located in library library. If kernel
handle is not found, the call returns CUDA_ERROR_NOT_FOUND.
See also:
cuLibraryLoadData, cuLibraryLoadFromFile, cuLibraryUnload, cuKernelGetFunction,
cuLibraryGetModule, cuModuleGetFunction
CUresult cuLibraryGetKernelCount (unsigned int *count,
CUlibrary lib)
Returns the number of kernels within a library.
Parameters
count
- Number of kernels found within the library
lib
- Library to query
Returns
CUDA_SUCCESS, CUDA_ERROR_INVALID_HANDLE, CUDA_ERROR_INVALID_VALUE
Description
Returns in count the number of kernels in lib.
|
175
Modules
CUresult cuLibraryGetManaged (CUdeviceptr *dptr, size_t
*bytes, CUlibrary library, const char *name)
Returns a pointer to managed memory.
Parameters
dptr
- Returned pointer to the managed memory
bytes
- Returned memory size in bytes
library
- Library to retrieve managed memory from
name
- Name of managed memory to retrieve
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_VALUE, CUDA_ERROR_INVALID_HANDLE,
CUDA_ERROR_NOT_FOUND
Description
Returns in *dptr and *bytes the base pointer and size of the managed memory with name name
for the requested library library. If no managed memory with the requested name name exists, the
call returns CUDA_ERROR_NOT_FOUND. One of the parameters dptr or bytes (not both) can be
NULL in which case it is ignored. Note that managed memory for library library is shared across
devices and is registered when the library is loaded into atleast one context.
See also:
cuLibraryLoadData, cuLibraryLoadFromFile, cuLibraryUnload
CUresult cuLibraryGetModule (CUmodule *pMod,
CUlibrary library)
Returns a module handle.
Parameters
pMod
- Returned module handle
library
- Library to retrieve module from
|
176
Modules
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_VALUE, CUDA_ERROR_INVALID_HANDLE,
CUDA_ERROR_NOT_FOUND, CUDA_ERROR_INVALID_CONTEXT,
CUDA_ERROR_CONTEXT_IS_DESTROYED
Description
Returns in pMod the module handle associated with the current context located in library library. If
module handle is not found, the call returns CUDA_ERROR_NOT_FOUND.
See also:
cuLibraryLoadData, cuLibraryLoadFromFile, cuLibraryUnload, cuModuleGetFunction
CUresult cuLibraryGetUnifiedFunction (void **fptr,
CUlibrary library, const char *symbol)
Returns a pointer to a unified function.
Parameters
fptr
- Returned pointer to a unified function
library
- Library to retrieve function pointer memory from
symbol
- Name of function pointer to retrieve
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_VALUE, CUDA_ERROR_INVALID_HANDLE,
CUDA_ERROR_NOT_FOUND
Description
Returns in *fptr the function pointer to a unified function denoted by symbol. If no unified function
with name symbol exists, the call returns CUDA_ERROR_NOT_FOUND. If there is no device with
attribute CU_DEVICE_ATTRIBUTE_UNIFIED_FUNCTION_POINTERS present in the system, the
call may return CUDA_ERROR_NOT_FOUND.
See also:
cuLibraryLoadData, cuLibraryLoadFromFile, cuLibraryUnload
|
177
Modules
CUresult cuLibraryLoadData (CUlibrary *library,
const void *code, CUjit_option *jitOptions, void
**jitOptionsValues, unsigned int numJitOptions,
CUlibraryOption *libraryOptions, void
**libraryOptionValues, unsigned int numLibraryOptions)
Load a library with specified code and options.
Parameters
library
- Returned library
code
- Code to load
jitOptions
- Options for JIT
jitOptionsValues
- Option values for JIT
numJitOptions
- Number of options
libraryOptions
- Options for loading
libraryOptionValues
- Option values for loading
numLibraryOptions
- Number of options for loading
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_VALUE, CUDA_ERROR_INVALID_PTX,
CUDA_ERROR_UNSUPPORTED_PTX_VERSION, CUDA_ERROR_OUT_OF_MEMORY,
CUDA_ERROR_NO_BINARY_FOR_GPU,
CUDA_ERROR_SHARED_OBJECT_SYMBOL_NOT_FOUND,
CUDA_ERROR_SHARED_OBJECT_INIT_FAILED,
CUDA_ERROR_JIT_COMPILER_NOT_FOUND, CUDA_ERROR_NOT_SUPPORTED
Description
Takes a pointer code and loads the corresponding library library based on the application defined
library loading mode:
|
178
Modules
‣ If module loading is set to EAGER, via the environment variables described in "Module loading",
library is loaded eagerly into all contexts at the time of the call and future contexts at the time
of creation until the library is unloaded with cuLibraryUnload().
‣ If the environment variables are set to LAZY, library is not immediately loaded onto all
existent contexts and will only be loaded when a function is needed for that context, such as a
kernel launch.
These environment variables are described in the CUDA programming guide under the "CUDA
environment variables" section.
The code may be a cubin or fatbin as output by nvcc, or a NULL-terminated PTX, either as output by
nvcc or hand-written. A fatbin should also contain relocatable code when doing separate compilation.
Options are passed as an array via jitOptions and any corresponding parameters are passed in
jitOptionsValues. The number of total JIT options is supplied via numJitOptions. Any
outputs will be returned via jitOptionsValues.
Library load options are passed as an array via libraryOptions and any corresponding parameters
are passed in libraryOptionValues. The number of total library load options is supplied via
numLibraryOptions.
Note:
If the library contains managed variables and no device in the system supports managed variables this
call is expected to return CUDA_ERROR_NOT_SUPPORTED
See also:
cuLibraryLoadFromFile, cuLibraryUnload, cuModuleLoad, cuModuleLoadData,
cuModuleLoadDataEx
CUresult cuLibraryLoadFromFile (CUlibrary
*library, const char *fileName, CUjit_option
*jitOptions, void **jitOptionsValues, unsigned int
numJitOptions, CUlibraryOption *libraryOptions, void
**libraryOptionValues, unsigned int numLibraryOptions)
Load a library with specified file and options.
Parameters
library
- Returned library
fileName
- File to load from
|
179
Modules
jitOptions
- Options for JIT
jitOptionsValues
- Option values for JIT
numJitOptions
- Number of options
libraryOptions
- Options for loading
libraryOptionValues
- Option values for loading
numLibraryOptions
- Number of options for loading
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_VALUE, CUDA_ERROR_INVALID_PTX,
CUDA_ERROR_UNSUPPORTED_PTX_VERSION, CUDA_ERROR_OUT_OF_MEMORY,
CUDA_ERROR_NO_BINARY_FOR_GPU,
CUDA_ERROR_SHARED_OBJECT_SYMBOL_NOT_FOUND,
CUDA_ERROR_SHARED_OBJECT_INIT_FAILED,
CUDA_ERROR_JIT_COMPILER_NOT_FOUND, CUDA_ERROR_NOT_SUPPORTED
Description
Takes a pointer code and loads the corresponding library library based on the application defined
library loading mode:
‣ If module loading is set to EAGER, via the environment variables described in "Module loading",
library is loaded eagerly into all contexts at the time of the call and future contexts at the time
of creation until the library is unloaded with cuLibraryUnload().
‣ If the environment variables are set to LAZY, library is not immediately loaded onto all
existent contexts and will only be loaded when a function is needed for that context, such as a
kernel launch.
These environment variables are described in the CUDA programming guide under the "CUDA
environment variables" section.
The file should be a cubin file as output by nvcc, or a PTX file either as output by nvcc or handwritten,
or a fatbin file as output by nvcc. A fatbin should also contain relocatable code when doing separate
compilation.
Options are passed as an array via jitOptions and any corresponding parameters are passed in
jitOptionsValues. The number of total options is supplied via numJitOptions. Any outputs
will be returned via jitOptionsValues.
|
180
Modules
Library load options are passed as an array via libraryOptions and any corresponding parameters
are passed in libraryOptionValues. The number of total library load options is supplied via
numLibraryOptions.
Note:
If the library contains managed variables and no device in the system supports managed variables this
call is expected to return CUDA_ERROR_NOT_SUPPORTED
See also:
cuLibraryLoadData, cuLibraryUnload, cuModuleLoad, cuModuleLoadData, cuModuleLoadDataEx
CUresult cuLibraryUnload (CUlibrary library)
Unloads a library.
Parameters
library
- Library to unload
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_VALUE
Description
Unloads the library specified with library
See also:
cuLibraryLoadData, cuLibraryLoadFromFile, cuModuleUnload
6.13. Memory Management
This section describes the memory management functions of the low-level CUDA driver application
programming interface.
|
181
Modules
struct CUmemDecompressParams
Structure describing the parameters that compose a single decompression operation.
enum CUmemDecompressAlgorithm
Bitmasks for CU_DEVICE_ATTRIBUTE_MEM_DECOMPRESS_ALGORITHM_MASK.
Values
CU_MEM_DECOMPRESS_UNSUPPORTED = 0
Decompression is unsupported.
CU_MEM_DECOMPRESS_ALGORITHM_DEFLATE = 1<<0
Deflate is supported.
CU_MEM_DECOMPRESS_ALGORITHM_SNAPPY = 1<<1
Snappy is supported.
CU_MEM_DECOMPRESS_ALGORITHM_LZ4 = 1<<2
LZ4 is supported.
CUresult cuArray3DCreate (CUarray *pHandle, const
CUDA_ARRAY3D_DESCRIPTOR *pAllocateArray)
Creates a 3D CUDA array.
Parameters
pHandle
- Returned array
pAllocateArray
- 3D array descriptor
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_VALUE,
CUDA_ERROR_OUT_OF_MEMORY, CUDA_ERROR_UNKNOWN
Description
Creates a CUDA array according to the CUDA_ARRAY3D_DESCRIPTOR structure
pAllocateArray and returns a handle to the new CUDA array in *pHandle. The
CUDA_ARRAY3D_DESCRIPTOR is defined as:
‎
typedef struct {
unsigned int Width;
unsigned int Height;
unsigned int Depth;
CUarray_format Format;
unsigned int NumChannels;
unsigned int Flags;
|
182
Modules
} CUDA_ARRAY3D_DESCRIPTOR;
where:
‣ Width, Height, and Depth are the width, height, and depth of the CUDA array (in elements);
the following types of CUDA arrays can be allocated:
‣ A 1D array is allocated if Height and Depth extents are both zero.
‣ A 2D array is allocated if only Depth extent is zero.
‣ A 3D array is allocated if all three extents are non-zero.
‣ A 1D layered CUDA array is allocated if only Height is zero and the
CUDA_ARRAY3D_LAYERED flag is set. Each layer is a 1D array. The number of layers is
determined by the depth extent.
‣ A 2D layered CUDA array is allocated if all three extents are non-zero and the
CUDA_ARRAY3D_LAYERED flag is set. Each layer is a 2D array. The number of layers is
determined by the depth extent.
‣ A cubemap CUDA array is allocated if all three extents are non-zero and the
CUDA_ARRAY3D_CUBEMAP flag is set. Width must be equal to Height, and Depth
must be six. A cubemap is a special type of 2D layered CUDA array, where the six layers
represent the six faces of a cube. The order of the six layers in memory is the same as that
listed in CUarray_cubemap_face.
‣ A cubemap layered CUDA array is allocated if all three extents are non-zero, and both,
CUDA_ARRAY3D_CUBEMAP and CUDA_ARRAY3D_LAYERED flags are set. Width
must be equal to Height, and Depth must be a multiple of six. A cubemap layered CUDA
array is a special type of 2D layered CUDA array that consists of a collection of cubemaps.
The first six layers represent the first cubemap, the next six layers form the second cubemap,
and so on.
‣ Format specifies the format of the elements; CUarray_format is defined as:
‎
typedef enum CUarray_format_enum {
CU_AD_FORMAT_UNSIGNED_INT8 = 0x01,
CU_AD_FORMAT_UNSIGNED_INT16 = 0x02,
CU_AD_FORMAT_UNSIGNED_INT32 = 0x03,
CU_AD_FORMAT_SIGNED_INT8 = 0x08,
CU_AD_FORMAT_SIGNED_INT16 = 0x09,
CU_AD_FORMAT_SIGNED_INT32 = 0x0a,
CU_AD_FORMAT_HALF = 0x10,
CU_AD_FORMAT_FLOAT = 0x20,
CU_AD_FORMAT_NV12 = 0xb0,
CU_AD_FORMAT_UNORM_INT8X1 = 0xc0,
CU_AD_FORMAT_UNORM_INT8X2 = 0xc1,
CU_AD_FORMAT_UNORM_INT8X4 = 0xc2,
CU_AD_FORMAT_UNORM_INT16X1 = 0xc3,
CU_AD_FORMAT_UNORM_INT16X2 = 0xc4,
CU_AD_FORMAT_UNORM_INT16X4 = 0xc5,
CU_AD_FORMAT_SNORM_INT8X1 = 0xc6,
CU_AD_FORMAT_SNORM_INT8X2 = 0xc7,
CU_AD_FORMAT_SNORM_INT8X4 = 0xc8,
CU_AD_FORMAT_SNORM_INT16X1 = 0xc9,
CU_AD_FORMAT_SNORM_INT16X2 = 0xca,
CU_AD_FORMAT_SNORM_INT16X4 = 0xcb,
CU_AD_FORMAT_BC1_UNORM = 0x91,
CU_AD_FORMAT_BC1_UNORM_SRGB = 0x92,
CU_AD_FORMAT_BC2_UNORM = 0x93,
|
183
Modules
CU_AD_FORMAT_BC2_UNORM_SRGB = 0x94,
CU_AD_FORMAT_BC3_UNORM = 0x95,
CU_AD_FORMAT_BC3_UNORM_SRGB = 0x96,
CU_AD_FORMAT_BC4_UNORM = 0x97,
CU_AD_FORMAT_BC4_SNORM = 0x98,
CU_AD_FORMAT_BC5_UNORM = 0x99,
CU_AD_FORMAT_BC5_SNORM = 0x9a,
CU_AD_FORMAT_BC6H_UF16 = 0x9b,
CU_AD_FORMAT_BC6H_SF16 = 0x9c,
CU_AD_FORMAT_BC7_UNORM = 0x9d,
CU_AD_FORMAT_BC7_UNORM_SRGB = 0x9e,
CU_AD_FORMAT_P010 = 0x9f,
CU_AD_FORMAT_P016 = 0xa1,
CU_AD_FORMAT_NV16 = 0xa2,
CU_AD_FORMAT_P210 = 0xa3,
CU_AD_FORMAT_P216 = 0xa4,
CU_AD_FORMAT_YUY2 = 0xa5,
CU_AD_FORMAT_Y210 = 0xa6,
CU_AD_FORMAT_Y216 = 0xa7,
CU_AD_FORMAT_AYUV = 0xa8,
CU_AD_FORMAT_Y410 = 0xa9,
CU_AD_FORMAT_Y416 = 0xb1,
CU_AD_FORMAT_Y444_PLANAR8 = 0xb2,
CU_AD_FORMAT_Y444_PLANAR10 = 0xb3,
CU_AD_FORMAT_YUV444_8bit_SemiPlanar = 0xb4,
CU_AD_FORMAT_YUV444_16bit_SemiPlanar = 0xb5,
CU_AD_FORMAT_UNORM_INT_101010_2 = 0x50,
} CUarray_format;
‣ NumChannels specifies the number of packed components per CUDA array element; it may be
1, 2, or 4;
‣ Flags may be set to
‣ CUDA_ARRAY3D_LAYERED to enable creation of layered CUDA arrays. If this flag is set,
Depth specifies the number of layers, not the depth of a 3D array.
‣ CUDA_ARRAY3D_SURFACE_LDST to enable surface references to be bound to the CUDA
array. If this flag is not set, cuSurfRefSetArray will fail when attempting to bind the CUDA
array to a surface reference.
‣ CUDA_ARRAY3D_CUBEMAP to enable creation of cubemaps. If this flag is set, Width
must be equal to Height, and Depth must be six. If the CUDA_ARRAY3D_LAYERED
flag is also set, then Depth must be a multiple of six.
‣ CUDA_ARRAY3D_TEXTURE_GATHER to indicate that the CUDA array will be used for
texture gather. Texture gather can only be performed on 2D CUDA arrays.
Width, Height and Depth must meet certain size requirements as listed in the following
table. All values are specified in elements. Note that for brevity's sake, the full name of the
device attribute is not specified. For ex., TEXTURE1D_WIDTH refers to the device attribute
CU_DEVICE_ATTRIBUTE_MAXIMUM_TEXTURE1D_WIDTH.
Note that 2D CUDA arrays have different size requirements if the
CUDA_ARRAY3D_TEXTURE_GATHER flag is set. Width and Height must not be
greater than CU_DEVICE_ATTRIBUTE_MAXIMUM_TEXTURE2D_GATHER_WIDTH and
CU_DEVICE_ATTRIBUTE_MAXIMUM_TEXTURE2D_GATHER_HEIGHT respectively, in that
case.
|
184
Modules
CUDA array type
Valid extents that must always be
Valid extents with
met {(width range in elements),
CUDA_ARRAY3D_SURFACE_LD
ST
(height range), (depth range)}
set {(width range in elements),
(height range), (depth range)}
1D
{ (1,TEXTURE1D_WIDTH), 0, 0 }
{ (1,SURFACE1D_WIDTH), 0, 0 }
2D
{ (1,TEXTURE2D_WIDTH),
{ (1,SURFACE2D_WIDTH),
(1,TEXTURE2D_HEIGHT), 0 }
(1,SURFACE2D_HEIGHT), 0 }
3D
{ (1,TEXTURE3D_WIDTH),
{ (1,SURFACE3D_WIDTH),
(1,TEXTURE3D_HEIGHT),
(1,SURFACE3D_HEIGHT),
(1,TEXTURE3D_DEPTH) } OR
(1,SURFACE3D_DEPTH) }
{ (1,TEXTURE3D_WIDTH_ALTERNATE),
(1,TEXTURE3D_HEIGHT_ALTERNATE),
(1,TEXTURE3D_DEPTH_ALTERNATE) }
1D Layered
{ (1,TEXTURE1D_LAYERED_WID{ (1,SURFACE1D_LAYERED_WIDTH),
0,
0,
(1,TEXTURE1D_LAYERED_LAYE
1,SURFACE1D_LAYERED_LAYE
RS) }
2D Layered
{ (1,TEXTURE2D_LAYERED_WID{ (1,SURFACE2D_LAYERED_WIDTH),
(1,TEXTURE2D_LAYERED_HEIG(1,SURFACE2D_LAYERED_HEIG
HT),
(1,TEXTURE2D_LAYERED_LAYE
1,SURFACE2D_LAYERED_LAYE
RS) }
Cubemap
{ (1,TEXTURECUBEMAP_WIDTH),
{ (1,SURFACECUBEMAP_WIDTH
),
(1,TEXTURECUBEMAP_WIDTH),
(1,SURFACECUBEMAP_WIDTH),
6 }
6 }
Cubemap Layered
{ (1,TEXTURECUBEMAP_LAYER{ (1,SURFACECUBEMAP_LAYER
ED_WIDTH),
(1,TEXTURECUBEMAP_LAYERE(1,SURFACECUBEMAP_LAYERE
D_WIDTH),
(1,TEXTURECUBEMAP_LAYERE
(1,SURFACECUBEMAP_LAYERE
D_LAYERS) }
Here are examples of CUDA array descriptions:
Description for a CUDA array of 2048 floats:
‎
CUDA_ARRAY3D_DESCRIPTOR desc;
desc.Format = CU_AD_FORMAT_FLOAT;
desc.NumChannels = 1;
desc.Width = 2048;
desc.Height = 0;
desc.Depth = 0;
Description for a 64 x 64 CUDA array of floats:
‎
CUDA_ARRAY3D_DESCRIPTOR desc;
desc.Format = CU_AD_FORMAT_FLOAT;
desc.NumChannels = 1;
desc.Width = 64;
desc.Height = 64;
desc.Depth = 0;
|
185
Modules
Description for a width x height x depth CUDA array of 64-bit, 4x16-bit float16's:
‎
CUDA_ARRAY3D_DESCRIPTOR desc;
desc.Format = CU_AD_FORMAT_HALF;
desc.NumChannels = 4;
desc.Width = width;
desc.Height = height;
desc.Depth = depth;
Note:
Note that this function may also return error codes from previous, asynchronous launches.
See also:
cuArray3DGetDescriptor, cuArrayCreate, cuArrayDestroy, cuArrayGetDescriptor, cuMemAlloc,
cuMemAllocHost, cuMemAllocPitch, cuMemcpy2D, cuMemcpy2DAsync, cuMemcpy2DUnaligned,
cuMemcpy3D, cuMemcpy3DAsync, cuMemcpyAtoA, cuMemcpyAtoD, cuMemcpyAtoH,
cuMemcpyAtoHAsync, cuMemcpyDtoA, cuMemcpyDtoD, cuMemcpyDtoDAsync,
cuMemcpyDtoH, cuMemcpyDtoHAsync, cuMemcpyHtoA, cuMemcpyHtoAAsync, cuMemcpyHtoD,
cuMemcpyHtoDAsync, cuMemFree, cuMemFreeHost, cuMemGetAddressRange, cuMemGetInfo,
cuMemHostAlloc, cuMemHostGetDevicePointer, cuMemsetD2D8, cuMemsetD2D16,
cuMemsetD2D32, cuMemsetD8, cuMemsetD16, cuMemsetD32, cudaMalloc3DArray
CUresult cuArray3DGetDescriptor
(CUDA_ARRAY3D_DESCRIPTOR *pArrayDescriptor,
CUarray hArray)
Get a 3D CUDA array descriptor.
Parameters
pArrayDescriptor
- Returned 3D array descriptor
hArray
- 3D array to get descriptor of
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED,
CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_VALUE,
CUDA_ERROR_INVALID_HANDLE, CUDA_ERROR_CONTEXT_IS_DESTROYED
Description
Returns in *pArrayDescriptor a descriptor containing information on the format and dimensions
of the CUDA array hArray. It is useful for subroutines that have been passed a CUDA array, but need
to know the CUDA array parameters for validation or other purposes.
|
186

 

 

 

 

 

 

 

 

Content      ..     1      2      3      4      ..