[PATCH] D64418: [Docs][OpenCL] Documentation of C++ for OpenCL mode

[Phabricator via Phabricator via cfe-commits]

This revision was automatically updated to reflect the committed changes.
Closed by commit rL369749: [Docs][OpenCL] Several corrections to C++ for OpenCL 
(authored by stulova, committed by ).

Changed prior to commit:
  https://reviews.llvm.org/D64418?vs=215922=216808#toc

Repository:
  rL LLVM

CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D64418/new/

https://reviews.llvm.org/D64418

Files:
  cfe/trunk/docs/LanguageExtensions.rst
  cfe/trunk/docs/UsersManual.rst

Index: cfe/trunk/docs/LanguageExtensions.rst
===
--- cfe/trunk/docs/LanguageExtensions.rst
+++ cfe/trunk/docs/LanguageExtensions.rst
@@ -1640,8 +1640,8 @@
 C++ for OpenCL
 --
 
-This functionality is built on top of OpenCL C v2.0 and C++17. Regular C++
-features can be used in OpenCL kernel code. All functionality from OpenCL C
+This functionality is built on top of OpenCL C v2.0 and C++17 enabling most of
+regular C++ features in OpenCL kernel code. Most functionality from OpenCL C
 is inherited. This section describes minor differences to OpenCL C and any
 limitations related to C++ support as well as interactions between OpenCL and
 C++ features that are not documented elsewhere.
@@ -1652,6 +1652,7 @@
 The following features are not supported:
 
 - Virtual functions
+- Exceptions
 - ``dynamic_cast`` operator
 - Non-placement ``new``/``delete`` operators
 - Standard C++ libraries. Currently there is no solution for alternative C++
@@ -1667,20 +1668,24 @@
 Address spaces are part of the type qualifiers; many rules are just inherited
 from the qualifier behavior documented in OpenCL C v2.0 s6.5 and Embedded C
 extension ISO/IEC JTC1 SC22 WG14 N1021 s3.1. Note that since the address space
-behavior in C++ is not documented formally yet, Clang extends existing concept
+behavior in C++ is not documented formally, Clang extends the existing concept
 from C and OpenCL. For example conversion rules are extended from qualification
-conversion but the compatibility is determined using sets and overlapping from
-Embedded C (ISO/IEC JTC1 SC22 WG14 N1021 s3.1.3). For OpenCL it means that
-implicit conversions are allowed from named to ``__generic`` but not vice versa
-(OpenCL C v2.0 s6.5.5) except for ``__constant`` address space. Most of the
-rules are built on top of this behavior.
+conversion but the compatibility is determined using notation of sets and
+overlapping of address spaces from Embedded C (ISO/IEC JTC1 SC22 WG14 N1021
+s3.1.3). For OpenCL it means that implicit conversions are allowed from
+a named address space (except for ``__constant``) to ``__generic`` (OpenCL C
+v2.0 6.5.5). Reverse conversion is only allowed explicitly. The ``__constant``
+address space does not overlap with any other and therefore no valid conversion
+between ``__constant`` and other address spaces exists. Most of the rules
+follow this logic.
 
 **Casts**
 
-C style cast will follow OpenCL C v2.0 rules (s6.5.5). All cast operators will
-permit implicit conversion to ``__generic``. However converting from named
-address spaces to ``__generic`` can only be done using ``addrspace_cast``. Note
-that conversions between ``__constant`` and any other is still disallowed.
+C-style casts follow OpenCL C v2.0 rules (s6.5.5). All cast operators
+permit conversion to ``__generic`` implicitly. However converting from
+``__generic`` to named address spaces can only be done using ``addrspace_cast``.
+Note that conversions between ``__constant`` and any other address space
+are disallowed.
 
 .. _opencl_cpp_addrsp_deduction:
 
@@ -1693,7 +1698,7 @@
 - non-pointer/non-reference class members except for static data members that are
   deduced to ``__global`` address space.
 - non-pointer/non-reference alias declarations.
-- ``decltype`` expression.
+- ``decltype`` expressions.
 
 .. code-block:: c++
 
@@ -1722,7 +1727,7 @@
 
 **References**
 
-References types can be qualified with an address space.
+Reference types can be qualified with an address space.
 
 .. code-block:: c++
 
@@ -1737,29 +1742,29 @@
 **Default address space**
 
 All non-static member functions take an implicit object parameter ``this`` that
-is a pointer type. By default this pointer parameter is in ``__generic`` address
-space. All concrete objects passed as an argument to ``this`` parameter will be
-converted to ``__generic`` address space first if the conversion is valid.
-Therefore programs using objects in ``__constant`` address space won't be compiled
-unless address space is explicitly specified using address space qualifiers on
-member functions
+is a pointer type. By default this pointer parameter is in the ``__generic``
+address space. All concrete objects passed as an argument to ``this`` parameter
+will be converted to the ``__generic`` address space first if such conversion is
+valid. Therefore programs using objects in the ``__constant`` address space will
+not be compiled unless the address space is explicitly 

[PATCH] D64418: [Docs][OpenCL] Documentation of C++ for OpenCL mode

[Sven van Haastregt via Phabricator via cfe-commits]

svenvh accepted this revision.
svenvh added a comment.

LGTM!


CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D64418/new/

https://reviews.llvm.org/D64418



___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[PATCH] D64418: [Docs][OpenCL] Documentation of C++ for OpenCL mode

[Anastasia Stulova via Phabricator via cfe-commits]

Anastasia updated this revision to Diff 215922.
Anastasia added a comment.

Added small corrections in various parts.


CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D64418/new/

https://reviews.llvm.org/D64418

Files:
  docs/LanguageExtensions.rst
  docs/UsersManual.rst

Index: docs/UsersManual.rst
===
--- docs/UsersManual.rst
+++ docs/UsersManual.rst
@@ -2397,7 +2408,8 @@
 This will produce a generic test.bc file that can be used in vendor toolchains
 to perform machine code generation.
 
-Clang currently supports OpenCL C language standards up to v2.0.
+Clang currently supports OpenCL C language standards up to v2.0. Starting from
+clang 9 a C++ mode is available for OpenCL (see :ref:`C++ for OpenCL `).
 
 OpenCL Specific Options
 ---
@@ -2756,6 +2768,46 @@
   enqueue query functions from `section 6.13.17.5
   `_.
 
+.. _opencl_cpp:
+
+C++ for OpenCL
+--
+
+Starting from clang 9 kernel code can contain C++17 features: classes, templates,
+function overloading, type deduction, etc. Please note that this is not an
+implementation of `OpenCL C++
+`_ and
+there is no plan to support it in clang in any new releases in the near future.
+
+For detailed information about restrictions to allowed C++ features please
+refer to :doc:`LanguageExtensions`.
+
+Since C++ features are to be used on top of OpenCL C functionality, all existing
+restrictions from OpenCL C v2.0 will inherently apply. All OpenCL C builtin types
+and function libraries are supported and can be used in this mode.
+
+To enable the C++ for OpenCL mode, pass one of following command line options when
+compiling ``.cl`` file ``-cl-std=clc++``, ``-cl-std=CLC++``, ``-std=clc++`` or
+``-std=CLC++``.
+
+   .. code-block:: c++
+
+ template T add( T x, T y )
+ {
+   return x + y;
+ }
+
+ __kernel void test( __global float* a, __global float* b)
+ {
+   auto index = get_global_id(0);
+   a[index] = add(b[index], b[index+1]);
+ }
+
+
+   .. code-block:: console
+
+ clang -cl-std=clc++ test.cl
+
 .. _target_features:
 
 Target-Specific Features and Limitations
Index: docs/LanguageExtensions.rst
===
--- docs/LanguageExtensions.rst
+++ docs/LanguageExtensions.rst
@@ -1516,6 +1633,285 @@
 Query the presence of this new mangling with
 ``__has_feature(objc_protocol_qualifier_mangling)``.
 
