Used to set a SVM pointer as the argument value for a specific argument of a kernel.
kernel
A valid kernel object.
arg_index
The argument index. Arguments to the kernel are
referred by indices that go from 0
for the leftmost argument to n
- 1,
where n
is the total
number of arguments declared by a kernel.
arg_value
A pointer to the SVM pointer that should be used as the argument value for
argument specified by arg_index
.
The SVM pointer specified is the value used by all
API calls that enqueue kernel
(clEnqueueNDRangeKernel)
until the argument value is changed by a call to
clSetKernelArgSVMPointer
for kernel
.
The SVM pointer can only be used for arguments that
are declared to be a pointer to global or constant
memory. The SVM pointer value must
be aligned according to the argument’s type. For
example, if the argument is declared to be
global float4 *p
, the SVM pointer
value passed for p
must
be at a minimum aligned to a
float4. The SVM pointer value
specified as the argument value can be the pointer returned by
clSVMAlloc
or can be a pointer + offset into the SVM region.
All OpenCL API calls are thread-safe except
clSetKernelArg
and clSetKernelArgSVMPointer
.
clSetKernelArg
and clSetKernelArgSVMPointer
are safe
to call from any host thread, and safe to call re-entrantly so long as concurrent
calls operate on different cl_kernel objects.
However, the behavior of the cl_kernel object is undefined if
clSetKernelArg
or clSetKernelArgSVMPointer
are called from multiple host threads on the same
cl_kernel object at the same time. Please note that there
are additional limitations as to which OpenCL APIs may be called
from OpenCL callback functions -- please see section 5.11.
(Please refer to the OpenCL glossary for the OpenCL definition of thread-safe.
This definition may be different from usage of the term in other contexts.)
There is an inherent race condition in the design of OpenCL that occurs between setting a kernel argument and using the kernel with clEnqueueNDRangeKernel. Another host thread might change the kernel arguments between when a host thread sets the kernel arguments and then enqueues the kernel, causing the wrong kernel arguments to be enqueued. Rather than attempt to share cl_kernel objects among multiple host threads, applications are strongly encouraged to make additional cl_kernel objects for kernel functions for each host thread.
clSetKernelArgSVMPointer
returns CL_SUCCESS if the
function is executed successfully. Otherwise, it returns one of the following errors:
kernel
is not a valid kernel object.
arg_index
is not a valid argument index.
arg_value
specified is not a valid value.
clSetKernelArg, clCreateKernel, clCreateKernelsInProgram, clReleaseKernel, clRetainKernel, clGetKernelInfo, clGetKernelWorkGroupInfo