[clang] 90355d6 - [OpenCL][Docs] Change description for the OpenCL standard headers.
Anastasia Stulova via cfe-commits
cfe-commits at lists.llvm.org
Tue Feb 23 03:49:35 PST 2021
Author: Anastasia Stulova
Date: 2021-02-23T11:49:05Z
New Revision: 90355d6f10765d03af1bfcc1ab3d17e8cae330f1
URL: https://github.com/llvm/llvm-project/commit/90355d6f10765d03af1bfcc1ab3d17e8cae330f1
DIFF: https://github.com/llvm/llvm-project/commit/90355d6f10765d03af1bfcc1ab3d17e8cae330f1.diff
LOG: [OpenCL][Docs] Change description for the OpenCL standard headers.
After updating the user interface in D96515, update the docs
reflecting the new approach.
Tags: #clang
Differential Revision: https://reviews.llvm.org/D96616
Added:
Modified:
clang/docs/OpenCLSupport.rst
clang/docs/UsersManual.rst
Removed:
################################################################################
diff --git a/clang/docs/OpenCLSupport.rst b/clang/docs/OpenCLSupport.rst
index 266fde3436d3..02522052e106 100644
--- a/clang/docs/OpenCLSupport.rst
+++ b/clang/docs/OpenCLSupport.rst
@@ -63,6 +63,10 @@ OpenCL Specific Options
In addition to the options described in :doc:`UsersManual` there are the
following options specific to the OpenCL frontend.
+All the options in this section are frontend-only and therefore if used
+with regular clang driver they require frontend forwarding, e.g. ``-cc1``
+or ``-Xclang``.
+
.. _opencl_cl_ext:
.. option:: -cl-ext
@@ -76,9 +80,6 @@ can be either one of `the OpenCL published extensions
or any vendor extension. Alternatively, ``'all'`` can be used to enable
or disable all known extensions.
-Note that this is a frontend-only flag and therefore it requires the use of
-flags that forward options to the frontend e.g. ``-cc1`` or ``-Xclang``.
-
Example disabling double support for the 64-bit SPIR target:
.. code-block:: console
@@ -91,6 +92,65 @@ Enabling all extensions except double support in R600 AMD GPU can be done using:
$ clang -cc1 -triple r600-unknown-unknown -cl-ext=-all,+cl_khr_fp16 test.cl
+.. _opencl_finclude_default_header:
+
+.. option:: -finclude-default-header
+
+Adds most of builtin types and function declarations during compilations. By
+default the OpenCL headers are not loaded by the frontend and therefore certain
+builtin types and most of builtin functions are not declared. To load them
+automatically this flag can be passed to the frontend (see also :ref:`the
+section on the OpenCL Header <opencl_header>`):
+
+ .. code-block:: console
+
+ $ clang -Xclang -finclude-default-header test.cl
+
+Alternatively the internal header `opencl-c.h` containing the declarations
+can be included manually using ``-include`` or ``-I`` followed by the path
+to the header location. The header can be found in the clang source tree or
+installation directory.
+
+ .. code-block:: console
+
+ $ clang -I<path to clang sources>/lib/Headers/opencl-c.h test.cl
+ $ clang -I<path to clang installation>/lib/clang/<llvm version>/include/opencl-c.h/opencl-c.h test.cl
+
+In this example it is assumed that the kernel code contains
+``#include <opencl-c.h>`` just as a regular C include.
+
+Because the header is very large and long to parse, PCH (:doc:`PCHInternals`)
+and modules (:doc:`Modules`) can be used internally to improve the compilation
+speed.
+
+To enable modules for OpenCL:
+
+ .. code-block:: console
+
+ $ clang -target spir-unknown-unknown -c -emit-llvm -Xclang -finclude-default-header -fmodules -fimplicit-module-maps -fm odules-cache-path=<path to the generated module> test.cl
+
+Another way to circumvent long parsing latency for the OpenCL builtin
+declarations is to use mechanism enabled by :ref:`-fdeclare-opencl-builtins
+<opencl_fdeclare_opencl_builtins>` flag that is available as an alternative
+feature.
+
+.. _opencl_fdeclare_opencl_builtins:
+
+.. option:: -fdeclare-opencl-builtins
+
+In addition to regular header includes with builtin types and functions using
+:ref:`-finclude-default-header <opencl_finclude_default_header>`, clang
+supports a fast mechanism to declare builtin functions with
+``-fdeclare-opencl-builtins``. This does not declare the builtin types and
+therefore it has to be used in combination with ``-finclude-default-header``
+if full functionality is required.
+
+**Example of Use**:
+
+ .. code-block:: console
+
+ $ clang -Xclang -fdeclare-opencl-builtins test.cl
+
.. _opencl_fake_address_space_map:
.. option:: -ffake-address-space-map
@@ -108,9 +168,6 @@ also :ref:`the section on the address space attribute <opencl_addrsp>`).
$ clang -cc1 -ffake-address-space-map test.cl
-Note that this is a frontend-only flag and therefore it requires the use of
-flags that forward options to the frontend e.g. ``-cc1`` or ``-Xclang``.
-
OpenCL builtins
---------------
@@ -134,8 +191,8 @@ There are some standard OpenCL functions that are implemented as Clang builtins:
**Fast builtin function declarations**
The implementation of the fast builtin function declarations (available via the
-:ref:`-fdeclare-opencl-builtins option <opencl_fast_builtins>`) consists of the
-following main components:
+:ref:`-fdeclare-opencl-builtins option <opencl_fdeclare_opencl_builtins>`) consists
+of the following main components:
- A TableGen definitions file ``OpenCLBuiltins.td``. This contains a compact
representation of the supported builtin functions. When adding new builtin
@@ -263,30 +320,6 @@ Feel free to contact us on `cfe-dev
<https://lists.llvm.org/mailman/listinfo/cfe-dev>`_ or via `Bugzilla
<https://bugs.llvm.org/>`__.
-.. _opencl_fast_builtins:
-
-Fast builtin function declarations
-----------------------------------
-
-In addition to regular header includes with builtin types and functions using
-``-finclude-default-header`` explained in :doc:`UsersManual`, clang
-supports a fast mechanism to declare builtin functions with
-``-fdeclare-opencl-builtins``. This does not declare the builtin types and
-therefore it has to be used in combination with ``-finclude-default-header``
-if full functionality is required.
-
-**Example of Use**:
-
- .. code-block:: console
-
- $ clang -Xclang -fdeclare-opencl-builtins test.cl
-
-Note that this is a frontend-only flag and therefore it requires the use of
-flags that forward options to the frontend, e.g. ``-cc1`` or ``-Xclang``.
-
-As this feature is still in experimental phase some changes might still occur
-on the command line interface side.
-
C++ libraries for OpenCL
------------------------
diff --git a/clang/docs/UsersManual.rst b/clang/docs/UsersManual.rst
index dfc0ea29487e..6f593cab8f1a 100644
--- a/clang/docs/UsersManual.rst
+++ b/clang/docs/UsersManual.rst
@@ -2934,35 +2934,24 @@ compiling for OpenCL, examples: ``-c``, ``-O<1-4|s>``, ``-o``, ``-emit-llvm``, e
Some extra options are available to support special OpenCL features.
-.. option:: -finclude-default-header
+.. _opencl_cl_no_stdinc:
-Adds most of builtin types and function declarations during compilations. By
-default the OpenCL headers are not loaded and therefore certain builtin
-types and most of builtin functions are not declared. To load them
-automatically this flag can be passed to the frontend (see also :ref:`the
-section on the OpenCL Header <opencl_header>`):
+.. option:: -cl-no-stdinc
- .. code-block:: console
-
- $ clang -Xclang -finclude-default-header test.cl
-
-Note that this is a frontend-only flag and therefore it requires the use of
-flags that forward options to the frontend, e.g. ``-cc1`` or ``-Xclang``.
-
-Alternatively the internal header `opencl-c.h` containing the declarations
-can be included manually using ``-include`` or ``-I`` followed by the path
-to the header location. The header can be found in the clang source tree or
-installation directory.
+Allows to disable all extra types and functions that are not native to the compiler.
+This might reduce the compilation speed marginally but many declarations from the
+OpenCL standard will not be accessible. For example, the following will fail to
+compile.
.. code-block:: console
- $ clang -I<path to clang sources>/lib/Headers/opencl-c.h test.cl
- $ clang -I<path to clang installation>/lib/clang/<llvm version>/include/opencl-c.h/opencl-c.h test.cl
-
-In this example it is assumed that the kernel code contains
-``#include <opencl-c.h>`` just as a regular C include.
+ $ echo "bool is_wg_uniform(int i){return get_enqueued_local_size(i)==get_local_size(i);}" > test.cl
+ $ clang -cl-std=CL2.0 -cl-no-stdinc test.cl
+ error: use of undeclared identifier 'get_enqueued_local_size'
+ error: use of undeclared identifier 'get_local_size'
-More options are documented in :doc:`OpenCLSupport`.
+More information about the standard types and functions is provided in :ref:`the
+section on the OpenCL Header <opencl_header>`.
OpenCL Targets
--------------
@@ -2999,11 +2988,8 @@ Generic Targets
.. code-block:: console
- $ clang -cc1 -triple=spir test.cl
- $ clang -cc1 -triple=spir64 test.cl
-
- Note that this is a frontend-only target and therefore it requires the use of
- flags that forward options to the frontend e.g. ``-cc1`` or ``-Xclang``.
+ $ clang -target spir test.cl -emit-llvm -c
+ $ clang -target spir64 test.cl -emit-llvm -c
All known OpenCL extensions are supported in the SPIR targets. Clang will
generate SPIR v1.2 compatible IR for OpenCL versions up to 2.0 and SPIR v2.0
@@ -3026,31 +3012,21 @@ Generic Targets
OpenCL Header
-------------
-By default Clang will not include standard headers and therefore OpenCL builtin
-functions and some types (i.e. vectors) are unknown during compilation. The
-default CL header is, however, provided in the Clang installation and can be
-enabled by passing the ``-finclude-default-header`` flag (see :ref:`flags
-description <opencl_cl_ext>` for more details).
+By default Clang will include standard headers and therefore most of OpenCL
+builtin functions and types are available during compilation. The
+default declarations of non-native compiler types and functions can be disabled
+by using flag :ref:`-cl-no-stdinc <opencl_cl_no_stdinc>`.
- .. code-block:: console
-
- $ echo "bool is_wg_uniform(int i){return get_enqueued_local_size(i)==get_local_size(i);}" > test.cl
- $ clang -Xclang -finclude-default-header -cl-std=CL2.0 test.cl
-
-Because the header is very large and long to parse, PCH (:doc:`PCHInternals`)
-and modules (:doc:`Modules`) are used internally to improve the compilation
-speed.
-
-To enable modules for OpenCL:
+The following example demonstrates that OpenCL kernel sources with various
+standard builtin functions can be compiled without the need for an explicit
+includes or compiler flags.
.. code-block:: console
- $ clang -target spir-unknown-unknown -c -emit-llvm -Xclang -finclude-default-header -fmodules -fimplicit-module-maps -fmodules-cache-path=<path to the generated module> test.cl
+ $ echo "bool is_wg_uniform(int i){return get_enqueued_local_size(i)==get_local_size(i);}" > test.cl
+ $ clang -cl-std=CL2.0 test.cl
-Another way to circumvent long parsing latency for the OpenCL builtin
-declarations is to use mechanism enabled by ``-fdeclare-opencl-builtins`` flag
-that is available as an experimental feature (see more information in
-:doc:`OpenCLSupport`).
+More information about the default headers is provided in :doc:`OpenCLSupport`.
OpenCL Extensions
-----------------
More information about the cfe-commits
mailing list