diff --git a/clang/docs/OpenCLSupport.rst b/clang/docs/OpenCLSupport.rst index 266fde3436d301..02522052e1061b 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 `): + + .. 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/lib/Headers/opencl-c.h test.cl + $ clang -I/lib/clang//include/opencl-c.h/opencl-c.h test.cl + +In this example it is assumed that the kernel code contains +``#include `` 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= test.cl + +Another way to circumvent long parsing latency for the OpenCL builtin +declarations is to use mechanism enabled by :ref:`-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 `, 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 `). $ 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 `) consists of the -following main components: +:ref:`-fdeclare-opencl-builtins option `) 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 `_ or via `Bugzilla `__. -.. _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 dfc0ea29487eaa..6f593cab8f1a08 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 `): +.. 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/lib/Headers/opencl-c.h test.cl - $ clang -I/lib/clang//include/opencl-c.h/opencl-c.h test.cl - -In this example it is assumed that the kernel code contains -``#include `` 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 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 ` 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 `. - .. 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= 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 -----------------