[clang] bafcb4c - [OpenCL][Docs] Add guidelines for new extensions and features.

[Anastasia Stulova via cfe-commits]

Author: Anastasia Stulova
Date: 2021-03-11T14:28:48Z
New Revision: bafcb4c6841a302d502b14fb93101fb590459935

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

LOG: [OpenCL][Docs] Add guidelines for new extensions and features.

Add documentation that explains how to extend clang with the new
extensions/features. The guidelines also detail clang's position
about the extension pragmas for the new functionality.

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

Added: 
    

Modified: 
    clang/docs/OpenCLSupport.rst

Removed: 
    


################################################################################
diff  --git a/clang/docs/OpenCLSupport.rst b/clang/docs/OpenCLSupport.rst
index 02522052e106..f7d6b1f7f2c9 100644
--- a/clang/docs/OpenCLSupport.rst
+++ b/clang/docs/OpenCLSupport.rst
@@ -168,6 +168,8 @@ also :ref:`the section on the address space attribute <opencl_addrsp>`).
 
      $ clang -cc1 -ffake-address-space-map test.cl
 
+.. _opencl_builtins:
+
 OpenCL builtins
 ---------------
 
@@ -210,6 +212,82 @@ of the following main components:
   inserted using ``InsertOCLBuiltinDeclarationsFromTable`` and overload
   resolution takes place.
 
+OpenCL Extensions and Features
+------------------------------
+
+Clang implements various extensions to OpenCL kernel languages.
+
+New functionality is accepted as soon as the documentation is detailed to the
+level sufficient to be implemented. There should be an evidence that the
+extension is designed with implementation feasibility in consideration and
+assessment of complexity for C/C++ based compilers. Alternatively, the
+documentation can be accepted in a format of a draft that can be further
+refined during the implementation.
+
+Implementation guidelines
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This section explains how to extend clang with the new functionality.
+
+**Parsing functionality**
+
+If an extension modifies the standard parsing it needs to be added to
+the clang frontend source code. This also means that the associated macro
+indicating the presence of the extension should be added to clang.
+
+The default flow for adding a new extension into the frontend is to
+modify `OpenCLExtensions.def
+<https://github.com/llvm/llvm-project/blob/main/clang/include/clang/Basic/OpenCLExtensions.def>`_
+
+This will add the macro automatically and also add a field in the target
+options ``clang::TargetOptions::OpenCLFeaturesMap`` to control the exposure
+of the new extension during the compilation.
+
+Note that by default targets like `SPIR` or `X86` expose all the OpenCL
+extensions. For all other targets the configuration has to be made explicitly.
+
+Note that the target extension support performed by clang can be overridden
+with :ref:`-cl-ext <opencl_cl_ext>` command-line flags.
+
+**Library functionality**
+
+If an extension adds functionality that does not modify standard language
+parsing it should not require modifying anything other than header files or
+``OpenCLBuiltins.td`` detailed in :ref:`OpenCL builtins <opencl_builtins>`.
+Most commonly such extensions add functionality via libraries (by adding
+non-native types or functions) parsed regularly. Similar to other languages this
+is the most common way to add new functionality.
+
+Clang has standard headers where new types and functions are being added,
+for more details refer to
+:ref:`the section on the OpenCL Header <opencl_header>`. The macros indicating
+the presence of such extensions can be added in the standard header files
+conditioned on target specific predefined macros or/and language version
+predefined macros.
+
+**Pragmas**
+
+Some extensions alter standard parsing dynamically via pragmas.
+
+Clang provides a mechanism to add the standard extension pragma
+``OPENCL EXTENSION`` by setting a dedicated flag in the extension list entry of
+``OpenCLExtensions.def``. Note that there is no default behavior for the
+standard extension pragmas as it is not specified (for the standards up to and
+including version 3.0) in a sufficient level of detail and, therefore,
+there is no default functionality provided by clang.
+
+Pragmas without detailed information of their behavior (e.g. an explanation of
+changes it triggers in the parsing) should not be added to clang. Moreover, the
+pragmas should provide useful functionality to the user. For example, such
+functionality should address a practical use case and not be redundant i.e.
+cannot be achieved using existing features.
+
+Note that some legacy extensions (published prior to OpenCL 3.0) still
+provide some non-conformant functionality for pragmas e.g. add diagnostics on
+the use of types or functions. This functionality is not guaranteed to remain in
+future releases. However, any future changes should not affect backward
+compatibility.
+
 .. _opencl_addrsp:
 
 Address spaces attribute