+
+OpenCL Features
+===
+
+C++ for OpenCL
+--
+
+This functionality is built on top of OpenCL C v2.0 and C++17 enabling most of
+regular C++ features in OpenCL kernel code. Most functionality from OpenCL C
+is inherited. This section describes minor differences to OpenCL C and any
+limitations related to C++ support as well as interactions between OpenCL and
+C++ features that are not documented elsewhere.
+
+Restrictions to C++17
+^
+
+The following features are not supported:
+
+- Virtual functions
+- Exceptions
+- ``dynamic_cast`` operator
+- Non-placement ``new``/``delete`` operators
+- Standard C++ libraries. Currently there is no solution for alternative C++
+  libraries provided. Future release will feature library support.
+
+
+Interplay of OpenCL and C++ features
+
+
+Address space behavior
+""
+
+Address spaces are part of the type qualifiers; many rules are just inherited
+from the qualifier behavior documented in OpenCL C v2.0 s6.5 and Embedded C
+extension ISO/IEC JTC1 SC22 WG14 N1021 s3.1. Note that since the address space
+behavior in C++ is not documented formally, Clang extends the existing concept
+from C and OpenCL. For example conversion rules are extended from qualification
+conversion but the compatibility is determined using notation of sets and
+overlapping of address spaces from Embedded C (ISO/IEC JTC1 SC22 WG14 N1021
+s3.1.3). For OpenCL it means that implicit conversions are allowed from
+a named address space (except for ``__constant``) to ``__generic`` (OpenCL C
+v2.0 6.5.5). Reverse conversion is only allowed explicitly. The ``__constant``
+address space does not overlap with any other and therefore no valid conversion
+between ``__constant`` and other address spaces exists. Most of the rules
+follow this logic.
+
+**Casts**
+
+C-style casts follow OpenCL C v2.0 rules (s6.5.5). All cast operators
+permit conversion to ``__generic`` implicitly. However converting from
+``__generic`` to named address spaces can only be done using ``addrspace_cast``.
+Note that conversions between ``__constant`` and any other address space
+are disallowed.
+
+.. _opencl_cpp_addrsp_deduction:
+
+**Deduction**
+
+Address spaces are not deduced for:
+
+- non-pointer/non-reference template parameters or any dependent types except

[PATCH] D64418: [Docs][OpenCL] Documentation of C++ for OpenCL mode

[Anastasia Stulova via Phabricator via cfe-commits]

Anastasia updated this revision to Diff 215562.
Anastasia marked an inline comment as done and 2 inline comments as not done.
Anastasia added a comment.

- Addressed comments from Sven.


CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D64418/new/

https://reviews.llvm.org/D64418

Files:
  docs/LanguageExtensions.rst
  docs/UsersManual.rst

Index: docs/UsersManual.rst
===
--- docs/UsersManual.rst
+++ docs/UsersManual.rst
@@ -2397,7 +2408,8 @@
 This will produce a generic test.bc file that can be used in vendor toolchains
 to perform machine code generation.
 
-Clang currently supports OpenCL C language standards up to v2.0.
+Clang currently supports OpenCL C language standards up to v2.0. Starting from
+clang 9 a C++ mode is available for OpenCL (see :ref:`C++ for OpenCL `).
 
 OpenCL Specific Options
 ---
@@ -2756,6 +2768,46 @@
   enqueue query functions from `section 6.13.17.5
   `_.
 
+.. _opencl_cpp:
+
+C++ for OpenCL
+--
+
+Starting from clang 9 kernel code can contain C++17 features: classes, templates,
+function overloading, type deduction, etc. Please note that this is not an
+implementation of `OpenCL C++
+`_ and
+there is no plan to support it in clang in any new releases in the near future.
+
+For detailed information about restrictions to allowed C++ features please
+refer to :doc:`LanguageExtensions`.
+
+Since C++ features are to be used on top of OpenCL C functionality, all existing
+restrictions from OpenCL C v2.0 will inherently apply. All OpenCL C builtin types
+and function libraries are supported and can be used in this mode.
+
+To enable the C++ for OpenCL mode, pass one of following command line options when
+compiling ``.cl`` file ``-cl-std=clc++``, ``-cl-std=CLC++``, ``-std=clc++`` or
+``-std=CLC++``.
+
+   .. code-block:: c++
+
+ template T add( T x, T y )
+ {
+   return x + y;
+ }
+
+ __kernel void test( __global float* a, __global float* b)
+ {
+   auto index = get_global_id(0);
+   a[index] = add(b[index], b[index+1]);
+ }
+
+
+   .. code-block:: console
+
+ clang -cl-std=clc++ test.cl
+
 .. _target_features:
 
 Target-Specific Features and Limitations
Index: docs/LanguageExtensions.rst
===
--- docs/LanguageExtensions.rst
+++ docs/LanguageExtensions.rst
@@ -1516,6 +1633,284 @@
 Query the presence of this new mangling with
 ``__has_feature(objc_protocol_qualifier_mangling)``.
 
+
+OpenCL Features
+===
+
+C++ for OpenCL
+--
+
+This functionality is built on top of OpenCL C v2.0 and C++17 enabling most of
+regular C++ features in OpenCL kernel code. Most functionality from OpenCL C
+is inherited. This section describes minor differences to OpenCL C and any
+limitations related to C++ support as well as interactions between OpenCL and
+C++ features that are not documented elsewhere.
+
+Restrictions to C++17
+^
+
+The following features are not supported:
+
+- Virtual functions
+- Exceptions
+- ``dynamic_cast`` operator
+- Non-placement ``new``/``delete`` operators
+- Standard C++ libraries. Currently there is no solution for alternative C++
+  libraries provided. Future release will feature library support.
+
+
+Interplay of OpenCL and C++ features
+
+
+Address space behavior
+""
+
+Address spaces are part of the type qualifiers; many rules are just inherited
+from the qualifier behavior documented in OpenCL C v2.0 s6.5 and Embedded C
+extension ISO/IEC JTC1 SC22 WG14 N1021 s3.1. Note that since the address space
+behavior in C++ is not documented formally, Clang extends existing concept
+from C and OpenCL. For example conversion rules are extended from qualification
+conversion but the compatibility is determined using notation of sets and
+overlapping of address spaces from Embedded C (ISO/IEC JTC1 SC22 WG14 N1021
+s3.1.3). For OpenCL it means that implicit conversions are allowed from
+a named address space (except for ``__constant``) to ``__generic`` (OpenCL C
+v2.0 6.5.5). Reverse conversion is only allowed explicitly. The ``__constant``
+address space does not overlap with any other and therefore no valid conversion
+between ``__constant`` and other address spaces exists. Most of the rules
+follow this logic.
+
+**Casts**
+
+C-style cast will follow OpenCL C v2.0 rules (s6.5.5). All cast operators will
+permit conversion to ``__generic`` implicitly. However converting from
+``__generic`` to named address spaces can only be done using ``addrspace_cast``.
+Note that conversions between ``__constant`` and any other is disallowed.
+
+.. _opencl_cpp_addrsp_deduction:
+
+**Deduction**
+
+Address spaces are not deduced for:
+
+- 

[PATCH] D64418: [Docs][OpenCL] Documentation of C++ for OpenCL mode

[Anastasia Stulova via Phabricator via cfe-commits]

Anastasia added inline comments.



Comment at: docs/UsersManual.rst:2771
+
+There are only a few restrictions on allowed C++ features. For detailed 
information
+please refer to documentation on Extensions (:doc:`LanguageExtensions`).

svenvh wrote:
> Anastasia wrote:
> > kpet wrote:
> > > Everything is relative. I would keep this 100% factual: "there are 
> > > restrictions". This is not a sales pitch :).
> > I think it's fair to say few restrictions because the majority of C++ just 
> > works in OpenCL.
> I agree with @kpet and also prefer "There are restrictions" instead of an 
> unquantified statement.
Ok, I don't understand what value does it bring to make information less 
specific but potentially it's not important enough to continue the argument. 
The idea of this sentence was indeed to point out that the mode is just very 
close to C++ with very few restrictions. This isn't a program so it can't have 
a formal definition for every statement. :P


CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D64418/new/

https://reviews.llvm.org/D64418



___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[PATCH] D64418: [Docs][OpenCL] Documentation of C++ for OpenCL mode

