[OpenCL][Docs] Moved information about internals from UsersManual into OpenCLSupport

[Anastasia]

Summary

Moved information detailing the implementation from UsersManual into OpenCLSupport page as it is not relevant to the user's of clang but primarily needed for the compiler developers.

[svenvh]

Please build the docs and check the build log, as you might break some references?

clang/docs/UsersManual.rst

3008

Is this a dead reference now that you moved it to a different file?

3019

Is this a dead reference now that you moved it to a different file?

[Anastasia]

clang/docs/UsersManual.rst

3008

It is moved to another doc but the labels are globally visible.

[svenvh]

LGTM then, thanks!

clang/docs/UsersManual.rst

3008

Cool, I wasn't expecting that.

clang/docs/OpenCLSupport.rst

 
 There is an ongoing work to support :ref:`OpenCL 3.0 <opencl_300>`.
 
 There are also other :ref:`new and experimental features <opencl_experimenal>` available.
 
 For general issues and bugs with OpenCL in clang refer to `Bugzilla
 <https://bugs.llvm.org/buglist.cgi?component=OpenCL&list_id=172679&product=clang&resolution=--->`__.
 
+Internals Manual
+================
+
+This section acts as internal documentation for OpenCL features design
+as well as some important implementation aspects. It is primarily targeted
+at the advanced users and the toolchain developers integrating frontend
+functionality as a component.
+
+OpenCL Metadata
+---------------
+
+Clang uses metadata to provide additional OpenCL semantics in IR needed for
+backends and OpenCL runtime.
+
+Each kernel will have function metadata attached to it, specifying the arguments.
+Kernel argument metadata is used to provide source level information for querying
+at runtime, for example using the `clGetKernelArgInfo 
+<https://www.khronos.org/registry/OpenCL/specs/opencl-1.2.pdf#167>`_
+call.
+
+Note that ``-cl-kernel-arg-info`` enables more information about the original
+kernel code to be added e.g. kernel parameter names will appear in the OpenCL
+metadata along with other information. 
+
+The IDs used to encode the OpenCL's logical address spaces in the argument info
+metadata follows the SPIR address space mapping as defined in the SPIR
+specification `section 2.2
+<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.
+
+.. _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_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
+---------------
+
+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>`_.
+
+.. _opencl_addrsp:
+
+Address spaces attribute
+------------------------
+
+Clang has arbitrary address space support using the ``address_space(N)``
+attribute, where ``N`` is an integer number in the range specified in the
+Clang source code. This addresses spaces can be used along with the OpenCL
+address spaces however when such addresses spaces converted to/from OpenCL
+address spaces the behavior is not governed by OpenCL specification.
+
+An OpenCL implementation provides a list of standard address spaces using
+keywords: ``private``, ``local``, ``global``, and ``generic``. In the AST and
+in the IR each of the address spaces will be represented by unique number
+provided in the Clang source code. The specific IDs for an address space do not
+have to match between the AST and the IR. Typically in the AST address space
+numbers represent logical segments while in the IR they represent physical
+segments.
+Therefore, machines with flat memory segments can map all AST address space
+numbers to the same physical segment ID or skip address space attribute
+completely while generating the IR. However, if the address space information
+is needed by the IR passes e.g. to improve alias analysis, it is recommended
+to keep it and only lower to reflect physical memory segments in the late
+machine passes. The mapping between logical and target address spaces is
+specified in the Clang's source code.
+
 .. _cxx_for_opencl_impl:
 
 C++ for OpenCL Implementation Status
 ====================================
 
 Clang implements language version 1.0 published in `the official
 release of C++ for OpenCL Documentation
 <https://github.com/KhronosGroup/OpenCL-Docs/releases/tag/cxxforopencl-v1.0-r1>`_.

clang/docs/UsersManual.rst

 <https://www.khronos.org/registry/cl/specs/opencl-2.0.pdf#200>`_ are available.
 
 Examples:
 
    .. 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
 
 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
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.
 
-.. _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_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``.
-
-Some other flags used for the compilation for C can also be passed while
-compiling for OpenCL, examples: ``-c``, ``-O<1-4|s>``, ``-o``, ``-emit-llvm``, etc.
+More options are documented in :doc:`OpenCLSupport`.
 
 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.
 
- x86 is used by some implementations that are x86 compatible and currently
   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. 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).
+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).
 
    .. 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

 It is therefore recommended that the identifiers are prefixed with a
 double underscore to avoid clashing with user space identifiers. Vendor
 extension should use reserved identifier prefix e.g. amd, arm, intel.
 
 Clang also supports language extensions documented in `The OpenCL C Language
 Extensions Documentation
 <https://github.com/KhronosGroup/Khronosdotorg/blob/master/api/opencl/assets/OpenCL_LangExt.pdf>`_.
 
-OpenCL Metadata
----------------
-
-Clang uses metadata to provide additional OpenCL semantics in IR needed for
-backends and OpenCL runtime.
-
-Each kernel will have function metadata attached to it, specifying the arguments.
-Kernel argument metadata is used to provide source level information for querying
-at runtime, for example using the `clGetKernelArgInfo 
-<https://www.khronos.org/registry/OpenCL/specs/opencl-1.2.pdf#167>`_
-call.
-
-Note that ``-cl-kernel-arg-info`` enables more information about the original CL
-code to be added e.g. kernel parameter names will appear in the OpenCL metadata
-along with other information. 
-
-The IDs used to encode the OpenCL's logical address spaces in the argument info
-metadata follows the SPIR address space mapping as defined in the SPIR
-specification `section 2.2
-<https://www.khronos.org/registry/spir/specs/spir_spec-2.0.pdf#18>`_
-
 OpenCL-Specific Attributes
 --------------------------
 
 OpenCL support in Clang contains a set of attribute taken directly from the
 specification as well as additional attributes.
 
 See also :doc:`AttributeReference`.
 

 
 while using ``noduplicate`` would disallow this. Also ``noduplicate`` doesn't
 have the same safe semantics of CFG as ``convergent`` and can cause changes in
 CFG that modify semantics of the original program.
 
 ``noduplicate`` is kept for backwards compatibility only and it considered to be
 deprecated for future uses.
 
-.. _opencl_addrsp:
-
-address_space
-^^^^^^^^^^^^^
-
-Clang has arbitrary address space support using the ``address_space(N)``
-attribute, where ``N`` is an integer number in the range ``0`` to ``16777215``
-(``0xffffffu``).
-
-An OpenCL implementation provides a list of standard address spaces using
-keywords: ``private``, ``local``, ``global``, and ``generic``. In the AST and
-in the IR local, global, or generic will be represented by the address space
-attribute with the corresponding unique number. Note that private does not have
-any corresponding attribute added and, therefore, is represented by the absence
-of an address space number. The specific IDs for an address space do not have to
-match between the AST and the IR. Typically in the AST address space numbers
-represent logical segments while in the IR they represent physical segments.
-Therefore, machines with flat memory segments can map all AST address space
-numbers to the same physical segment ID or skip address space attribute
-completely while generating the IR. However, if the address space information
-is needed by the IR passes e.g. to improve alias analysis, it is recommended
-to keep it and only lower to reflect physical memory segments in the late
-machine passes.
-
-OpenCL 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>`_.
-
 .. _cxx_for_opencl:
 
 C++ for OpenCL
 --------------
 
 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++