CL_VERSION_2_1 and CL_VERSION_2_2 missing in documentation

[TSlivede]

It is documented, that one can test the api version up to OpenCL 2.0 by testing macros like CL_VERSION_2_0. However the macros CL_VERSION_2_1 and CL_VERSION_2_2 are missing in the documentation, although they are defined in the header. Are these makros guarantied to be defined (in OpenCL 2.2) and just missing from the documentation or could there be conforming implementations, that don't define those?

Note: even the makros up to CL_VERSION_2_0 are only documented in the Appendix E: Changes to OpenCL and not in the main text.

Note 2: The string CL_VERSION_2_2 does appear in xml/cl.xml on line 4303 but I don't really get if that does mean, that a macro of that name is defined...

[alycm]

The CL_VERSION_2_0 and earlier macros that the appendix E text is referring to is for OpenCL C. The reason that there isn't a 2_1 or 2_2 macro is because there never was an OpenCL C 2.0 or 2.1.

The API changelog covers everything that changed in an OpenCL version, even if it is outside of the API spec. That is a bit confusing, but I think it's also handy to have all that information together.

However, since OpenCL 2.2 was released the OpenCL headers were "unified". There used to be different header for each version of OpenCL, now a single set covers them all with defines such as CL_VERSION_2_2. These defines aren't actually specified, and OpenCL implementations that continue to ship with older headers may not have them. Having the names be identical is maybe also confusing, but having them inconsistent between the API and OpenCL C would seem untidy to me.

I think we should do something to address this issue, the simplest thing would be to at least document that they're not required to be present. However, maybe there is some room for officially defining that these version macros are present at an API level (just like the CL_​DEVICE_​MAX_​WORK_​GROUP_​SIZE enum macro is there, as a random example).

[bashbaug]

Hmm, I do think this is a little confusing, and we may be able to document how the CL_VERSION_x_y macros work better in the spec. I think there are two issues:

1. There are CL_VERSION_x_y pre-processors macro defined by the OpenCL C compiler. They can be used with the __OPENCL_C_VERSION__ pre-processor macro to test which version of the OpenCL C standard the compiler is compiling for. Because there is no OpenCL C 2.1 or OpenCL C 2.2, there is no CL_VERSION_2_1 or CL_VERSION_2_2 OpenCL C version to test against. These pre-processor macros are described in the OpenCL C spec, and are also mentioned in the OpenCL API spec appendix.

2. There are also CL_VERSION_x_y pre-processor macros defined by the OpenCL Headers. They can be used to determine which version of the API headers an application is compiling with. These pre-processor macros are NOT described in the API spec.

Some things we clarify:

• In the OpenCL C spec, clarify that the CL_VERSION_x_y macros identify the OpenCL C version and not an OpenCL API version. In hindsight these macros should probably have been CL_C_VERSION_x_y.

• Describe what an OpenCL 2.1 or 2.2 implementation should define for __OPENCL_VERSION__. Is this the highest OpenCL C version supported by the device, or the OpenCL API version supported by the device? If it's the OpenCL API version supported by the device then we may need to define CL_VERSION_2_1 and CL_VERSION_2_2 anyhow.

• Consider describing the CL_VERSION_x_y pre-processor macros in the headers, either in the core spec (if they are formally part of the API) or in an appendix otherwise. This description would include CL_VERSION_2_1 and CL_VERSION_2_2.

• Update the current descriptions in the API spec appendix to disambiguate between these two usages.

I can update both specs once we agree on the direction. Thanks!

[TSlivede]

at least document that they're not required to be present

So is there no way, to determine (in an #if directive) which OpenCL API level is supported? Even if the requirement for CLVERSIONx_y would be added, that doesn't prevent the existance of an old conforming version of OpenCL which doesn't have the macro defined...

[bashbaug]

that doesn't prevent the existence of an old conforming version of OpenCL which doesn't have the macro defined...

For the OpenCL C compiler, the macro must be defined since it is part of the API. It looks like we don't have a test for the CL_VERSION_x_y macros specifically, but we do have a test for __OPENCL_C_VERSION__ here.

To determine which OpenCL API level is supported there are actually two questions:

1. What version of the headers are you using, and what version of OpenCL (likely the OpenCL ICD loader) are you linking with? This will put an upper bound on the APIs you can use, and can be tested with the CL_VERSION_x_y macros defined in the headers. These are not currently part of the official spec, but they could be, as described above.

2. For the chosen OpenCL implementation, what is the supported platform version and device version? Both of these queries are part of the spec and are required for a conforming implementation.

Does this help? How can we document this more clearly? Thanks!

[TSlivede]

1. What version of the headers are you using, and what version of OpenCL (likely the OpenCL ICD loader) are you linking with?

As the headers and the library to link against are (at least relatively often) shipped together, I'd just hope, that the versions of these two are matching. I would be happy, if I could just reliably test the version of the header.

[...] can be tested with the CL_VERSION_x_y macros defined in the headers.

As far as I understood, I actually can't use that macro, because although it would probably be available in most cases, it's not actually part of the standard. Or did I understand that incorrectly?

These are not currently part of the official spec, but they could be, as described above.

Even if they would be added, they could be only added to new standards, right? That would still not give the possibility to reliably test if the installed headers are for example at least those of OpenCL 2.0.

Or is there a possibility to add these macros to the old standards as well? With the argumentation, that they were always intended to be there (as seen in all shipped headers) and just forgotten in the document writing?

[StuartDBrady]

It seems clear that the __OPENCL_VERSION__ macro in OpenCL C would have been intended to be distinct from the __OPENCL_C_VERSION__ macro, i.e. it should describe the device's runtime OpenCL version (corresponding to the device's CL_DEVICE_VERSION string), not the OpenCL C language version, but it is not clear to me what purpose this actually serves.

It may be worth considering removing it from a future version of the OpenCL C specification if it serves none, as it should still be possible to query the device version using the runtime API, and pass this as a macro definition in the build options. At the least, in a future version of the specification, it would be better for this to be named __OPENCL_API_VERSION__ or __OPENCL_RUNTIME_VERSION__, or even __OPENCL_DEVICE_VERSION__ to better distinguish it from __OPENCL_C_VERSION__.

If none of the OpenCL 2.1 or OpenCL 2.2 implementations actually define it as 210 or 220, then it may be best instead to define it as 200 for those versions, stating this discrepancy explicitly in the specification.

[AnastasiaStulova]

Do we need anything more here than what has been done for #471?