valid values for clSetKernelExecInfo

[bashbaug]

One of our engineers raised a question internally: if a set of indirectly accesseed SVM (or USM) pointers are set using clSetKernelExecInfo(CL_KERNEL_EXEC_INFO_SVM_PTRS), how are they "un-set"? To "un-set" all SVM pointers should an empty set be passed to clSetKernelExecInfo, specifically one where param_value_size is zero (and, possibly, param_value is nullptr)?

For reference: https://registry.khronos.org/OpenCL/specs/3.0-unified/html/OpenCL_API.html#clSetKernelExecInfo

The spec describes an error condition for invalid values, but never describes what values are considered invalid.

CL_INVALID_VALUE if param_name is not valid, if param_value is NULL or if the size specified by param_value_size is not valid.

I think we should clarify:

1. The empty set is valid and is the proper way to "un-set" any previously set SVM (or USM) pointers. Specifically:
2. When param_name is CL_KERNEL_EXEC_INFO_SVM_PTRS, passing zero for param_value_size is valid.
3. When param_name is CL_KERNEL_EXEC_INFO_SVM_PTRS, passing nullptr for param_value is valid if and only if param_value_size is zero.

TBD: When param_name is CL_KERNEL_EXEC_INFO_SVM_PTRS, is it valid to pass zero for param_value_size, and a non-nullptr value for param_value, or is this an error?

[bashbaug]

Discussed in the April 16th teleconference:

• We don’t have a lot of “setters” in OpenCL, so there is not a lot of precedence to base a decision upon.
• Setting the empty set does seem to be the best way to “un-set” all previously set pointers.
• Requiring nullptr for the empty set does seem to be the least error-prone, but it will require special-case handling if the set of pointers is stored in a std::vector, since the value of .data() is unspecified if .size() returns zero.
• Need to check if there is precedent for other APIs to mandate nullptr when the size is zero, or whether it is preferable to ignore the pointer when the size is zero.
• We will also need CTS tests to test this case.

[bashbaug]

• Need to check if there is precedent for other APIs to mandate nullptr when the size is zero, or whether it is preferable to ignore the pointer when the size is zero.

I did a quick check and as far as I can see we usually mandate nullptr when the size is zero. Some examples:

• clGetPlatformIDs says "If platforms is not NULL, num_entries must be greater than zero."
• clGetDeviceIDs likewise says "If devices is not NULL, the num_entries must be greater than zero."
• clEnqueueAcquireExternalMemObjectsKHR and other acquire and release functions return CL_INVALID_VALUE "if num_mem_objects is zero and mem_objects is not a NULL value".

I didn't find any pointer values that are ignored when a size is zero.

Therefore, unless someone wants to argue strongly that we break precedent and allow a non-NULL pointer in this case, I think we should require a NULL pointer, even if it requires special-case handling for an empty std::vector.