clarify __OPENCL_VERSION__ (#522)

* clarify __OPENCL_VERSION__

* clarify the integer value returned for newer OpenCL versions

* change offline compiler behavior from must to should

* change offline compiler behavior from should to may

Author: bashbaug

OpenCL_C.txt

@@ -3430,10 +3430,13 @@ The following predefined macro names are available.
     source line (an integer constant).
 
 `+__OPENCL_VERSION__+` ::
-    Substitutes an integer reflecting the version number of the OpenCL
-    supported by the OpenCL device.
-    The version of OpenCL described in this document will have
-    `+__OPENCL_VERSION__+` substitute the integer 300.
+    For OpenCL devices with OpenCL version less than or equal to OpenCL 2.0,
+    substitutes an integer value reflecting the OpenCL version supported by the
+    device.
+    This predefined macro is <<unified-spec, deprecated by>> OpenCL 2.1.
+    For OpenCL devices with OpenCL version greater than OpenCL 2.0, it must be
+    defined but may substitute any implementation-defined integer value greater
+    than 200, reflecting OpenCL 2.0. footnote:[{fn-OPENCL_VERSION}]
 
 `CL_VERSION_1_0` ::
     Substitutes the integer 100 reflecting the OpenCL 1.0 version.

c/footnotes.asciidoc

@@ -192,6 +192,10 @@ Here `TYPE_MIN` and `TYPE_MIN_EXP` should be substituted by constants appropriat
 I.e. the _global_work_size_ values specified to *clEnqueueNDRangeKernel* are not evenly divisible by the _local_work_size_ values for each dimension. \
 ]
 
+:fn-OPENCL_VERSION: pass:n[ \
+When OpenCL C is compiled offline, `+__OPENCL_VERSION__+` may be defined and may substitute any implementation-defined integer value. \
+]
+
 :fn-pointer-invalid-value-indirection: pass:n[ \
 Among the invalid values for dereferencing a pointer by the unary *+*+* operator are a null pointer, an address inappropriately aligned for the type of object pointed to, and the address of an object after the end of its lifetime. \
 If *+*P+* is an l-value and *T* is the name of an object pointer type, *+*(T)P+* is an l-value that has a type compatible with that to which *T* points. \