[OpenCL][Docs] Change decription for the OpenCL standard headers

[Anastasia]

Summary

After updating the user interface (https://reviews.llvm.org/D96515), make sure the doc reflects the change.

[svenvh]

clang/docs/OpenCLSupport.rst

67

123

"are" or "can be"?

clang/docs/UsersManual.rst

2942

2943

2949

Maybe include the error output from running this as well, because otherwise a hasty reader might assume this command should work?

3019–3020

I wonder if we need to keep this example? You're not referring to it from the text and it's not demonstrating any special flags anymore.

[Anastasia]

Added corrections from Sven.

clang/docs/UsersManual.rst

3019–3020

it's still demonstrating the use of default clang driver invocation i.e. there are no flags needed to compile the code that uses BIFs.

[svenvh]

LGTM!

clang/docs/UsersManual.rst

3019–3020

Okay, if you want to make that explicit then I would suggest to add a line like:

The following example shows how an OpenCL program that calls various standard builtin functions can be compiled without the need for any explicit includes or compiler flags.

[Anastasia]

clang/docs/UsersManual.rst

3019–3020

Ok, good idea. I will add this in my final commit.

clang/docs/OpenCLSupport.rst

 <https://www.khronos.org/registry/spir/specs/spir_spec-2.0.pdf#18>`_
 
 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
 
 Disables support of OpenCL extensions. All OpenCL targets provide a list
 of extensions that they support. Clang allows to amend this using the ``-cl-ext``
 flag with a comma-separated list of extensions prefixed with ``'+'`` or ``'-'``.
 The syntax: ``-cl-ext=<(['-'|'+']<extension>[,])+>``,  where extensions
 can be either one of `the OpenCL published extensions
 <https://www.khronos.org/registry/OpenCL>`_
 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
 
      $ clang -cc1 -triple spir64-unknown-unknown -cl-ext=-cl_khr_fp64 test.cl
 
 Enabling all extensions except double support in R600 AMD GPU can be done using:
 
    .. code-block:: console
 
      $ 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
 
 Overrides the target address space map with a fake map.
 This allows adding explicit address space IDs to the bitcode for non-segmented
 memory architectures that do not have separate IDs for each of the OpenCL
 logical address spaces by default. Passing ``-ffake-address-space-map`` will
 add/override address spaces of the target compiled for with the following values:
 ``1-global``, ``2-constant``, ``3-local``, ``4-generic``. The private address
 space is represented by the absence of an address space attribute in the IR (see
 also :ref:`the section on the address space attribute <opencl_addrsp>`).
 
    .. code-block:: console
 
      $ 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
 ---------------
 
 **Clang builtins**
 
 There are some standard OpenCL functions that are implemented as Clang builtins:
 
 - All pipe functions from `section 6.13.16.2/6.13.16.3
   <https://www.khronos.org/registry/cl/specs/opencl-2.0-openclc.pdf#160>`_ of
   the OpenCL v2.0 kernel language specification.
 
 - Address space qualifier conversion functions ``to_global``/``to_local``/``to_private``
   from `section 6.13.9
   <https://www.khronos.org/registry/cl/specs/opencl-2.0-openclc.pdf#101>`_.
 
 - All the ``enqueue_kernel`` functions from `section 6.13.17.1
   <https://www.khronos.org/registry/cl/specs/opencl-2.0-openclc.pdf#164>`_ and
   enqueue query functions from `section 6.13.17.5
   <https://www.khronos.org/registry/cl/specs/opencl-2.0-openclc.pdf#171>`_.
 
 **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
   function declarations, this is normally the only file that needs modifying.
 
 - A Clang TableGen emitter defined in ``ClangOpenCLBuiltinEmitter.cpp``.  During
   Clang build time, the emitter reads the TableGen definition file and
   generates ``OpenCLBuiltins.inc``.  This generated file contains various tables

 =====================
 
 Clang provides the following new WIP features for the developers to experiment
 and provide early feedback or contribute with further improvements.
 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
 ------------------------
 
 There is ongoing work to support C++ standard libraries from `LLVM's libcxx
 <https://libcxx.llvm.org/>`_ in OpenCL kernel code using C++ for OpenCL mode.
 
 It is currently possible to include `type_traits` from C++17 in the kernel
 sources when the following clang extensions are enabled

clang/docs/UsersManual.rst

.. code-block:: console
      $ clang -cl-std=CL2.0 -cl-single-precision-constant test.cl
 
 
 Many flags used for the compilation for C sources can also be passed while
 compiling for OpenCL, examples: ``-c``, ``-O<1-4|s>``, ``-o``, ``-emit-llvm``, etc.
 
 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
 --------------
 
 OpenCL targets are derived from the regular Clang target classes. The OpenCL
 specific parts of the target representation provide address space mapping as
 well as a set of supported extensions.
 

 
 - SPIR is available as a generic target to allow portable bitcode to be produced
   that can be used across GPU toolchains. The implementation follows `the SPIR
   specification <https://www.khronos.org/spir>`_. There are two flavors
   available for 32 and 64 bits.
 
    .. 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
   for OpenCL v2.0 or C++ for OpenCL.
 
 - x86 is used by some implementations that are x86 compatible and currently
   remains for backwards compatibility (with older implementations prior to
   SPIR target support). For "non-SPMD" targets which cannot spawn multiple
   work-items on the fly using hardware, which covers practically all non-GPU
   devices such as CPUs and DSPs, additional processing is needed for the kernels
   to support multiple work-item execution. For this, a 3rd party toolchain,
   such as for example `POCL <http://portablecl.org/>`_, can be used.
 
   This target does not support multiple memory segments and, therefore, the fake
   address space map can be added using the :ref:`-ffake-address-space-map
   <opencl_fake_address_space_map>` flag.
 
 .. _opencl_header:
 
 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>`.
+
+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
 
      $ 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=<path to the generated module> 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
 -----------------
 
 Most of the ``cl_khr_*`` extensions to OpenCL C from `the official OpenCL
 registry <https://www.khronos.org/registry/OpenCL/>`_ are available and
 configured per target depending on the support available in the specific
 architecture.