C++ for OpenCL 2021 (i.e OpenCL 3.0-compatible) (#616)

Added a new version of C++ for OpenCL aligned with OpenCL 3
that makes the same feature optional.

The main summary of new content:
- Updated intro to explain the main concept of the new language
   version.
- Misc small updates to differences to C++ and OpenCL C sections.
- Added new predefined version macros.
- Updated address space section to detail the behavior without
   generic address space and program scope features.
- Changed section references and their format from OpenCL v2.0
   to OpenCL 3.0.

Co-authored-by: Marco Antognini <antognini.marco@gmail.com>
Co-authored-by: Justas Janickas <Justas.Janickas@arm.com>
Co-authored-by: Sven van Haastregt <sven.vanhaastregt@arm.com>

Author: 4 people

CXX_for_OpenCL.txt

@@ -2,7 +2,7 @@
 // Creative Commons Attribution 4.0 International License; see
 // http://creativecommons.org/licenses/by/4.0/
 
-= The C++ for OpenCL 1.0 Programming Language Documentation
+= The C++ for OpenCL 1.0 and 2021 Programming Language Documentation
 :R: pass:q,r[^(R)^]
 Khronos{R} OpenCL Working Group
 :data-uri:

cxx4opencl/address_spaces.txt

@@ -29,10 +29,10 @@ feature test macros.]
 Simultaneous initialization of static local objects performed by
 different work-items is not guaranteed to be free from race-conditions.
 Whether an implementation provides such a guarantee is indicated by the
-presence of the `__cpp_threadsafe_static_init` feature test
+presence of the `+__cpp_threadsafe_static_init+` feature test
 macro{fn-feature-macro}.
 
 The list above only contains extra restrictions that are not detailed in OpenCL
-C. As OpenCL restricts a number of C features, the same restrictions are
-inherited by C++ for OpenCL. The detailed list of C feature restrictions
-is provided in `OpenCL C v2.0 section 6.9`.
+C specification. As OpenCL restricts a number of C features, the same restrictions
+are inherited by C++ for OpenCL. The detailed list of C feature restrictions
+is provided in `OpenCL C 3.0 section 6.11`.

cxx4opencl/diff2cxx.txt

@@ -102,15 +102,15 @@ encouraged to define `NULL` as an alias to pointer literal `nullptr`.
 
 {cpp}17 does not support `restrict` and therefore {cpp} for OpenCL
 can not support it either. Some compilers might provide extensions
-with some functionality of `restrict` in {cpp}, e.g. `__restrict`
+with some functionality of `restrict` in {cpp}, e.g. `+__restrict+`
 in Clang.
 
 This feature only affects optimizations and the source
 code can be modified by removing it. As a workaround to avoid manual
 modifications, macro substitutions can be used to either remove the
 keyword during the preprocessing by defining `restrict` as an empty
 macro or mapping it to another similar compiler features, e.g.
-`__restrict` in Clang. This can be done in headers or using `-D`
+`+__restrict+` in Clang. This can be done in headers or using `-D`
 compilation flag.
 
 ===== Limitations of goto statements
@@ -136,7 +136,7 @@ The ternary selection operator (`?:`) inherits its behaviour from both
 `(exp1 ? exp2 : exp3)`. If all three expressions are scalar values,
 the {cpp}17 rules for ternary operator are followed. If the result is
 a vector value, then this is equivalent to calling
-`select(exp3, exp2, exp1)` as described in `OpenCL C v2.0 s6.13.6`.
+`select(exp3, exp2, exp1)` as described in `OpenCL C 3.0 s6.15.6`.
 The rules from OpenCL C impose limitation that `exp1` cannot be a
 vector of float values. However, `exp1` can be evaluated to a scalar
 float as it is contextually convertible to bool in {cpp}.
@@ -149,32 +149,39 @@ in OpenCL specific behavior.
 ===== Variadic macros
 
 {cpp} for OpenCL eliminates the restriction on variadic macros from
-`OpenCL C v2.0 s6.9.e`.
+`OpenCL C 3.0 s6.11.f`.
 Variadic macros can be used normally as per {cpp}17 `[cpp.replace]`.
 
 ===== Predefined macros
 
-The macro `+__OPENCL_C_VERSION__+` described in `OpenCL C v2.0 s6.10`,
+The macro `+__OPENCL_C_VERSION__+` described in `OpenCL C 3.0 s6.12`,
 is not defined.
 
 The following new predefined macros are added in {cpp} for OpenCL:
 
- * `+__OPENCL_CPP_VERSION__+` set to value `100`.
- * `+__CL_CPP_VERSION_1_0__+` also set to `100` and can be used for
+ * `+__OPENCL_CPP_VERSION__+` set to integer value reflecting the C++
+   for OpenCL version the translation unit is compiled for. The value
+   `100` corresponds to the language version 1.0 and `202100` corresponds
+   to the version 2021.
+ * `+__CL_CPP_VERSION_1_0__+` set to `100` and can be used for
+   convenience instead of a literal.
+ * `+__CL_CPP_VERSION_2021__+` set to `202100` and can be used for
    convenience instead of a literal.
 
 ===== Atomic operations
 
-{cpp} for OpenCL relaxes restriction from `OpenCL C v2.0 s6.13.11` to
+{cpp} for OpenCL relaxes restriction from `OpenCL C 3.0 s6.15.12` to
 atomic types allowing them to be used by builtin operators, and not
-only by builtin functions.
+only by builtin functions. This relaxation does not apply to
+{cpp} for OpenCL version 2021 if the sequential consistency memory model
+(i.e. `+__opencl_c_atomic_order_seq_cst+` feature) is not supported.
 
 Operators on atomic types behave as described in {cpp}17
 sections `[atomics.types.int]` `[atomics.types.pointer]`
 `[atomics.types.float]`.
-
 [source,c]
 ----------
+// Assumes support of sequential consistency memory model.
 atomic_int acnt;
 acnt++; // equivalent to atomic_fetch_add(&acnt, 1);
 ----------

cxx4opencl/diff2openclc.txt

@@ -5,45 +5,65 @@
 [[intro]]
 == Introduction
 
-This language is built on top of OpenCL C v2.0 and {cpp}17 enabling
+This language is built on top of OpenCL C 3.0 unified and {cpp}17 enabling
 most of regular {cpp} features in OpenCL kernel code. Most functionality
 from {cpp} and OpenCL C is inherited. Since both OpenCL C and {cpp} are
 derived from C and moreover {cpp} is almost fully backward compatible with C,
 the main design principle of {cpp} for OpenCL is to reapply existing OpenCL
 concepts to {cpp}. Therefore, it is important to refer to