[Sven van Haastregt via Phabricator via cfe-commits]

svenvh added inline comments.



Comment at: docs/LanguageExtensions.rst:1561
+s3.1.3). For OpenCL it means that implicit conversions are allowed from
+named address space except for ``__constant`` to ``__generic`` address space
+that is a superset of all others except for ``__constant`` (OpenCL C v2.0

"For OpenCL it means that implicit conversions are allowed from a ​named 
address space except for conversion from the ``__constant`` to the 
``__generic`` address space."

I would omit "that is a superset of all others except for ``__constant``" as 
that is already documented in the OpenCL spec and it might confuse readers 
here.  If you want to keep it, I suggest rephrasing it as a separate sentence.



Comment at: docs/LanguageExtensions.rst:1563
+that is a superset of all others except for ``__constant`` (OpenCL C v2.0
+s6.5.5). Reverse conversion is only allowed explicitly.  ``__constant``
+address space does not overlap with any other and therefore no valid conversion

+The+ ``__constant`` address space



Comment at: docs/LanguageExtensions.rst:1570
+
+C style cast will follow OpenCL C v2.0 rules (s6.5.5). All cast operators will
+permit conversion to ``__generic`` implicitly. However converting from

"C-style casts follow"



Comment at: docs/LanguageExtensions.rst:1630
+All non-static member functions take an implicit object parameter ``this`` that
+is a pointer type. By default this pointer parameter is in ``__generic`` 
address
+space. All concrete objects passed as an argument to ``this`` parameter will be

+the+ ``__generic`` address space

(also in the next few lines)



Comment at: docs/LanguageExtensions.rst:1647
+
+Clang allows specifying address space qualifier on member functions to signal 
that
+they are to be used with objects constructed in some specific address space. 
This

+an+ address space qualifier



Comment at: docs/LanguageExtensions.rst:1650
+works just the same as qualifying member functions with ``const`` or any other
+qualifiers. The overloading resolution will select ithe overload with most 
specific
+address space if multiple candidates are provided. If there is no conversion to

ithe -> the



Comment at: docs/LanguageExtensions.rst:1651
+qualifiers. The overloading resolution will select ithe overload with most 
specific
+address space if multiple candidates are provided. If there is no conversion to
+to an address space among existing overloads compilation will fail with a

Duplicate "to" (to to)



Comment at: docs/LanguageExtensions.rst:1652
+address space if multiple candidates are provided. If there is no conversion to
+to an address space among existing overloads compilation will fail with a
+diagnostic.

Add comma:
... overloads, compilation ...



Comment at: docs/LanguageExtensions.rst:1715
+definition and instantiation. If multiple different address spaces are 
specified in
+template definition and instantiation compilation of such a program will fail 
with a
+diagnostic.

Add comma:
... instantiation, compilation ...



Comment at: docs/LanguageExtensions.rst:1730
+
+Once template is instantiated regular restrictions for address spaces will 
apply.
+

Once a template has been instantiated, regular restrictions for address spaces 
will apply.



Comment at: docs/LanguageExtensions.rst:1746
+
+All temporaries are materialized in ``__private`` address space. If a reference
+with some other address space is bound to them, the conversion will be 
generated

the ``__private`` address space



Comment at: docs/LanguageExtensions.rst:1747
+All temporaries are materialized in ``__private`` address space. If a reference
+with some other address space is bound to them, the conversion will be 
generated
+in case it's valid otherwise compilation will fail with a diagnostic.

some other -> another



Comment at: docs/LanguageExtensions.rst:1748
+with some other address space is bound to them, the conversion will be 
generated
+in case it's valid otherwise compilation will fail with a diagnostic.
+

it's -> it is

add comma:
... valid, otherwise ...



Comment at: docs/LanguageExtensions.rst:1776
+API for invoking global constructors. However, an easy workaround would be
+to enqueue constructor initialization kernel that has a name
+``@_GLOBAL__sub_I_``. This kernel is only present if there

enqueue *a* constructor



Comment at: docs/LanguageExtensions.rst:1782
+
+Note that if multiple files are compiled and linked into libraries multiple
+kernels that initialize global objects for multiple modules would have to be

[PATCH] D64418: [Docs][OpenCL] Documentation of C++ for OpenCL mode

[Anastasia Stulova via Phabricator via cfe-commits]

Anastasia marked 12 inline comments as done and 2 inline comments as done.
Anastasia added inline comments.



Comment at: docs/LanguageExtensions.rst:327
 
+.. _languageextensions-builtin-macros:
+

FYI, this is not part of my change. It was just hard to produce combined diff.



Comment at: docs/LanguageExtensions.rst:1541
+- Standard C++ libraries. Currently there is no solution for alternative C++
+  libraries provided. Future release will feature library support.
+

kpet wrote:
> I would remove this last sentence. Only a very small portion of the libray 
> can be supported anyway.
I think it's valuable especially for metaprogramming. I was being asked about 
it.



Comment at: docs/LanguageExtensions.rst:1553
+extension ISO/IEC JTC1 SC22 WG14 N1021 s3.1. Note that since the address space
+behavior in C++ is not documented formally yet, Clang extends existing concept
+from C and OpenCL. For example conversion rules are extended from qualification

kpet wrote:
> kpet wrote:
> > I would remove the "yet", unless we can refer to an on-going and visible 
> > effort.
> "Clang extends existing concept" feels like it should be re-worded.
I need to understand what needs re-wording



Comment at: docs/LanguageExtensions.rst:1557
+Embedded C (ISO/IEC JTC1 SC22 WG14 N1021 s3.1.3). For OpenCL it means that
+implicit conversions are allowed from named to ``__generic`` but not vice versa
+(OpenCL C v2.0 s6.5.5) except for ``__constant`` address space. Most of the

kpet wrote:
> Why use `__generic` when `generic` is equally valid and easier on the eyes? 
> The same comment applies to other mentions of address space keywords.
I prefer to use `__` for two reasons (1) it's more official in OpenCL docs and 
tutorials (2) I sometimes omit the noun and just use it as a short term in the 
text.



Comment at: docs/LanguageExtensions.rst:1564
+C style cast will follow OpenCL C v2.0 rules (s6.5.5). All cast operators will
+permit implicit conversion to ``__generic``. However converting from named
+address spaces to ``__generic`` can only be done using ``addrspace_cast``. Note

kpet wrote:
> Isn't a conversion explicit if a cast operator is used?
It's complicated to explain but basically some cast operators perform implicit 
conversions of what they are not expected to do because implicit conversions 
are allowed everywhere even if the operator isn't intended to do the conversion 
explicitly.

Similar example in C++, most of operators accept converting to `const` objects.




Comment at: docs/LanguageExtensions.rst:1565
+permit implicit conversion to ``__generic``. However converting from named
+address spaces to ``__generic`` can only be done using ``addrspace_cast``. Note
+that conversions between ``__constant`` and any other is still disallowed.

kpet wrote:
> kpet wrote:
> > At the time of writing `addrspace_cast` doesn't seem to exist in trunk and 
> > C-style casts seem to work.
> Didn't you mean "from `__generic` to named address spaces"?
> At the time of writing addrspace_cast doesn't seem to exist in trunk and 
> C-style casts seem to work.

I think it's ok to document full extension even if it's WIP.



Comment at: docs/LanguageExtensions.rst:1577
+- non-pointer/non-reference class members except for static data members that 
are
+  deduced to ``__global`` address space.
+- non-pointer/non-reference alias declarations.

kpet wrote:
> Makes me wonder whether const members couldn't be in the `constant` address 
> space.
No `constant` specify memory region but `const` indicates that object is not 
changed during lifetime. You can cast away `const` but you can't convert 
`constant` object to any other address space.



Comment at: docs/LanguageExtensions.rst:1761
+program objects is executed. In OpenCL v2.0 drivers there is no specific
+API for invoking global constructors. However, an easy workaround would be
+to enqueue constructor initialization kernel that has a name

kpet wrote:
> OpenCL doesn't have an API for this per-se, regardless of the version. The 
> only mechanism currently specified is the SPIR-V `Initializer` and 
> `Finalizer` execution modes for entrypoints, either of which currently 
> require an OpenCL 2.2 implementation.
Not sure whether you imply any action here.



Comment at: docs/LanguageExtensions.rst:1779
+
+Global destructors can not be invoked in OpenCL v2.0 drivers. However, all
+memory used for program scope objects is released on ``clReleaseProgram``.

kpet wrote:
> This could be managed by the application with a scheme similar to the one 
> you're proposing for constructor functions.
The Itanium C++ ABIs for destructors are different and we haven't got it 
working yet for OpenCL. I would leave the 

[PATCH] D64418: [Docs][OpenCL] Documentation of C++ for OpenCL mode

[Anastasia Stulova via Phabricator via cfe-commits]

Anastasia updated this revision to Diff 215106.
Anastasia marked 26 inline comments as done.
Anastasia added a comment.

Addressed various comments from Kevin.


CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D64418/new/

https://reviews.llvm.org/D64418

Files:
  docs/LanguageExtensions.rst
  docs/UsersManual.rst

Index: docs/UsersManual.rst
===
--- docs/UsersManual.rst
+++ docs/UsersManual.rst
@@ -2397,7 +2397,8 @@
 This will produce a generic test.bc file that can be used in vendor toolchains
 to perform machine code generation.
 
-Clang currently supports OpenCL C language standards up to v2.0.
+Clang currently supports OpenCL C language standards up to v2.0. Starting from
+Clang 9 a C++ mode is available for OpenCL (see :ref:`C++ for OpenCL `).
 
 OpenCL Specific Options
 ---
@@ -2756,6 +2757,45 @@
   enqueue query functions from `section 6.13.17.5
   `_.
 
+.. _opencl_cpp:
+
+C++ for OpenCL
+--
+
+Starting from Clang9 kernel code can contain C++17 features: classes, templates,
+function overloading, type deduction, etc. Please note that this is not an
+implementation of `OpenCL C++
+`_ and
+there is no plan to support it in clang in any new releases in the near future.
+
+There are only a few restrictions on allowed C++ features. For detailed information
+please refer to documentation on Extensions (:doc:`LanguageExtensions`).
+
+Since C++ features are to be used on top of OpenCL C functionality, all existing
+restrictions from OpenCL C v2.0 will inherently apply. All OpenCL C builtin types
+and function libraries are supported and can be used in the new mode.
+
+To enable the new mode pass the following command line option when compiling ``.cl``
+file ``-cl-std=clc++``, ``-cl-std=CLC++``, ``-std=clc++`` or ``-std=CLC++``.
+
+   .. code-block:: c++
+
+ template T add( T x, T y )
+ {
+   return x + y;
+ }
+
+ __kernel void test( __global float* a, __global float* b)
+ {
+   auto index = get_global_id(0);
+   a[index] = add(b[index], b[index+1]);
+ }
+
+
+   .. code-block:: console
+
+ clang -cl-std=clc++ test.cl
+
 .. _target_features:
 
 Target-Specific Features and Limitations
Index: docs/LanguageExtensions.rst
===
--- docs/LanguageExtensions.rst
+++ docs/LanguageExtensions.rst
@@ -324,6 +324,8 @@
   ...
   #endif
 
+.. _languageextensions-builtin-macros:
+
 Builtin Macros
 ==
 
@@ -1516,6 +1518,284 @@
 Query the presence of this new mangling with
 ``__has_feature(objc_protocol_qualifier_mangling)``.
 
+
+OpenCL Features
+===
+
+C++ for OpenCL
+--
+
+This functionality is built on top of OpenCL C v2.0 and C++17 enabling most of
+regular C++ features in OpenCL kernel code. Most functionality from OpenCL C
+is inherited. This section describes minor differences to OpenCL C and any
+limitations related to C++ support as well as interactions between OpenCL and
+C++ features that are not documented elsewhere.
+
+Restrictions to C++17
+^
+
+The following features are not supported:
+
+- Virtual functions
+- Exceptions
+- ``dynamic_cast`` operator
+- Non-placement ``new``/``delete`` operators
+- Standard C++ libraries. Currently there is no solution for alternative C++
+  libraries provided. Future release will feature library support.
+
+
+Interplay of OpenCL and C++ features
+
+
+Address space behavior
+""
+
+Address spaces are part of the type qualifiers; many rules are just inherited
+from the qualifier behavior documented in OpenCL C v2.0 s6.5 and Embedded C
+extension ISO/IEC JTC1 SC22 WG14 N1021 s3.1. Note that since the address space
+behavior in C++ is not documented formally, Clang extends existing concept
+from C and OpenCL. For example conversion rules are extended from qualification
+conversion but the compatibility is determined using notation of sets and
+overlapping of address spaces from Embedded C (ISO/IEC JTC1 SC22 WG14 N1021
+s3.1.3). For OpenCL it means that implicit conversions are allowed from
+named address space except for ``__constant`` to ``__generic`` address space
+that is a superset of all others except for ``__constant`` (OpenCL C v2.0
+s6.5.5). Reverse conversion is only allowed explicitly.  ``__constant``
+address space does not overlap with any other and therefore no valid conversion
+between ``__constant`` and other address spaces exists. Most of the rules
+follow this logic.
+
+**Casts**
+
+C style cast will follow OpenCL C v2.0 rules (s6.5.5). All cast operators will
+permit conversion to ``__generic`` implicitly. However converting from
+``__generic`` to named address spaces can only be done using ``addrspace_cast``.

[PATCH] D64418: [Docs][OpenCL] Documentation of C++ for OpenCL mode

[Anastasia Stulova via Phabricator via cfe-commits]

Anastasia reopened this revision.
Anastasia added a comment.
This revision is now accepted and ready to land.

Reopening to continue reviews.


Repository:
  rL LLVM

CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D64418/new/

https://reviews.llvm.org/D64418



___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[PATCH] D64418: [Docs][OpenCL] Documentation of C++ for OpenCL mode

[Phabricator via Phabricator via cfe-commits]

This revision was automatically updated to reflect the committed changes.
Closed by commit rL366351: [Docs][OpenCL] Documentation of C++ for OpenCL mode 
(authored by stulova, committed by ).
Herald added a project: LLVM.
Herald added a subscriber: llvm-commits.

Changed prior to commit:
  https://reviews.llvm.org/D64418?vs=210101=210362#toc

Repository:
  rL LLVM

CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D64418/new/

https://reviews.llvm.org/D64418

Files:
  cfe/trunk/docs/LanguageExtensions.rst
  cfe/trunk/docs/UsersManual.rst

Index: cfe/trunk/docs/LanguageExtensions.rst
===
--- cfe/trunk/docs/LanguageExtensions.rst
+++ cfe/trunk/docs/LanguageExtensions.rst
@@ -1518,6 +1518,275 @@
 Query the presence of this new mangling with
 ``__has_feature(objc_protocol_qualifier_mangling)``.
 
+
+OpenCL Features
+===
+
+C++ for OpenCL
+--
+
+This functionality is built on top of OpenCL C v2.0 and C++17. Regular C++
+features can be used in OpenCL kernel code. All functionality from OpenCL C
+is inherited. This section describes minor differences to OpenCL C and any
+limitations related to C++ support as well as interactions between OpenCL and
+C++ features that are not documented elsewhere.
+
+Restrictions to C++17
+^
+
+The following features are not supported:
+
+- Virtual functions
+- ``dynamic_cast`` operator
+- Non-placement ``new``/``delete`` operators
+- Standard C++ libraries. Currently there is no solution for alternative C++
+  libraries provided. Future release will feature library support.
+
+
+Interplay of OpenCL and C++ features
+
+
+Address space behavior
+""
+
+Address spaces are part of the type qualifiers; many rules are just inherited
+from the qualifier behavior documented in OpenCL C v2.0 s6.5 and Embedded C
+extension ISO/IEC JTC1 SC22 WG14 N1021 s3.1. Note that since the address space
+behavior in C++ is not documented formally yet, Clang extends existing concept
+from C and OpenCL. For example conversion rules are extended from qualification
+conversion but the compatibility is determined using sets and overlapping from
+Embedded C (ISO/IEC JTC1 SC22 WG14 N1021 s3.1.3). For OpenCL it means that
+implicit conversions are allowed from named to ``__generic`` but not vice versa
+(OpenCL C v2.0 s6.5.5) except for ``__constant`` address space. Most of the
+rules are built on top of this behavior.
+
+**Casts**
+
+C style cast will follow OpenCL C v2.0 rules (s6.5.5). All cast operators will
+permit implicit conversion to ``__generic``. However converting from named
+address spaces to ``__generic`` can only be done using ``addrspace_cast``. Note
+that conversions between ``__constant`` and any other is still disallowed.
+
+.. _opencl_cpp_addrsp_deduction:
+
+**Deduction**
+
+Address spaces are not deduced for:
+
+- non-pointer/non-reference template parameters or any dependent types except
+  for template specializations.
+- non-pointer/non-reference class members except for static data members that are
+  deduced to ``__global`` address space.
+- non-pointer/non-reference alias declarations.
+- ``decltype`` expression.
+
+.. code-block:: c++
+
+  template 
+  void foo() {
+T m; // address space of m will be known at template instantiation time.
+T * ptr; // ptr points to __generic address space object.
+T & ref = ...; // ref references an object in __generic address space.
+  };
+
+  template 
+  struct S {
+int i; // i has no address space
+static int ii; // ii is in global address space
+int * ptr; // ptr points to __generic address space int.
+int & ref = ...; // ref references int in __generic address space.
+  };
+
+  template 
+  void bar()
+  {
+S s; // s is in __private address space
+  }
+
+TODO: Add example for type alias and decltype!
+
+**References**
+
+References types can be qualified with an address space.
+
+.. code-block:: c++
+
+  __private int & ref = ...; // references int in __private address space
+
+By default references will refer to ``__generic`` address space objects, except
+for dependent types that are not template specializations
+(see :ref:`Deduction `). Address space compatibility
+checks are performed when references are bound to values. The logic follows the
+rules from address space pointer conversion (OpenCL v2.0 s6.5.5).
+
+**Default address space**
+
+All non-static member functions take an implicit object parameter ``this`` that
+is a pointer type. By default this pointer parameter is in ``__generic`` address
+space. All concrete objects passed as an argument to ``this`` parameter will be
+converted to ``__generic`` address space first if the conversion is valid.
+Therefore programs using objects in ``__constant`` address space won't be compiled
+unless address space is explicitly specified using address space qualifiers on
+member functions
+(see 

[PATCH] D64418: [Docs][OpenCL] Documentation of C++ for OpenCL mode

[Kévin Petit via Phabricator via cfe-commits]

kpet accepted this revision.
kpet added a comment.
This revision is now accepted and ready to land.

> Would it be ok if I fix those in a separate commit? I would really like to 
> commit the core part before the release branch is taken.

I'm fine with this as long as we can continue the discussion for open comments 
in this review. Accepting the revision as I don't seem to be able to go back on 
my request for another patch.


CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D64418/new/

https://reviews.llvm.org/D64418



___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[PATCH] D64418: [Docs][OpenCL] Documentation of C++ for OpenCL mode

[Anastasia Stulova via Phabricator via cfe-commits]

Anastasia added a comment.

In D64418#1589401 , @kpet wrote:

> Very useful to have all of this documented! Thanks!


Would it be ok if I fix those in a separate commit? I would really like to 
commit the core part before the release branch is taken.


CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D64418/new/

https://reviews.llvm.org/D64418



___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[PATCH] D64418: [Docs][OpenCL] Documentation of C++ for OpenCL mode

[Kévin Petit via Phabricator via cfe-commits]

kpet requested changes to this revision.
kpet added a comment.
This revision now requires changes to proceed.

Very useful to have all of this documented! Thanks!




Comment at: docs/LanguageExtensions.rst:1527
+This functionality is built on top of OpenCL C v2.0 and C++17. Regular C++
+features can be used in OpenCL kernel code. All functionality from OpenCL C
+is inherited. This section describes minor differences to OpenCL C and any

I'm tempted to suggest you merge the first two sentences and tone down the 
claim in the second. "This functionality [...] and C++17, enabling _some_ 
regular C++ features [...].



Comment at: docs/LanguageExtensions.rst:1527
+This functionality is built on top of OpenCL C v2.0 and C++17. Regular C++
+features can be used in OpenCL kernel code. All functionality from OpenCL C
+is inherited. This section describes minor differences to OpenCL C and any

kpet wrote:
> I'm tempted to suggest you merge the first two sentences and tone down the 
> claim in the second. "This functionality [...] and C++17, enabling _some_ 
> regular C++ features [...].
s/All/Most/? Stating that all functionality from OpenCL C is available right 
before stating that the differences will be described feels like a 
contradiction.



Comment at: docs/LanguageExtensions.rst:1535
+
+The following features are not supported:
+

Probably worth adding exceptions to the list.



Comment at: docs/LanguageExtensions.rst:1541
+- Standard C++ libraries. Currently there is no solution for alternative C++
+  libraries provided. Future release will feature library support.
+

I would remove this last sentence. Only a very small portion of the libray can 
be supported anyway.



Comment at: docs/LanguageExtensions.rst:1553
+extension ISO/IEC JTC1 SC22 WG14 N1021 s3.1. Note that since the address space
+behavior in C++ is not documented formally yet, Clang extends existing concept
+from C and OpenCL. For example conversion rules are extended from qualification

I would remove the "yet", unless we can refer to an on-going and visible effort.



Comment at: docs/LanguageExtensions.rst:1553
+extension ISO/IEC JTC1 SC22 WG14 N1021 s3.1. Note that since the address space
+behavior in C++ is not documented formally yet, Clang extends existing concept
+from C and OpenCL. For example conversion rules are extended from qualification

kpet wrote:
> I would remove the "yet", unless we can refer to an on-going and visible 
> effort.
"Clang extends existing concept" feels like it should be re-worded.



Comment at: docs/LanguageExtensions.rst:1555
+from C and OpenCL. For example conversion rules are extended from qualification
+conversion but the compatibility is determined using sets and overlapping from
+Embedded C (ISO/IEC JTC1 SC22 WG14 N1021 s3.1.3). For OpenCL it means that

"using sets and overlapping" feels incomplete. Pretending I can't guess: sets 
of what? What is overlapping what? :)



Comment at: docs/LanguageExtensions.rst:1557
+Embedded C (ISO/IEC JTC1 SC22 WG14 N1021 s3.1.3). For OpenCL it means that
+implicit conversions are allowed from named to ``__generic`` but not vice versa
+(OpenCL C v2.0 s6.5.5) except for ``__constant`` address space. Most of the

Why use `__generic` when `generic` is equally valid and easier on the eyes? The 
same comment applies to other mentions of address space keywords.



Comment at: docs/LanguageExtensions.rst:1558
+implicit conversions are allowed from named to ``__generic`` but not vice versa
+(OpenCL C v2.0 s6.5.5) except for ``__constant`` address space. Most of the
+rules are built on top of this behavior.

This is ambiguous. One could read that conversions from `__generic` to 
`__constant` are allowed.



Comment at: docs/LanguageExtensions.rst:1564
+C style cast will follow OpenCL C v2.0 rules (s6.5.5). All cast operators will
+permit implicit conversion to ``__generic``. However converting from named
+address spaces to ``__generic`` can only be done using ``addrspace_cast``. Note

Isn't a conversion explicit if a cast operator is used?



Comment at: docs/LanguageExtensions.rst:1565
+permit implicit conversion to ``__generic``. However converting from named
+address spaces to ``__generic`` can only be done using ``addrspace_cast``. Note
+that conversions between ``__constant`` and any other is still disallowed.

At the time of writing `addrspace_cast` doesn't seem to exist in trunk and 
C-style casts seem to work.



Comment at: docs/LanguageExtensions.rst:1565
+permit implicit conversion to ``__generic``. However converting from named
+address spaces to ``__generic`` can only be done using 

[PATCH] D64418: [Docs][OpenCL] Documentation of C++ for OpenCL mode

[Marco Antognini via Phabricator via cfe-commits]

mantognini accepted this revision.
mantognini added a comment.
This revision is now accepted and ready to land.

Beside my two comments, I think this looks good.




Comment at: docs/LanguageExtensions.rst:1614
+
+By default references will refer to ``__generic`` address space objects 
(except for
+dependent types that are not template specializations

` (` -> `, ` (there's no matching closing parenthesis.)



Comment at: docs/LanguageExtensions.rst:1652-1657
+ __kernel void bar() {
+   __local C c1; // will resolve to the first foo
+   C c2; // will resolve to the second foo
+   __constant C c3; // error due to mismatching address spaces - can't convert 
to
+// __local or __generic
+ }

`foo()` isn't actually called here. You probably meant to write this:


```
__local C c1;
C c2;
__constant C c3;

c1.foo(); // will resolve to the first foo
c2.foo(); // will resolve to the second foo
c3.foo(); // error due to mismatching address spaces - can't convert to __local 
or __generic
```


CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D64418/new/

https://reviews.llvm.org/D64418



___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[PATCH] D64418: [Docs][OpenCL] Documentation of C++ for OpenCL mode

[Anastasia Stulova via Phabricator via cfe-commits]

Anastasia updated this revision to Diff 210101.

CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D64418/new/

https://reviews.llvm.org/D64418

Files:
  docs/LanguageExtensions.rst
  docs/UsersManual.rst

Index: docs/UsersManual.rst
===
--- docs/UsersManual.rst
+++ docs/UsersManual.rst
@@ -2397,7 +2397,8 @@
 This will produce a generic test.bc file that can be used in vendor toolchains
 to perform machine code generation.
 
-Clang currently supports OpenCL C language standards up to v2.0.
+Clang currently supports OpenCL C language standards up to v2.0. Starting from Clang9
+C++ mode is available for OpenCL (see :ref:`C++ for OpenCL `).
 
 OpenCL Specific Options
 ---
@@ -2756,6 +2757,45 @@
   enqueue query functions from `section 6.13.17.5
   `_.
 
+.. _opencl_cpp:
+
+C++ for OpenCL
+--
+
+Starting from Clang9 kernel code can contain C++17 features: classes, templates,
+function overloading, type deduction, etc. Please note that this is not an
+implementation of `OpenCL C++
+`_ and
+there is no plan to support it in clang in any new releases in the near future.
+
+There are only a few restrictions on allowed C++ features. For detailed information
+please refer to documentation on Extensions (:doc:`LanguageExtensions`).
+
+Since C++ features are to be used on top of OpenCL C functionality, all existing
+restrictions from OpenCL C v2.0 will inherently apply. All OpenCL C builtin types
+and function libraries are supported and can be used in the new mode.
+
+To enable the new mode pass the following command line option when compiling ``.cl``
+file ``-cl-std=c++`` or ``-std=c++``.
+
+   .. code-block:: c++
+
+ template T add( T x, T y )
+ {
+   return x + y;
+ }
+
+ __kernel void test( __global float* a, __global float* b)
+ {
+   auto index = get_global_id(0);
+   a[index] = add(b[index], b[index+1]);
+ }
+
+
+   .. code-block:: console
+
+ clang -cl-std=c++ test.cl
+
 .. _target_features:
 
 Target-Specific Features and Limitations
Index: docs/LanguageExtensions.rst
===
--- docs/LanguageExtensions.rst
+++ docs/LanguageExtensions.rst
@@ -1516,6 +1516,269 @@
 Query the presence of this new mangling with
 ``__has_feature(objc_protocol_qualifier_mangling)``.
 
+
+OpenCL Features
+===
+
+C++ for OpenCL
+--
+
+This functionality is built on top of OpenCL C v2.0 and C++17. Regular C++
+features can be used in OpenCL kernel code. All functionality from OpenCL C
+is inherited. This section describes minor differences to OpenCL C and any
+limitations related to C++ support as well as interactions between OpenCL and
+C++ features that are not documented elsewhere.
+
+Restrictions to C++17
+^
+
+The following features are not supported:
+
+- Virtual functions
+- ``dynamic_cast`` operator
+- Non-placement ``new``/``delete`` operators
+- Standard C++ libraries. Currently there is no solution for alternative C++
+  libraries provided. Future release will feature library support.
+
+
+Interplay of OpenCL and C++ features
+
+
+Address space behavior
+""
+
+Address spaces are part of the type qualifiers; many rules are just inherited
+from the qualifier behavior documented in OpenCL C v2.0 s6.5 and Embedded C
+extension ISO/IEC JTC1 SC22 WG14 N1021 s3.1. Note that since the address space
+behavior in C++ is not documented formally yet, Clang extends existing concept
+from C and OpenCL. For example conversion rules are extended from qualification
+conversion but the compatibility is determined using sets and overlapping from
+Embedded C (ISO/IEC JTC1 SC22 WG14 N1021 s3.1.3). For OpenCL it means that
+implicit conversions are allowed from named to ``__generic`` but not vice versa
+(OpenCL C v2.0 s6.5.5) except for ``__constant`` address space. Most of the
+rules are built on top of this behavior.
+
+**Casts**
+
+C style cast will follow OpenCL C v2.0 rules (s6.5.5). All cast operators will
+permit implicit conversion to ``__generic``. However converting from named
+address spaces to ``__generic`` can only be done using ``addrspace_cast``. Note
+that conversions between ``__constant`` and any other is still disallowed.
+
+.. _opencl_cpp_addrsp_deduction:
+
+**Deduction**
+
+Address spaces are not deduced for:
+
+- non-pointer/non-reference template parameters or any dependent types except
+  for template specializations.
+- non-pointer/non-reference class members except for static data members that are
+  deduced to ``__global`` address space.
+- non-pointer/non-reference alias declarations.
+- ``decltype`` expression.
+
+.. code-block:: c++
+
+  template 
+  void foo() {
+T m; // 

[PATCH] D64418: [Docs][OpenCL] Documentation of C++ for OpenCL mode

[Anastasia Stulova via Phabricator via cfe-commits]

Anastasia added inline comments.



Comment at: docs/LanguageExtensions.rst:1673
+
+All builtin operators will be available in the specific address spaces, thus 
no conversion
+to generic is performed.

mantognini wrote:
> "specific" seems to imply to the user will have to explicitly write down the 
> AS. Maybe "requested" or "desired" would fit better?
Ok, specific here is as opposite to generic. 



Comment at: docs/LanguageExtensions.rst:1753-1761
+Global objects are constructed before the first kernel using the global
+objects is executed and destroyed just after the last kernel using the
+program objects is executed. In OpenCL v2.0 drivers there is no specific
+API for invoking global constructors. However, an easy workaround would be
+to enqueue constructor initialization kernel that has a name
+``@_GLOBAL__sub_I_``. This kernel is only present if there
+are any global objects to be initialized in the compiled binary. One way to

mantognini wrote:
> Is it expected of the user to call this special kernel, or is it expected 
> that the driver takes care of that?
In v2.0 drivers this is a manual step. In v2.2 drivers it is expected to be 
done automatically.



Comment at: docs/LanguageExtensions.rst:1758
+to enqueue constructor initialization kernel that has a name
+``@_GLOBAL__sub_I_``. This kernel is only present if there
+are any global objects to be initialized in the compiled binary. One way to

keryell wrote:
> " Is there an issue if you link a program from several files with the same file 
> names?
I think IR linker makes them unique i.e. adds a suffix. Although I think the 
files (including the path) linked are supposed to be unique. Anyway, good point 
to look into.

No idea about obj linker. We currently don't support this feature.



Comment at: docs/LanguageExtensions.rst:1768
+.. code-block:: console
+ clang -cl-std=c++ test.cl
+

mantognini wrote:
> As it stands, I'm not sure why this command is mentioned in this paragraph. 
> Maybe it's a leftover of things that are now in the User's Manual?
This is the example I am explaining just below.



Comment at: docs/UsersManual.rst:2797
+
+ clang -cl-std=c++ test.cl
+

mantognini wrote:
> I would remove this code sample; it is already explained above that 
> `-cl-std=c++` should be used.
Manual is good for examples. Some new developers might find it useful to have 
the full line even though it's quite simple.


CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D64418/new/

https://reviews.llvm.org/D64418



___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[PATCH] D64418: [Docs][OpenCL] Documentation of C++ for OpenCL mode

[Anastasia Stulova via Phabricator via cfe-commits]

Anastasia updated this revision to Diff 210064.
Anastasia marked 5 inline comments as done.
Anastasia added a comment.

Addressed some review comments. Refs are still to be fixed!


CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D64418/new/

https://reviews.llvm.org/D64418

Files:
  docs/LanguageExtensions.rst
  docs/UsersManual.rst

Index: docs/UsersManual.rst
===
--- docs/UsersManual.rst
+++ docs/UsersManual.rst
@@ -2397,7 +2397,8 @@
 This will produce a generic test.bc file that can be used in vendor toolchains
 to perform machine code generation.
 
-Clang currently supports OpenCL C language standards up to v2.0.
+Clang currently supports OpenCL C language standards up to v2.0. Starting from Clang9
+C++ mode is available for OpenCL (see :ref:``).
 
 OpenCL Specific Options
 ---
@@ -2756,6 +2757,45 @@
   enqueue query functions from `section 6.13.17.5
   `_.
 
+.. _opencl_cpp:
+
+C++ for OpenCL
+--
+
+Starting from Clang9 kernel code can contain C++17 features: classes, templates,
+function overloading, type deduction, etc. Please note that this is not an
+implementation of `OpenCL C++
+`_ and
+there is no plan to support it in clang in any new releases in the near future.
+
+There are only a few restrictions on allowed C++ features. For detailed information
+please refer to documentation on Extensions (:doc:`LanguageExtensions`).
+
+Since C++ features are to be used on top of OpenCL C functionality, all existing
+restrictions from OpenCL C v2.0 will inherently apply. All OpenCL C builtin types
+and function libraries are supported and can be used in the new mode.
+
+To enable the new mode pass the following command line option when compiling ``.cl``
+file ``-cl-std=c++`` or ``-std=c++``.
+
+   .. code-block:: c++
+
+ template T add( T x, T y )
+ {
+   return x + y;
+ }
+
+ __kernel void test( __global float* a, __global float* b)
+ {
+   auto index = get_global_id(0);
+   a[index] = add(b[index], b[index+1]);
+ }
+
+
+   .. code-block:: console
+
+ clang -cl-std=c++ test.cl
+
 .. _target_features:
 
 Target-Specific Features and Limitations
Index: docs/LanguageExtensions.rst
===
--- docs/LanguageExtensions.rst
+++ docs/LanguageExtensions.rst
@@ -1516,6 +1516,268 @@
 Query the presence of this new mangling with
 ``__has_feature(objc_protocol_qualifier_mangling)``.
 
+
+OpenCL Features
+===
+
+C++ for OpenCL
+--
+
+This functionality is built on top of OpenCL C v2.0 and C++17. Regular C++
+features can be used in OpenCL kernel code. All functionality from OpenCL C
+is inherited. This section describes minor differences to OpenCL C and any
+limitations related to C++ support as well as interactions between OpenCL and
+C++ features that are not documented elsewhere.
+
+Restrictions to C++17
+^
+
+The following features are not supported:
+
+- Virtual functions
+- ``dynamic_cast`` operator
+- Non-placement ``new``/``delete`` operators
+- Standard C++ libraries. Currently there is no solution for alternative
+  libraries provided. Future release will feature library support.
+
+
+Interplay of OpenCL and C++ features
+
+
+Address space behavior
+""
+
+Address spaces are part of the type qualifiers; many rules are just inherited
+from the qualifier behavior documented in OpenCL C v2.0 s6.5 and Embedded C
+extension ISO/IEC JTC1 SC22 WG14 N1021 s3.1. Note that since the address space
+behavior in C++ is not documented formally yet, Clang extends existing concept
+from C and OpenCL. For example conversion rules are extended from qualification
+conversions but the compatibility is determined using sets and overlapping from
+Embedded C (ISO/IEC JTC1 SC22 WG14 N1021 s3.1.3). For OpenCL it means that
+implicit conversions are allowed from named to ``__generic`` but not vice versa
+(OpenCL C v2.0 s6.5.5) except for constant address space. Most of the rules
+are built on top of this behavior.
+
+**Casts**
+
+C style cast will follow OpenCL C v2.0 rules (s6.5.5). All cast operators will
+permit implicit conversion to ``__generic``. However converting from named
+address spaces to ``__generic`` can only be done using ``addrspace_cast``. Note
+that conversions between ``__constant`` and any other is still disallowed.
+
+.. _opencl_cpp_addrsp_deduction:
+
+**Deduction**
+
+Address spaces are not deduced for:
+
+- non-pointer/non-reference template parameters or any dependent types are except
+  for template specializations.
+- non-pointer/non-reference class members except for static data members that are
+  deduced to __global address space. 
+- non-pointer/non-reference alias 

[PATCH] D64418: [Docs][OpenCL] Documentation of C++ for OpenCL mode

[Anastasia Stulova via Phabricator via cfe-commits]

Anastasia marked an inline comment as done.
Anastasia added inline comments.



Comment at: docs/LanguageExtensions.rst:1772
+``@_GLOBAL__sub_I_test.cl`` kernel to be enqueued.
+
+

I think I should add something about dtors too.


CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D64418/new/

https://reviews.llvm.org/D64418



___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[PATCH] D64418: [Docs][OpenCL] Documentation of C++ for OpenCL mode

[Ronan Keryell via Phabricator via cfe-commits]

keryell added a comment.

Good improvement!




Comment at: docs/LanguageExtensions.rst:1758
+to enqueue constructor initialization kernel that has a name
+``@_GLOBAL__sub_I_``. This kernel is only present if there
+are any global objects to be initialized in the compiled binary. One way to

"https://reviews.llvm.org/D64418/new/

https://reviews.llvm.org/D64418



___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[PATCH] D64418: [Docs][OpenCL] Documentation of C++ for OpenCL mode

[Marco Antognini via Phabricator via cfe-commits]

mantognini added a comment.

Here are a few comments from me but keep in mind that English is not my primary 
language




Comment at: docs/LanguageExtensions.rst:1562-1565
+C style cast will follow OpenCL C v2.0 rules (s6.5.5). All cast operators will
+permit implicit conversion to generic. However converting from named address
+spaces to generic can only be done using ``addrspace_cast``. Note that
+conversions between ``__constant`` and any other is still disallowed.

I would suggest using `__generic` or //generic address space//. The later is a 
bit more verbose, but makes the sentence more natural I think.



Comment at: docs/LanguageExtensions.rst:1582
+  void foo() {
+T m; // address space of m will be knowns at template instantiation time.
+T * ptr; // ptr points to generic address space object.

s/knowns/known/



Comment at: docs/LanguageExtensions.rst:1611-1615
+By default references will refer to generic address space objects (except for
+dependent types that are not template specializations
+(:ref:``). When references are bound to values 
address
+space compatibility check will be performed. The logic will largely follow the 
rules
+from address space pointer conversion (OpenCL v2.0 s6.5.5).

The `ref` is broken. There's also one too many `(`.



Comment at: docs/LanguageExtensions.rst:1613-1614
+dependent types that are not template specializations
+(:ref:``). When references are bound to values 
address
+space compatibility check will be performed. The logic will largely follow the 
rules
+from address space pointer conversion (OpenCL v2.0 s6.5.5).

> When references are bound to values address space compatibility check will be 
> performed.

This might just be me so this might actually be okay, but I feel the sentence 
is simpler when rewritten as "Address space compatibility checks are performed 
when references are bound to values." What do you think?

> The logic will largely follow the rules from address space pointer conversion

Present tense should probably be better. Are there actually any differences? If 
no, I would drop "largely" from the sentence. Otherwise it might be good to 
actually list the differences.



Comment at: docs/LanguageExtensions.rst:1617
+
+**Default AS**
+ 

AS might be better fully spelled out.



Comment at: docs/LanguageExtensions.rst:1619
+ 
+All non-static methods take implicit object parameter that is a pointer type. 
By
+default this pointer parameter is in generic address space. All concrete 
objects

take //an// implicit



Comment at: docs/LanguageExtensions.rst:1624
+address space won't be compiled unless address space is explicitly specified 
using
+address space method qualifiers ((:ref:``) 
as the
+conversion between ``__constant`` and generic is disallowed. Method qualifiers 
can

`ref` is broken and there's one too manu `(`.



Comment at: docs/LanguageExtensions.rst:1627
+also be useful in case conversion to generic address space is undesirable 
(even if
+it's legal). For example if we need to take advantage of memory bank accesses.
+Please note this not only applies to regular methods but to constructors and

> For example if we need to take advantage of memory bank accesses.

Maybe "For example: to take advantage [...]"?



Comment at: docs/LanguageExtensions.rst:1662
+
+  class C{
+// Has the following implicit definition

nitpicking: missing space before `{`.



Comment at: docs/LanguageExtensions.rst:1671
+
+**Built in operators**
+

Typo: //Builtin//



Comment at: docs/LanguageExtensions.rst:1673
+
+All builtin operators will be available in the specific address spaces, thus 
no conversion
+to generic is performed.

"specific" seems to imply to the user will have to explicitly write down the 
AS. Maybe "requested" or "desired" would fit better?



Comment at: docs/LanguageExtensions.rst:1679
+There is no deduction of address spaces in non-pointer/non-reference template 
parameters and
+dependent types (:ref:``). The address space of 
template
+parameter is deduced during the type deduction if it's not explicitly provided 
in

The reference seems broken as well.



Comment at: docs/LanguageExtensions.rst:1708
+  void bar() {
+foo3<__global int>(); // error: conflicting address space qualifiers are 
provided
+  }

s/foo3/foo/



Comment at: docs/LanguageExtensions.rst:1717
+  void foo(){
+  T var;
+  }

nitpicking: indentation. Might as well rename it to `ii` to match the other 
example.



Comment at: docs/LanguageExtensions.rst:1753-1761
+Global objects are 

[PATCH] D64418: [Docs][OpenCL] Documentation of C++ for OpenCL mode

[Neil Hickey via Phabricator via cfe-commits]

neil.hickey added inline comments.



Comment at: docs/LanguageExtensions.rst:1538
+- ``dynamic_cast`` operator
+- Only placement ``new``/``delete`` operators
+- Standard C++ libraries. Currently there is no solution for alternative

This seems weird, you say the following features are not supported then say 
Only placement new/delete. I think you mean to say new/delete is not supported 
except for placement new and delete.



Comment at: docs/LanguageExtensions.rst:1549
+
+Address spaces are part of the type qualifiers. Therefore many rules are just
+inherited from the qualifier behavior documented in OpenCL C v2.0 s6.5 and

I'd replace ". Therefore" with "; "



Comment at: docs/LanguageExtensions.rst:1552
+Embedded C extension ISO/IEC JTC1 SC22 WG14 N1021 s3.1. Note that since the
+address space behavior in C++ is not documented formally yet Clang extends
+existing concept from C and OpenCL. For example conversion rules are extended

need a , between yet and Clang I think, to remove the ambiguity


CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D64418/new/

https://reviews.llvm.org/D64418



___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[PATCH] D64418: [Docs][OpenCL] Documentation of C++ for OpenCL mode

[Anastasia Stulova via Phabricator via cfe-commits]

Anastasia created this revision.
Anastasia added reviewers: svenvh, mantognini, stuart, neil.hickey.
Herald added subscribers: ebevhan, yaxunl.

Added documentation of C++ for OpenCL mode into Clang User Manual and Language 
Extensions document.


https://reviews.llvm.org/D64418

Files:
  docs/LanguageExtensions.rst
  docs/UsersManual.rst

Index: docs/UsersManual.rst
===
--- docs/UsersManual.rst
+++ docs/UsersManual.rst
@@ -2397,7 +2397,8 @@
 This will produce a generic test.bc file that can be used in vendor toolchains
 to perform machine code generation.
 
-Clang currently supports OpenCL C language standards up to v2.0.
+Clang currently supports OpenCL C language standards up to v2.0. Starting from Clang9
+C++ mode is available for OpenCL (see :ref:``).
 
 OpenCL Specific Options
 ---
@@ -2756,6 +2757,45 @@
   enqueue query functions from `section 6.13.17.5
   `_.
 
+.. _opencl_cpp:
+
+C++ for OpenCL
+--
+
+Starting from Clang9 kernel code can contain C++17 features: classes, templates,
+function overloading, type deduction, etc. Please note that this is not an
+implementation of `OpenCL C++
+`_ and
+there is no plan to support it in clang in any new releases in the near future.
+
+There are only a few restrictions on allowed C++ features, for detailed information
+please refer to documentation on Extensions (:doc:`LanguageExtensions`).
+
+Since C++ features are to be used on top of OpenCL C functionality all existing
+restrictions from OpenCL C v2.0 will inherently apply. All OpenCL C builtin types
+and function libraries are supported and can be used in the new mode.
+
+To enable the new mode pass the following command line option when compiling .cl
+file ``-cl-std=c++`` or ``-std=c++``.
+
+   .. code-block:: c++
+
+ template T add( T x, T y )
+ {
+   return x + y;
+ }
+
+ __kernel void test( __global float* a, __global float* b)
+ {
+   auto index = get_global_id(0);
+   a[index] = add(b[index], b[index+1]);
+ }
+
+
+   .. code-block:: console
+
+ clang -cl-std=c++ test.cl
+
 .. _target_features:
 
 Target-Specific Features and Limitations
Index: docs/LanguageExtensions.rst
===
--- docs/LanguageExtensions.rst
+++ docs/LanguageExtensions.rst
@@ -1516,6 +1516,261 @@
 Query the presence of this new mangling with
 ``__has_feature(objc_protocol_qualifier_mangling)``.
 
+
+OpenCL Features
+===
+
+C++ for OpenCL
+--
+
+This functionality is built on top of OpenCL C v2.0 and C++17. Regular C++
+features can be used in OpenCL kernel code. All functionality from OpenCL C
+is inherited. This section describes minor differences to OpenCL C and any
+limitations related to C++ support as well as interactions between OpenCL and
+C++ features that are not documented elsewhere.
+
+Restrictions to C++17
+^
+
+The following features are not supported:
+- Virtual functions
+- ``dynamic_cast`` operator
+- Only placement ``new``/``delete`` operators
+- Standard C++ libraries. Currently there is no solution for alternative
+libraries provided. Future release will feature library support.
+
+
+Interplay of OpenCL and C++ features
+
+
+Address space behavior
+""
+
+Address spaces are part of the type qualifiers. Therefore many rules are just
+inherited from the qualifier behavior documented in OpenCL C v2.0 s6.5 and
+Embedded C extension ISO/IEC JTC1 SC22 WG14 N1021 s3.1. Note that since the
+address space behavior in C++ is not documented formally yet Clang extends
+existing concept from C and OpenCL. For example conversion rules are extended
+from qualification conversions but the compatibility is determined using sets
+and overlapping from Embedded C (ISO/IEC JTC1 SC22 WG14 N1021 s3.1.3). For OpenCL
+it means that implicit conversions are allowed from named to generic but not vice
+versa (OpenCL C v2.0 s6.5.5) except for constant address space. Most of the rules
+are built on top of this behavior.
+
+**Casts**
+
+C style cast will follow OpenCL C v2.0 rules (s6.5.5). All cast operators will
+permit implicit conversion to generic. However converting from named address
+spaces to generic can only be done using ``addrspace_cast``. Note that
+conversions between ``__constant`` and any other is still disallowed.
+
+.. _opencl_cpp_addrsp_deduction:
+**Deduction**
+
+Address spaces are not deduced for:
+- non-pointer/non-reference template parameters or any dependent types are except
+  for template specializations.
+- non-pointer/non-reference class members except for static data members that are
+  deduced to __global address space. 
+- non-pointer/non-reference alias declarations.
+-