Deprecated API Prefix and Suffix Defines

[bashbaug]

I'm a little confused by the prefix and suffix pre-processor defines for deprecated OpenCL APIs. I believe this is a summary of what is in the headers currently:

API	Introduced In	Deprecated In	Prefix Define	Suffix Define
clSetCommandQueueProperty	OpenCL 1.0	OpenCL 1.1	(None!)	CL_EXT_SUFFIX__ VERSION_1_0_DEPRECATED
clCreateImage2D	OpenCL 1.0	OpenCL 1.2	CL_EXT_PREFIX__ VERSION_1_1_DEPRECATED	CL_EXT_SUFFIX__ VERSION_1_1_DEPRECATED
clCreateImage3D	OpenCL 1.0	OpenCL 1.2	CL_EXT_PREFIX__ VERSION_1_1_DEPRECATED	CL_EXT_SUFFIX__ VERSION_1_1_DEPRECATED
clEnqueueMarker	OpenCL 1.0	OpenCL 1.2	CL_EXT_PREFIX__ VERSION_1_1_DEPRECATED	CL_EXT_SUFFIX__ VERSION_1_1_DEPRECATED
clEnqueueWaitForEvents	OpenCL 1.0	OpenCL 1.2	CL_EXT_PREFIX__ VERSION_1_1_DEPRECATED	CL_EXT_SUFFIX__ VERSION_1_1_DEPRECATED
clEnqueueBarrier	OpenCL 1.0	OpenCL 1.2	CL_EXT_PREFIX__ VERSION_1_1_DEPRECATED	CL_EXT_SUFFIX__ VERSION_1_1_DEPRECATED
clUnloadCompiler	OpenCL 1.0	OpenCL 1.2	CL_EXT_PREFIX__ VERSION_1_1_DEPRECATED	CL_EXT_SUFFIX__ VERSION_1_1_DEPRECATED
clGetExtensionFunctionAddress	OpenCL 1.0	OpenCL 1.2	CL_EXT_PREFIX__ VERSION_1_1_DEPRECATED	CL_EXT_SUFFIX__ VERSION_1_1_DEPRECATED
clCreateCommandQueue	OpenCL 1.0	OpenCL 2.0	CL_EXT_PREFIX__ VERSION_1_2_DEPRECATED	CL_EXT_SUFFIX__ VERSION_1_2_DEPRECATED
clCreateSampler	OpenCL 1.0	OpenCL 2.0	CL_EXT_PREFIX__ VERSION_1_2_DEPRECATED	CL_EXT_SUFFIX__ VERSION_1_2_DEPRECATED
clEnqueueTask	OpenCL 1.0	OpenCL 2.0	CL_EXT_PREFIX__ VERSION_1_2_DEPRECATED	CL_EXT_SUFFIX__ VERSION_1_2_DEPRECATED
clCreateFromGLTexture2D	cl_khr_gl_sharing	OpenCL 1.2?	CL_EXT_PREFIX__ VERSION_1_1_DEPRECATED	CL_EXT_SUFFIX__ VERSION_1_1_DEPRECATED
clCreateFromGLTexture3D	cl_khr_gl_sharing	OpenCL 1.2?	CL_EXT_PREFIX__ VERSION_1_1_DEPRECATED	CL_EXT_SUFFIX__ VERSION_1_1_DEPRECATED
clGetKernelSubGroupInfoKHR	cl_khr_subgroups	OpenCL 2.1?	(None!)	CL_EXT_SUFFIX__ VERSION_2_0_DEPRECATED

Should the define indicate:

• When the API was added?
• When the API was last supported?
• When the API was deprecated?
• Or something else entirely?

Right now it looks like we have a bit of a mix, though it looks like we have more usage of "last supported" than anything else.

I'm looking at this to ensure that if we deprecate clSetProgramReleaseCallback we do it consistently. Thanks!

[bashbaug]

A bit more info: the prefix and suffix defines are mostly used to ensure proper deprecation messages are emitted when a deprecated API gets used. The deprecation messages can be suppressed by defining CL_USE_DEPRECATED_OPENCL_X_Y_APIS before including the headers.

Currently, if CL_USE_DEPRECATED_OPENCL_X_Y_APIS is defined then the corresponding prefix and suffix defines are empty, meaning no deprecation message gets printed for OpenCL X.Y APIs, otherwise the prefix and suffix defines are used to pass compiler-specific deprecation attributes.

I think this implies that the prefix and suffix defines should be when the APIs were added?

[Kerilk]

This is the one I've always considered true:

• When the API was last supported?

Aside from missing prefixes (mistakes?) I don't see incoherence with the above rule.

[bashbaug]

Yes, I agree that attaching prefix and suffix defines indicating when the API was last supported is most consistent with the current usage.

Admittedly this is a little confusing, since it means that if I define CL_USE_DEPRECATED_OPENCL_1_0_APIS I will still get a warning if I call clCreateCommandQueue even though it is an OpenCL 1.0 API. To suppress the warning, I would need to define CL_USE_DEPRECATED_OPENCL_1_2_APIS, since the last OpenCL version where clCreateCommandQueue was NOT deprecated was OpenCL 1.2.

I will keep the current usage for clSetProgramReleaseCallback so we stay consistent, but I do wonder if this should be improved. Thanks!

[oddhack]

Related, a while back I was looking at enhancing cl.xml and the generator scripts to be able to create C headers as we do with other Khronos APIs. The deprecation macros were basically opaque to me and one of the reasons I didn't pursue that very far as there didn't seem to be a really clear understanding of what the macros were for or how they were applied. So from that perspective it would be good to clear this up as well.

[bashbaug]

As an aside, we're also using CL_EXT_.... as our prefix for the deprecation macros, even for core API functions. This isn't broken, but it is a little weird. To fix this, we would add CL_API_... deprecation macros also.