Interactions with the CUDA Driver API - interactions between CUDA Driver API and
CUDA Runtime API (cuda_runtime_api.h)
This section describes the interactions between the CUDA Driver API and the CUDA
There exists a one to one relationship between CUDA devices in the CUDA Runtime
API and CUcontext s in the CUDA Driver API within a process. The specific
context which the CUDA Runtime API uses for a device is called the device's
primary context. From the perspective of the CUDA Runtime API, a device and
its primary context are synonymous.
CUDA Runtime API calls operate on the CUDA Driver API CUcontext which is current
to to the calling host thread.
The function cudaSetDevice()
makes the primary context for the specified
device current to the calling thread by calling cuCtxSetCurrent().
The CUDA Runtime API will automatically initialize the primary context for a
device at the first CUDA Runtime API call which requires an active context. If
no CUcontext is current to the calling thread when a CUDA Runtime API call
which requires an active context is made, then the primary context for a
device will be selected, made current to the calling thread, and initialized.
The context which the CUDA Runtime API initializes will be initialized using the
parameters specified by the CUDA Runtime API functions
, and cudaVDPAUSetVDPAUDevice()
. Note that
these functions will fail with cudaErrorSetOnActiveProcess
if they are
called when the primary context for the specified device has already been
initialized. (or if the current device has already been initialized, in the
case of cudaSetDeviceFlags()
Primary contexts will remain active until they are explicitly deinitialized
. The function cudaDeviceReset()
deinitialize the primary context for the calling thread's current device
immediately. The context will remain current to all of the threads that it was
current to. The next CUDA Runtime API call on any thread which requires an
active context will trigger the reinitialization of that device's primary
Note that there is no reference counting of the primary context's lifetime. It
is recommended that the primary context not be deinitialized except just
before exit or to recover from an unspecified launch failure.
Note that the use of multiple CUcontext s per device within a single process
will substantially degrade performance and is strongly discouraged. Instead,
it is highly recommended that the implicit one-to-one device-to-context
mapping for the process provided by the CUDA Runtime API be used.
If a non-primary CUcontext created by the CUDA Driver API is current to a thread
then the CUDA Runtime API calls to that thread will operate on that CUcontext,
with some exceptions listed below. Interoperability between data types is
discussed in the following sections.
The function cudaPointerGetAttributes()
will return the error
if the pointer being queried was
allocated by a non-primary context. The function
and the rest of the peer access API may
not be called when a non-primary CUcontext is current. To use the pointer
query and peer access APIs with a context created using the CUDA Driver API,
it is necessary that the CUDA Driver API be used to access these features.
All CUDA Runtime API state (e.g, global variables' addresses and values) travels
with its underlying CUcontext. In particular, if a CUcontext is moved from one
thread to another then all CUDA Runtime API state will move to that thread as
Please note that attaching to legacy contexts (those with a version of 3010 as
returned by cuCtxGetApiVersion()) is not possible. The CUDA Runtime will
in such cases.
The types CUstream and cudaStream_t
are identical and may be used
The types CUevent and cudaEvent_t
are identical and may be used
The types CUarray and struct cudaArray * represent the same data type and may be
used interchangeably by casting the two types between each other.
In order to use a CUarray in a CUDA Runtime API function which takes a struct
cudaArray *, it is necessary to explicitly cast the CUarray to a struct
In order to use a struct cudaArray * in a CUDA Driver API function which takes a
CUarray, it is necessary to explicitly cast the struct cudaArray * to a
The types CUgraphicsResource and cudaGraphicsResource_t
same data type and may be used interchangeably by casting the two types
between each other.
In order to use a CUgraphicsResource in a CUDA Runtime API function which takes
, it is necessary to explicitly cast the
CUgraphicsResource to a cudaGraphicsResource_t
In order to use a cudaGraphicsResource_t
in a CUDA Driver API function
which takes a CUgraphicsResource, it is necessary to explicitly cast the
to a CUgraphicsResource.
Generated automatically by Doxygen from the source code.