<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<style type="text/css" style="display:none;"><!-- P {margin-top:0;margin-bottom:0;} --></style>
</head>
<body dir="ltr">
<div id="divtagdefaultwrapper" style="font-size: 12pt; color: rgb(0, 0, 0); font-family: Calibri, Helvetica, sans-serif, Helvetica, EmojiFont, "Apple Color Emoji", "Segoe UI Emoji", NotoColorEmoji, "Segoe UI Symbol", "Android Emoji", EmojiSymbols;" dir="ltr">
<p style="margin-top:0;margin-bottom:0">Hi Hans,</p>
<p style="margin-top:0;margin-bottom:0"><br>
</p>
<p style="margin-top:0;margin-bottom:0">Can this be merged to the release, please?</p>
<p style="margin-top:0;margin-bottom:0"><br>
</p>
<p style="margin-top:0;margin-bottom:0">Thank you,</p>
<p style="margin-top:0;margin-bottom:0">Anastasia</p>
<br>
<br>
<div style="color: rgb(0, 0, 0);">
<hr style="display:inline-block;width:98%" tabindex="-1">
<div id="divRplyFwdMsg" dir="ltr"><font face="Calibri, sans-serif" style="font-size:11pt" color="#000000"><b>From:</b> cfe-commits <cfe-commits-bounces@lists.llvm.org> on behalf of Anastasia Stulova via cfe-commits <cfe-commits@lists.llvm.org><br>
<b>Sent:</b> 23 August 2019 12:43<br>
<b>To:</b> cfe-commits@lists.llvm.org <cfe-commits@lists.llvm.org><br>
<b>Subject:</b> r369749 - [Docs][OpenCL] Several corrections to C++ for OpenCL</font>
<div> </div>
</div>
<div class="BodyFragment"><font size="2"><span style="font-size:11pt;">
<div class="PlainText">Author: stulova<br>
Date: Fri Aug 23 04:43:49 2019<br>
New Revision: 369749<br>
<br>
URL: <a href="http://llvm.org/viewvc/llvm-project?rev=369749&view=rev">http://llvm.org/viewvc/llvm-project?rev=369749&view=rev</a><br>
Log:<br>
[Docs][OpenCL] Several corrections to C++ for OpenCL<br>
<br>
Differential Revision:https://reviews.llvm.org/D64418<br>
<br>
<br>
Modified:<br>
cfe/trunk/docs/LanguageExtensions.rst<br>
cfe/trunk/docs/UsersManual.rst<br>
<br>
Modified: cfe/trunk/docs/LanguageExtensions.rst<br>
URL: <a href="http://llvm.org/viewvc/llvm-project/cfe/trunk/docs/LanguageExtensions.rst?rev=369749&r1=369748&r2=369749&view=diff">
http://llvm.org/viewvc/llvm-project/cfe/trunk/docs/LanguageExtensions.rst?rev=369749&r1=369748&r2=369749&view=diff</a><br>
==============================================================================<br>
--- cfe/trunk/docs/LanguageExtensions.rst (original)<br>
+++ cfe/trunk/docs/LanguageExtensions.rst Fri Aug 23 04:43:49 2019<br>
@@ -1640,8 +1640,8 @@ OpenCL Features<br>
C++ for OpenCL<br>
--------------<br>
<br>
-This functionality is built on top of OpenCL C v2.0 and C++17. Regular C++<br>
-features can be used in OpenCL kernel code. All functionality from OpenCL C<br>
+This functionality is built on top of OpenCL C v2.0 and C++17 enabling most of<br>
+regular C++ features in OpenCL kernel code. Most functionality from OpenCL C<br>
is inherited. This section describes minor differences to OpenCL C and any<br>
limitations related to C++ support as well as interactions between OpenCL and<br>
C++ features that are not documented elsewhere.<br>
@@ -1652,6 +1652,7 @@ Restrictions to C++17<br>
The following features are not supported:<br>
<br>
- Virtual functions<br>
+- Exceptions<br>
- ``dynamic_cast`` operator<br>
- Non-placement ``new``/``delete`` operators<br>
- Standard C++ libraries. Currently there is no solution for alternative C++<br>
@@ -1667,20 +1668,24 @@ Address space behavior<br>
Address spaces are part of the type qualifiers; many rules are just inherited<br>
from the qualifier behavior documented in OpenCL C v2.0 s6.5 and Embedded C<br>
extension ISO/IEC JTC1 SC22 WG14 N1021 s3.1. Note that since the address space<br>
-behavior in C++ is not documented formally yet, Clang extends existing concept<br>
+behavior in C++ is not documented formally, Clang extends the existing concept<br>
from C and OpenCL. For example conversion rules are extended from qualification<br>
-conversion but the compatibility is determined using sets and overlapping from<br>
-Embedded C (ISO/IEC JTC1 SC22 WG14 N1021 s3.1.3). For OpenCL it means that<br>
-implicit conversions are allowed from named to ``__generic`` but not vice versa<br>
-(OpenCL C v2.0 s6.5.5) except for ``__constant`` address space. Most of the<br>
-rules are built on top of this behavior.<br>
+conversion but the compatibility is determined using notation of sets and<br>
+overlapping of address spaces from Embedded C (ISO/IEC JTC1 SC22 WG14 N1021<br>
+s3.1.3). For OpenCL it means that implicit conversions are allowed from<br>
+a named address space (except for ``__constant``) to ``__generic`` (OpenCL C<br>
+v2.0 6.5.5). Reverse conversion is only allowed explicitly. The ``__constant``<br>
+address space does not overlap with any other and therefore no valid conversion<br>
+between ``__constant`` and other address spaces exists. Most of the rules<br>
+follow this logic.<br>
<br>
**Casts**<br>
<br>
-C style cast will follow OpenCL C v2.0 rules (s6.5.5). All cast operators will<br>
-permit implicit conversion to ``__generic``. However converting from named<br>
-address spaces to ``__generic`` can only be done using ``addrspace_cast``. Note<br>
-that conversions between ``__constant`` and any other is still disallowed.<br>
+C-style casts follow OpenCL C v2.0 rules (s6.5.5). All cast operators<br>
+permit conversion to ``__generic`` implicitly. However converting from<br>
+``__generic`` to named address spaces can only be done using ``addrspace_cast``.<br>
+Note that conversions between ``__constant`` and any other address space<br>
+are disallowed.<br>
<br>
.. _opencl_cpp_addrsp_deduction:<br>
<br>
@@ -1693,7 +1698,7 @@ Address spaces are not deduced for:<br>
- non-pointer/non-reference class members except for static data members that are<br>
deduced to ``__global`` address space.<br>
- non-pointer/non-reference alias declarations.<br>
-- ``decltype`` expression.<br>
+- ``decltype`` expressions.<br>
<br>
.. code-block:: c++<br>
<br>
@@ -1722,7 +1727,7 @@ TODO: Add example for type alias and dec<br>
<br>
**References**<br>
<br>
-References types can be qualified with an address space.<br>
+Reference types can be qualified with an address space.<br>
<br>
.. code-block:: c++<br>
<br>
@@ -1737,29 +1742,29 @@ rules from address space pointer convers<br>
**Default address space**<br>
<br>
All non-static member functions take an implicit object parameter ``this`` that<br>
-is a pointer type. By default this pointer parameter is in ``__generic`` address<br>
-space. All concrete objects passed as an argument to ``this`` parameter will be<br>
-converted to ``__generic`` address space first if the conversion is valid.<br>
-Therefore programs using objects in ``__constant`` address space won't be compiled<br>
-unless address space is explicitly specified using address space qualifiers on<br>
-member functions<br>
+is a pointer type. By default this pointer parameter is in the ``__generic``<br>
+address space. All concrete objects passed as an argument to ``this`` parameter<br>
+will be converted to the ``__generic`` address space first if such conversion is<br>
+valid. Therefore programs using objects in the ``__constant`` address space will<br>
+not be compiled unless the address space is explicitly specified using address<br>
+space qualifiers on member functions<br>
(see :ref:`Member function qualifier <opencl_cpp_addrspace_method_qual>`) as the<br>
conversion between ``__constant`` and ``__generic`` is disallowed. Member function<br>
-qualifiers can also be used in case conversion to ``__generic`` address space is<br>
-undesirable (even if it is legal), for example to take advantage of memory bank<br>
-accesses. Note this not only applies to regular member functions but to<br>
-constructors and destructors too.<br>
+qualifiers can also be used in case conversion to the ``__generic`` address space<br>
+is undesirable (even if it is legal). For example, a method can be implemented to<br>
+exploit memory access coalescing for segments with memory bank. This not only<br>
+applies to regular member functions but to constructors and destructors too.<br>
<br>
.. _opencl_cpp_addrspace_method_qual:<br>
<br>
**Member function qualifier**<br>
<br>
-Clang allows specifying address space qualifier on member functions to signal that<br>
-they are to be used with objects constructed in some specific address space. This<br>
-works just the same as qualifying member functions with ``const`` or any other<br>
-qualifiers. The overloading resolution will select overload with most specific<br>
-address space if multiple candidates are provided. If there is no conversion to<br>
-to an address space among existing overloads compilation will fail with a<br>
+Clang allows specifying an address space qualifier on member functions to signal<br>
+that they are to be used with objects constructed in some specific address space.<br>
+This works just the same as qualifying member functions with ``const`` or any<br>
+other qualifiers. The overloading resolution will select the candidate with the<br>
+most specific address space if multiple candidates are provided. If there is no<br>
+conversion to an address space among candidates, compilation will fail with a<br>
diagnostic.<br>
<br>
.. code-block:: c++<br>
@@ -1782,7 +1787,7 @@ diagnostic.<br>
**Implicit special members**<br>
<br>
All implicit special members (default, copy, or move constructor, copy or move<br>
-assignment, destructor) will be generated with ``__generic`` address space.<br>
+assignment, destructor) will be generated with the ``__generic`` address space.<br>
<br>
.. code-block:: c++<br>
<br>
@@ -1797,15 +1802,15 @@ assignment, destructor) will be generate<br>
<br>
**Builtin operators**<br>
<br>
-All builtin operators are available in the specific address spaces, thus no conversion<br>
-to ``__generic`` is performed.<br>
+All builtin operators are available in the specific address spaces, thus no<br>
+conversion to ``__generic`` is performed.<br>
<br>
**Templates**<br>
<br>
-There is no deduction of address spaces in non-pointer/non-reference template parameters<br>
-and dependent types (see :ref:`Deduction <opencl_cpp_addrsp_deduction>`). The address<br>
-space of template parameter is deduced during the type deduction if it's not explicitly<br>
-provided in instantiation.<br>
+There is no deduction of address spaces in non-pointer/non-reference template<br>
+parameters and dependent types (see :ref:`Deduction <opencl_cpp_addrsp_deduction>`).<br>
+The address space of a template parameter is deduced during type deduction if<br>
+it is not explicitly provided in the instantiation.<br>
<br>
.. code-block:: c++<br>
<br>
@@ -1816,13 +1821,14 @@ provided in instantiation.<br>
5<br>
6 __global int g;<br>
7 void bar(){<br>
- 8 foo(&g); // error: template instantiation failed as function scope variable appears to<br>
- 9 // be declared in __global address space (see line 3)<br>
+ 8 foo(&g); // error: template instantiation failed as function scope variable<br>
+ 9 // appears to be declared in __global address space (see line 3)<br>
10 }<br>
<br>
-It is not legal to specify multiple different address spaces between template definition and<br>
-instantiation. If multiple different address spaces are specified in template definition and<br>
-instantiation compilation of such program will fail with a diagnostic.<br>
+It is not legal to specify multiple different address spaces between template<br>
+definition and instantiation. If multiple different address spaces are specified in<br>
+template definition and instantiation, compilation of such a program will fail with<br>
+a diagnostic.<br>
<br>
.. code-block:: c++<br>
<br>
@@ -1832,11 +1838,12 @@ instantiation compilation of such progra<br>
}<br>
<br>
void bar() {<br>
- foo<__global int>(); // error: conflicting address space qualifiers are provided __global<br>
- // and __private<br>
+ foo<__global int>(); // error: conflicting address space qualifiers are provided<br>
+ // __global and __private<br>
}<br>
<br>
-Once template is instantiated regular restrictions for address spaces will apply.<br>
+Once a template has been instantiated, regular restrictions for address spaces will<br>
+apply.<br>
<br>
.. code-block:: c++<br>
<br>
@@ -1846,15 +1853,15 @@ Once template is instantiated regular re<br>
}<br>
<br>
void bar(){<br>
- foo<__global int>(); // error: function scope variable cannot be declared in __global<br>
- // address space<br>
+ foo<__global int>(); // error: function scope variable cannot be declared in<br>
+ // __global address space<br>
}<br>
<br>
**Temporary materialization**<br>
<br>
-All temporaries are materialized in ``__private`` address space. If a reference with some<br>
-other address space is bound to them, the conversion will be generated in case it's valid<br>
-otherwise compilation will fail with a diagnostic.<br>
+All temporaries are materialized in the ``__private`` address space. If a<br>
+reference with another address space is bound to them, the conversion will be<br>
+generated in case it is valid, otherwise compilation will fail with a diagnostic.<br>
<br>
.. code-block:: c++<br>
<br>
@@ -1878,26 +1885,29 @@ TODO<br>
Constructing and destroying global objects<br>
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^<br>
<br>
-Global objects are constructed before the first kernel using the global<br>
+Global objects must be constructed before the first kernel using the global<br>
objects is executed and destroyed just after the last kernel using the<br>
program objects is executed. In OpenCL v2.0 drivers there is no specific<br>
API for invoking global constructors. However, an easy workaround would be<br>
-to enqueue constructor initialization kernel that has a name<br>
+to enqueue a constructor initialization kernel that has a name<br>
``@_GLOBAL__sub_I_<compiled file name>``. This kernel is only present if there<br>
are any global objects to be initialized in the compiled binary. One way to<br>
check this is by passing ``CL_PROGRAM_KERNEL_NAMES`` to ``clGetProgramInfo``<br>
(OpenCL v2.0 s5.8.7).<br>
<br>
-Note that if multiple files are compiled and linked into libraries multiple<br>
+Note that if multiple files are compiled and linked into libraries, multiple<br>
kernels that initialize global objects for multiple modules would have to be<br>
invoked.<br>
<br>
+Applications are currently required to run initialization of global objects<br>
+manually before running any kernels in which the objects are used.<br>
+<br>
.. code-block:: console<br>
<br>
clang -cl-std=clc++ test.cl<br>
<br>
-If there are any global objects to be initialized the final binary will<br>
-contain ``@_GLOBAL__sub_I_test.cl`` kernel to be enqueued.<br>
+If there are any global objects to be initialized, the final binary will<br>
+contain the ``@_GLOBAL__sub_I_test.cl`` kernel to be enqueued.<br>
<br>
Global destructors can not be invoked in OpenCL v2.0 drivers. However, all<br>
memory used for program scope objects is released on ``clReleaseProgram``.<br>
<br>
Modified: cfe/trunk/docs/UsersManual.rst<br>
URL: <a href="http://llvm.org/viewvc/llvm-project/cfe/trunk/docs/UsersManual.rst?rev=369749&r1=369748&r2=369749&view=diff">
http://llvm.org/viewvc/llvm-project/cfe/trunk/docs/UsersManual.rst?rev=369749&r1=369748&r2=369749&view=diff</a><br>
==============================================================================<br>
--- cfe/trunk/docs/UsersManual.rst (original)<br>
+++ cfe/trunk/docs/UsersManual.rst Fri Aug 23 04:43:49 2019<br>
@@ -2408,8 +2408,8 @@ Compiling to bitcode can be done as foll<br>
This will produce a generic test.bc file that can be used in vendor toolchains<br>
to perform machine code generation.<br>
<br>
-Clang currently supports OpenCL C language standards up to v2.0. Starting from Clang9<br>
-C++ mode is available for OpenCL (see :ref:`C++ for OpenCL <opencl_cpp>`).<br>
+Clang currently supports OpenCL C language standards up to v2.0. Starting from<br>
+clang 9 a C++ mode is available for OpenCL (see :ref:`C++ for OpenCL <opencl_cpp>`).<br>
<br>
OpenCL Specific Options<br>
-----------------------<br>
@@ -2773,21 +2773,22 @@ There are some standard OpenCL functions<br>
C++ for OpenCL<br>
--------------<br>
<br>
-Starting from Clang9 kernel code can contain C++17 features: classes, templates,<br>
+Starting from clang 9 kernel code can contain C++17 features: classes, templates,<br>
function overloading, type deduction, etc. Please note that this is not an<br>
implementation of `OpenCL C++<br>
<<a href="https://www.khronos.org/registry/OpenCL/specs/2.2/pdf/OpenCL_Cxx.pdf">https://www.khronos.org/registry/OpenCL/specs/2.2/pdf/OpenCL_Cxx.pdf</a>>`_ and<br>
there is no plan to support it in clang in any new releases in the near future.<br>
<br>
-There are only a few restrictions on allowed C++ features. For detailed information<br>
-please refer to documentation on Extensions (:doc:`LanguageExtensions`).<br>
+For detailed information about restrictions to allowed C++ features please<br>
+refer to :doc:`LanguageExtensions`.<br>
<br>
Since C++ features are to be used on top of OpenCL C functionality, all existing<br>
restrictions from OpenCL C v2.0 will inherently apply. All OpenCL C builtin types<br>
-and function libraries are supported and can be used in the new mode.<br>
+and function libraries are supported and can be used in this mode.<br>
<br>
-To enable the new mode pass the following command line option when compiling ``.cl``<br>
-file ``-cl-std=clc++``, ``-cl-std=CLC++``, ``-std=clc++`` or ``-std=CLC++``.<br>
+To enable the C++ for OpenCL mode, pass one of following command line options when<br>
+compiling ``.cl`` file ``-cl-std=clc++``, ``-cl-std=CLC++``, ``-std=clc++`` or<br>
+``-std=CLC++``.<br>
<br>
.. code-block:: c++<br>
<br>
<br>
<br>
_______________________________________________<br>
cfe-commits mailing list<br>
cfe-commits@lists.llvm.org<br>
<a href="https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits">https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits</a><br>
</div>
</span></font></div>
</div>
</div>
</body>
</html>