Yes, r370031. Thanks, Hans
On Tue, Aug 27, 2019 at 11:43 AM Anastasia Stulova <anastasia.stul...@arm.com> wrote: > > Hi Hans, > > > Can this be merged to the release, please? > > > Thank you, > > Anastasia > > > > ________________________________ > From: cfe-commits <cfe-commits-boun...@lists.llvm.org> on behalf of Anastasia > Stulova via cfe-commits <cfe-commits@lists.llvm.org> > Sent: 23 August 2019 12:43 > To: cfe-commits@lists.llvm.org <cfe-commits@lists.llvm.org> > Subject: r369749 - [Docs][OpenCL] Several corrections to C++ for OpenCL > > Author: stulova > Date: Fri Aug 23 04:43:49 2019 > New Revision: 369749 > > URL: http://llvm.org/viewvc/llvm-project?rev=369749&view=rev > Log: > [Docs][OpenCL] Several corrections to C++ for OpenCL > > Differential Revision:https://reviews.llvm.org/D64418 > > > Modified: > cfe/trunk/docs/LanguageExtensions.rst > cfe/trunk/docs/UsersManual.rst > > Modified: cfe/trunk/docs/LanguageExtensions.rst > URL: > http://llvm.org/viewvc/llvm-project/cfe/trunk/docs/LanguageExtensions.rst?rev=369749&r1=369748&r2=369749&view=diff > ============================================================================== > --- cfe/trunk/docs/LanguageExtensions.rst (original) > +++ cfe/trunk/docs/LanguageExtensions.rst Fri Aug 23 04:43:49 2019 > @@ -1640,8 +1640,8 @@ 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 > +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 @@ 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++ > @@ -1667,20 +1668,24 @@ 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 > +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 @@ Address spaces are not deduced for: > - 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 @@ TODO: Add example for type alias and dec > > **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 @@ rules from address space pointer convers > **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 specified using > address > +space qualifiers on member functions > (see :ref:`Member function qualifier <opencl_cpp_addrspace_method_qual>`) as > the > conversion between ``__constant`` and ``__generic`` is disallowed. Member > function > -qualifiers can also be used in case conversion to ``__generic`` address > space is > -undesirable (even if it is legal), for example to take advantage of memory > bank > -accesses. Note this not only applies to regular member functions but to > -constructors and destructors too. > +qualifiers can also be used in case conversion to the ``__generic`` address > space > +is undesirable (even if it is legal). For example, a method can be > implemented to > +exploit memory access coalescing for segments with memory bank. This not only > +applies to regular member functions but to constructors and destructors too. > > .. _opencl_cpp_addrspace_method_qual: > > **Member function qualifier** > > -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 > -works just the same as qualifying member functions with ``const`` or any > other > -qualifiers. The overloading resolution will select 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 > +Clang allows specifying an address space qualifier on member functions to > signal > +that they are to be used with objects constructed in some specific address > space. > +This works just the same as qualifying member functions with ``const`` or any > +other qualifiers. The overloading resolution will select the candidate with > the > +most specific address space if multiple candidates are provided. If there is > no > +conversion to an address space among candidates, compilation will fail with a > diagnostic. > > .. code-block:: c++ > @@ -1782,7 +1787,7 @@ diagnostic. > **Implicit special members** > > All implicit special members (default, copy, or move constructor, copy or > move > -assignment, destructor) will be generated with ``__generic`` address space. > +assignment, destructor) will be generated with the ``__generic`` address > space. > > .. code-block:: c++ > > @@ -1797,15 +1802,15 @@ assignment, destructor) will be generate > > **Builtin operators** > > -All builtin operators are available in the specific address spaces, thus no > conversion > -to ``__generic`` is performed. > +All builtin operators are available in the specific address spaces, thus no > +conversion to ``__generic`` is performed. > > **Templates** > > -There is no deduction of address spaces in non-pointer/non-reference > template parameters > -and dependent types (see :ref:`Deduction <opencl_cpp_addrsp_deduction>`). > The address > -space of template parameter is deduced during the type deduction if it's not > explicitly > -provided in instantiation. > +There is no deduction of address spaces in non-pointer/non-reference template > +parameters and dependent types (see :ref:`Deduction > <opencl_cpp_addrsp_deduction>`). > +The address space of a template parameter is deduced during type deduction if > +it is not explicitly provided in the instantiation. > > .. code-block:: c++ > > @@ -1816,13 +1821,14 @@ provided in instantiation. > 5 > 6 __global int g; > 7 void bar(){ > - 8 foo(&g); // error: template instantiation failed as function scope > variable appears to > - 9 // be declared in __global address space (see line 3) > + 8 foo(&g); // error: template instantiation failed as function scope > variable > + 9 // appears to be declared in __global address space (see line > 3) > 10 } > > -It is not legal to specify multiple different address spaces between > template definition and > -instantiation. If multiple different address spaces are specified in > template definition and > -instantiation compilation of such program will fail with a diagnostic. > +It is not legal to specify multiple different address spaces between template > +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. > > .. code-block:: c++ > > @@ -1832,11 +1838,12 @@ instantiation compilation of such progra > } > > void bar() { > - foo<__global int>(); // error: conflicting address space qualifiers are > provided __global > - // and __private > + foo<__global int>(); // error: conflicting address space qualifiers are > provided > + // __global and __private > } > > -Once template is instantiated regular restrictions for address spaces will > apply. > +Once a template has been instantiated, regular restrictions for address > spaces will > +apply. > > .. code-block:: c++ > > @@ -1846,15 +1853,15 @@ Once template is instantiated regular re > } > > void bar(){ > - foo<__global int>(); // error: function scope variable cannot be > declared in __global > - // address space > + foo<__global int>(); // error: function scope variable cannot be > declared in > + // __global address space > } > > **Temporary materialization** > > -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. > +All temporaries are materialized in the ``__private`` address space. If a > +reference with another address space is bound to them, the conversion will be > +generated in case it is valid, otherwise compilation will fail with a > diagnostic. > > .. code-block:: c++ > > @@ -1878,26 +1885,29 @@ TODO > Constructing and destroying global objects > ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ > > -Global objects are constructed before the first kernel using the global > +Global objects must be 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 > +to enqueue a constructor initialization kernel that has a name > ``@_GLOBAL__sub_I_<compiled file name>``. This kernel is only present if > there > are any global objects to be initialized in the compiled binary. One way to > check this is by passing ``CL_PROGRAM_KERNEL_NAMES`` to ``clGetProgramInfo`` > (OpenCL v2.0 s5.8.7). > > -Note that if multiple files are compiled and linked into libraries multiple > +Note that if multiple files are compiled and linked into libraries, multiple > kernels that initialize global objects for multiple modules would have to be > invoked. > > +Applications are currently required to run initialization of global objects > +manually before running any kernels in which the objects are used. > + > .. code-block:: console > > clang -cl-std=clc++ test.cl > > -If there are any global objects to be initialized the final binary will > -contain ``@_GLOBAL__sub_I_test.cl`` kernel to be enqueued. > +If there are any global objects to be initialized, the final binary will > +contain the ``@_GLOBAL__sub_I_test.cl`` kernel to be enqueued. > > Global destructors can not be invoked in OpenCL v2.0 drivers. However, all > memory used for program scope objects is released on ``clReleaseProgram``. > > Modified: cfe/trunk/docs/UsersManual.rst > URL: > http://llvm.org/viewvc/llvm-project/cfe/trunk/docs/UsersManual.rst?rev=369749&r1=369748&r2=369749&view=diff > ============================================================================== > --- cfe/trunk/docs/UsersManual.rst (original) > +++ cfe/trunk/docs/UsersManual.rst Fri Aug 23 04:43:49 2019 > @@ -2408,8 +2408,8 @@ Compiling to bitcode can be done as foll > 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. Starting > from Clang9 > -C++ mode is available for OpenCL (see :ref:`C++ for OpenCL <opencl_cpp>`). > +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_cpp>`). > > OpenCL Specific Options > ----------------------- > @@ -2773,21 +2773,22 @@ There are some standard OpenCL functions > C++ for OpenCL > -------------- > > -Starting from Clang9 kernel code can contain C++17 features: classes, > templates, > +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++ > <https://www.khronos.org/registry/OpenCL/specs/2.2/pdf/OpenCL_Cxx.pdf>`_ 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`). > +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 the new mode. > +and function libraries are supported and can be used in this 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++``. > +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++ > > > > _______________________________________________ > cfe-commits mailing list > cfe-commits@lists.llvm.org > https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits _______________________________________________ cfe-commits mailing list cfe-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits