[OpenCL][Docs] Describe internals of TableGen BIFs

[svenvh]

Summary

Add a high level explanation of the -fdeclare-opencl-builtins option.

[Anastasia]

Ok, this looks like a good start. Later we can add a bit more information/guidance on how to add new function specifically how to specify parameter or return types, overloads, and attributes.

clang/docs/OpenCLSupport.rst

142

I suggest to elaborate why it needs modifying i.e. add new function declarations.

clang/docs/OpenCLSupport.rst

.. 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:
+
+- 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
+  and functions that capture the builtin function data from the TableGen
+  definitions in a compact manner.
+
+- OpenCL specific code in ``SemaLookup.cpp``.  When ``Sema::LookupBuiltin``
+  encounters a potential builtin function, it will check if the name corresponds
+  to a valid OpenCL builtin function.  If so, all overloads of the function are
+  inserted using ``InsertOCLBuiltinDeclarationsFromTable`` and overload
+  resolution takes place.
+
 .. _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

 =====================
 
 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``