[PATCH] D97072: [OpenCL][Docs] Add guidelines for adding new extensions and features

[Anastasia Stulova via Phabricator via cfe-commits]

Anastasia created this revision.
Anastasia added reviewers: svenvh, azabaznov, yaxunl.
Herald added a subscriber: ebevhan.
Anastasia requested review of this revision.

Add documentation that explains how to extend clang with new extensions/features.

The guidelines also detail clang's position about the extension pragmas for the new functionality and it is expected the following change to be added first: https://reviews.llvm.org/D97052.

For further clarification around the extension pragma - the most common interpretation of the pragma in clang right now is the diagnostic of the use of types or functions from the extensions:

  def err_opencl_requires_extension : Error<
    "use of %select{type|declaration}0 %1 requires %2 extension to be enabled">;

This forces the developers to use the pragma, but it is not very clear why and it seems to violate the following statement in the spec:

> disable - Behave (including issuing errors and warnings) as if the extension extension_name is not part of the language definition.

The diagnostic given indicates that the disabled extension is indeed part of the language.

However, I must admit it doesn't seem that implementing dynamic loading/unloading of the extension functionality implied by the spec would be possible in clang. It is not clear why such flexibility would be needed either - most of the language provide one way of importing/including functionality.

Additionally, many extensions add functionality via the implicitly included headers and for using those no pragmas is required as no diagnostic is given if the pragma is not used.

Based on the above the conclusion is that the functionality provided by clang is neither conformant nor consistent for the user.


https://reviews.llvm.org/D97072

Files:
  clang/docs/OpenCLSupport.rst


Index: clang/docs/OpenCLSupport.rst
===================================================================
--- clang/docs/OpenCLSupport.rst
+++ clang/docs/OpenCLSupport.rst
@@ -153,6 +153,79 @@
   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 extensions modifies the standard parsing they need to be added to
+the clang frontend source code. This also means that the associate macro
+indicating the presence of the extensions should be added to clang.
+
+The default flow for adding the new extensions 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 the functionality that does not modify standard language
+parsing it should not require clang source code modifications. Most commonly
+such extensions add functionality via libraries (by adding new 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 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) with the sufficient level of details and, therefore,
+there is no default functionality provided by clang.
+
+Pragmas without detailed information of its behavior (explanation of changes it
+triggers in the parsing) should not be added to clang. Moreover, the acceptable
+behavior of pragmas should provide useful functionality to the user.
+
+Note that some legacy extensions (published prior to OpenCL 3.0), however 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
+the future releases, however, any future changes should not affect backward
+compatibility.
+
 .. _opencl_addrsp:
 
 Address spaces attribute


-------------- next part --------------
A non-text attachment was scrubbed...
Name: D97072.325032.patch
Type: text/x-patch
Size: 3774 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/cfe-commits/attachments/20210219/ca524b71/attachment-0001.bin>