Spec consistency around param_value_size parameter for many OpenCL procedures

[shajder]

In few cases of OpenCL API spec mentioned that param_value_size is ignored if related para_value is NULL, eg. :

param_value_size specifies the size in bytes of memory pointed to by param_value. This size must be ≥ size of return type as described in the table below. If param_value is NULL, it is ignored.

This is the case for clGetCommandBufferInfoKHR and clGetCommandQueueInfo.

For below, similar cases this information is missing.

clGetPlatformInfo, clGetDeviceInfo, clCreateSubDevices, clGetContextInfo, clGetSupportedImageFormats, clGetImageInfo, clGetPipeInfo, clGetMemObjectInfo, clGetGLTextureInfo, clGetSamplerInfo, clGetProgramInfo, clGetProgramBuildInfo, clCreateKernelsInProgram, clGetKernelInfo, clGetKernelWorkGroupInfo, clGetKernelSubGroupInfo, clGetKernelArgInfo, clGetEventInfo, clGetSemaphoreHandleForTypeKHR, clGetSemaphoreInfoKHR, clGetEventProfilingInfo, clGetMutableCommandInfoKHR, clGetGLContextInfoKHR

[bashbaug]

Discussed in the August 6th teleconference:

• We'll add the sentence to the other APIs to remove the inconsitency.
• We'll double-check the error conditions to make sure they are consistent, also.

We'll file an additional issue to possibly de-duplicate this information, or to add stricter error checking.

[kpet]

As part of creating https://github.com/KhronosGroup/OpenCL-Docs/pull/1220, I noticed that we should consider clGetSemaphoreHandleForTypeKHR too when resolving this issue. The name of the affected parameters are handle_size and handle_ptr but the pattern is exactly the same as with param_value_size/param_value.

[bashbaug]

Need to clarify exactly what should be updated for:

• clCreateSubDevices
• clGetsupportedImageFormats
• clCreateKernelsInProgram

These APIs have a slightly different pattern: they return an array of objects and/or the number of objects in the array. For example:

cl_int clCreateKernelsInProgram(
    cl_program program,
    cl_uint num_kernels,  // this is the allocated size of the array
    cl_kernel* kernels,  // this is the array itself, which stores the output from the function
    cl_uint* num_kernels_ret);  // this is the number of objects in the array

Do we want to say that the allocated size of the array ("num_kernels" in the esample above) is ignored if the array is NULL? It might be better to require that the allocated size of array must be zero when the array is NULL instead.

Regardless, I would prefer to resolve this with a separate PR.

[bashbaug]

1254 fixes most of these issues.

Moving to "Needs WG Discussion" to answer the question above regarding clCreateSubDevices, clGetsupportedImageFormats, and clCreateKernelsInProgram.

[shajder]

These APIs have a slightly different pattern: they return an array of objects and/or the number of objects in the array.

Indeed, pattern is not reflected exactly in mentioned cases and it may need a different description.