cuda.bindings._v2.driver.launch_kernel#

cuda.bindings._v2.driver.launch_kernel( intptr_t f, unsigned int grid_dim_x, unsigned int grid_dim_y, unsigned int grid_dim_z, unsigned int block_dim_x, unsigned int block_dim_y, unsigned int block_dim_z, unsigned int shared_mem_bytes, intptr_t h_stream, kernel_params, intptr_t extra, )#

Launches a CUDA function CUfunction or a CUDA kernel CUkernel.

Invokes the function CUfunction or the kernel CUkernel f on a grid_dim_x x grid_dim_y x grid_dim_z grid of blocks. Each block contains block_dim_x x block_dim_y x block_dim_z threads. shared_mem_bytes sets the amount of dynamic shared memory that will be available to each thread block. Kernel parameters to f can be specified in one of two ways:. 1) Kernel parameters can be specified via kernel_params. If f has N parameters, then kernel_params needs to be an array of N pointers. Each of kernel_params[0] through kernel_params[N-1] must point to a region of memory from which the actual kernel parameter will be copied. The number of kernel parameters and their offsets and sizes do not need to be specified as that information is retrieved directly from the kernel’s image. 2) Kernel parameters can also be packaged by the application into a single buffer that is passed in via the extra parameter. This places the burden on the application of knowing each kernel parameter’s size and alignment/padding within the buffer. Here is an example of using the extra parameter in this manner:. **View CUDA Toolkit Documentation for a C++ code example**. The extra parameter exists to allow cuLaunchKernel to take additional less commonly used arguments. extra specifies a list of names of extra settings and their corresponding values. Each extra setting name is immediately followed by the corresponding value. The list must be terminated with either NULL or CU_LAUNCH_PARAM_END.

CU_LAUNCH_PARAM_END, which indicates the end of the extra array;.
CU_LAUNCH_PARAM_BUFFER_POINTER, which specifies that the next value in extra will be a pointer to a buffer containing all the kernel parameters for launching kernel f;.
CU_LAUNCH_PARAM_BUFFER_SIZE, which specifies that the next value in extra will be a pointer to a size_t containing the size of the buffer specified with CU_LAUNCH_PARAM_BUFFER_POINTER;.

The error CUDA_ERROR_INVALID_VALUE will be returned if kernel parameters are specified with both kernel_params and extra (i.e. both kernel_params and extra are non-NULL). Calling launch_kernel() invalidates the persistent function state set through the following deprecated APIs: func_set_block_shape(), func_set_shared_size(), param_set_size(), param_seti(), param_setf(), param_setv(). Note that to use launch_kernel(), the kernel f must either have been compiled with toolchain version 3.2 or later so that it will contain kernel parameter information, or have no kernel parameters. If either of these conditions is not met, then launch_kernel() will return CUDA_ERROR_INVALID_IMAGE. Note that the API can also be used to launch context-less kernel CUkernel by querying the handle using library_get_kernel() and then passing it to the API by casting to CUfunction. Here, the context to launch the kernel on will either be taken from the specified stream h_stream or the current context in case of NULL stream.

Parameters:

f (intptr_t) – Function CUfunction or Kernel CUkernel to launch.
grid_dim_x (unsigned int) – Width of grid in blocks.
grid_dim_y (unsigned int) – Height of grid in blocks.
grid_dim_z (unsigned int) – Depth of grid in blocks.
block_dim_x (unsigned int) – X dimension of each thread block.
block_dim_y (unsigned int) – Y dimension of each thread block.
block_dim_z (unsigned int) – Z dimension of each thread block.
shared_mem_bytes (unsigned int) – Dynamic shared-memory size per thread block in bytes.
h_stream (intptr_t) – Stream identifier.
kernel_params (object) – Array of pointers to kernel parameters.
extra (intptr_t) – Extra options.