-<<opencl-spec, The OpenCL Specification, Version 2.0>> `section
+<<opencl-spec, The OpenCL Specification, Version 3.0>> `section
 3.2` and `section 3.3` detailing fundamental differences of OpenCL execution
 and memory models from the conventional C and {cpp} view.
 
-This document describes the programming language in details. It is not
+This document describes the programming language in detail. It is not
 structured as a standalone document, but rather as an addition to OpenCL C
-v2.0 defined in <<openclc-spec, The OpenCL C Specification, Version 2.0>>
-and {cpp}17 defined in <<cpp17-spec, The C++17 Specification>>. Where necessary
-this document refers to the specifications of those languages accordingly.
-A full understanding of {cpp} for OpenCL requires familiarity with the
-specifications or other documentation of both languages that {cpp} for OpenCL
+3.0 unified specification defined in <<openclc-spec, The OpenCL C Specification,
+Version 3.0>> and {cpp}17 defined in <<cpp17-spec, The C++17 Specification>>.
+Where necessary this document refers to the specifications of those languages
+accordingly. A full understanding of {cpp} for OpenCL requires familiarity with
+the specifications or other documentation of both languages that {cpp} for OpenCL
 is built upon.
 
 The description of {cpp} for OpenCL starts from highlighting <<diff2openclc,
 _the differences to OpenCL C_>> and <<diff2cxx, _the differences to {cpp}_>>.
 
 The majority of content covers the behavior that is not documented in
-the OpenCL C v2.0 `section 6` and {cpp}17 specifications. This is mainly
+the `OpenCL C 3.0 s6` and {cpp}17 specifications. This is mainly
 related to interactions between OpenCL and {cpp} language features.
 
+This document describes C++ for OpenCL language
+
+ * version 1.0 that is backward compatible with OpenCL 2.0; and
+ * version 2021 that is backward compatible with OpenCL 3.0.
+
+== Version differences 
+
+The main difference between {cpp} for OpenCL version 1.0 and version 2021
+comes from the difference between OpenCL 2.0 and OpenCL 3.0 with which they
+are respectively compatible. Support for some features of {cpp} for OpenCL 1.0
+has become optional as described in `OpenCL 3.0 s6.2.1`. Predefined feature
+macros from OpenCL C 3.0 can be used to detect which optional features are present.
+
+This impacts some C++ specific semantics mainly due to optionality of the
+generic address space (i.e. `+__opencl_c_generic_address_space+` feature) or
+program scope variables (i.e. `+__opencl_c_program_scope_global_variables+`
+feature).
+
 == The {cpp} for OpenCL Programming Language 
 
-This programming language inherits features from `OpenCL C v2.0,
-s6` as well as {cpp}17. Detailed aspects of OpenCL and {cpp} are not
-described in this document as they can be found in their official
-specifications.
+This programming language inherits features from `OpenCL C 3.0 s6` as well
+as {cpp}17. Detailed aspects of OpenCL and {cpp} are not described in this
+document as they can be found in their official specifications.
 
 This section documents various language features of {cpp} for OpenCL that are
-not covered in either OpenCL or {cpp} specifications, in particular:
+not covered in neither OpenCL nor {cpp} specifications, in particular:
 
  * any behavior that deviates from {cpp}17;
- * any behavior that deviates from OpenCL C v2.0;
+ * any behavior that deviates from OpenCL C 2.0 or 3.0;
  * any behavior that is not governed by OpenCL C and {cpp}.
 
-All language extensions to OpenCL C v2.0 or earlier are applicable to
-C++ for OpenCL.
+All language extensions to OpenCL C are applicable to C++ for OpenCL.
+ * Extensions to OpenCL C 2.0 or earlier versions apply to C++ for OpenCL
+   version 1.0.
+ * Extensions to OpenCL 3.0 or earlier versions except for OpenCL 2.0, apply to
+   C++ for OpenCL 2021.

cxx4opencl/intro.txt

@@ -24,5 +24,4 @@ Moreover the types used in parameters of the kernel functions must be:
     references{fn-ker-par-ref} if an implementation supports them in kernel
     parameters.
 
-These are additional restrictions to the list detailed in `OpenCL C v2.0
-section 6.9`.
+These are additional restrictions to the list detailed in `OpenCL C 3.0 s6.11`.

cxx4opencl/kernel.txt

@@ -4,9 +4,9 @@
 
 == Normative References
 
-   . [[opencl-spec]] "`The OpenCL Specification, Version 2.0`",
+   . [[opencl-spec]] "`The OpenCL Specification, Version 3.0`",
      https://www.khronos.org/registry/OpenCL/.
-   . [[openclc-spec]] "`The OpenCL C Specification, Version 2.0`",
+   . [[openclc-spec]] "`The OpenCL C Specification, Version 3.0`",
      https://www.khronos.org/registry/OpenCL/.
    . [[cpp17-spec]] "`ISO/IEC 14882:2017 - Programming languages — {CPP}`",
      https://www.iso.org/standard/68564.html.