[clang] 18a7079 - [OpenCL][Docs] Describe internals of TableGen builtins

[Sven van Haastregt via cfe-commits]

Author: Sven van Haastregt
Date: 2021-02-12T09:56:32Z
New Revision: 18a70797e798ade57a3deb017692d4c47d12d6f0

URL: https://github.com/llvm/llvm-project/commit/18a70797e798ade57a3deb017692d4c47d12d6f0
DIFF: https://github.com/llvm/llvm-project/commit/18a70797e798ade57a3deb017692d4c47d12d6f0.diff

LOG: [OpenCL][Docs] Describe internals of TableGen builtins

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

Differential Revision: https://reviews.llvm.org/D96150

Added: 
    

Modified: 
    clang/docs/OpenCLSupport.rst

Removed: 
    


################################################################################
diff  --git a/clang/docs/OpenCLSupport.rst b/clang/docs/OpenCLSupport.rst
index 716ce9953e35..bf5aea1a8a67 100644
--- a/clang/docs/OpenCLSupport.rst
+++ b/clang/docs/OpenCLSupport.rst
@@ -114,6 +114,8 @@ 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
@@ -129,6 +131,28 @@ There are some standard OpenCL functions that are implemented as Clang builtins:
   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
@@ -239,6 +263,8 @@ 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
 ----------------------------------