Index: clang/docs/OpenCLSupport.rst =================================================================== --- clang/docs/OpenCLSupport.rst +++ clang/docs/OpenCLSupport.rst @@ -63,6 +63,10 @@ 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 @@ 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 @@ $ 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`) are 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 @@ $ 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 --------------- @@ -239,28 +296,6 @@ `_ or via `Bugzilla `__. -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 ------------------------ Index: clang/docs/UsersManual.rst =================================================================== --- clang/docs/UsersManual.rst +++ clang/docs/UsersManual.rst @@ -2934,35 +2934,20 @@ 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 declaration from the +OpenCL standard won't be accessible i.e. the following example 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 -More options are documented in :doc:`OpenCLSupport`. +More information about the standard types and functions is provided in :ref:``. OpenCL Targets -------------- @@ -2999,11 +2984,8 @@ .. 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 +3008,17 @@ 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:``. .. 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: - - .. code-block:: console - - $ clang -target spir-unknown-unknown -c -emit-llvm -Xclang -finclude-default-header -fmodules -fimplicit-module-maps -fmodules-cache-path= 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 -----------------