[clang] 3087afb - [OpenCL][Doc] Misc improvements related to SPIR-V support.
Anastasia Stulova via cfe-commits
cfe-commits at lists.llvm.org
Thu May 26 07:54:47 PDT 2022
Author: Anastasia Stulova
Date: 2022-05-26T15:54:33+01:00
New Revision: 3087afb421bf4ca4450d8981a1410e1a09f3794a
URL: https://github.com/llvm/llvm-project/commit/3087afb421bf4ca4450d8981a1410e1a09f3794a
DIFF: https://github.com/llvm/llvm-project/commit/3087afb421bf4ca4450d8981a1410e1a09f3794a.diff
LOG: [OpenCL][Doc] Misc improvements related to SPIR-V support.
Added:
Modified:
clang/docs/OpenCLSupport.rst
clang/docs/UsersManual.rst
Removed:
################################################################################
diff --git a/clang/docs/OpenCLSupport.rst b/clang/docs/OpenCLSupport.rst
index 6b05b5df1d0b..bcd55f6cc841 100644
--- a/clang/docs/OpenCLSupport.rst
+++ b/clang/docs/OpenCLSupport.rst
@@ -25,9 +25,19 @@ Clang also supports :ref:`the C++ for OpenCL kernel language <cxx_for_opencl_imp
There are also other :ref:`new and experimental features <opencl_experimenal>`
available.
-For general issues and bugs with OpenCL in clang refer to `the GitHub issue
-list
-<https://github.com/llvm/llvm-project/issues?q=is%3Aopen+is%3Aissue+label%3Aopencl>`__.
+
+
+Missing features or with limited support
+========================================
+
+- For general issues and bugs with OpenCL in clang refer to `the GitHub issue
+ list
+ <https://github.com/llvm/llvm-project/issues?q=is%3Aopen+is%3Aissue+label%3Aopencl>`__.
+
+- Command-line flag :ref:`-cl-ext <opencl_cl_ext>` (used to override extensions/
+ features supported by a target) is missing support of some functionality i.e. that is
+ implemented fully through libraries (see :ref:`library-based features and
+ extensions <opencl_ext_libs>`).
Internals Manual
================
@@ -213,18 +223,22 @@ 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>`_
+<https://github.com/llvm/llvm-project/blob/main/clang/include/clang/Basic/OpenCLExtensions.def>`__,
+containing the list of all extensions and optional features supported by
+the frontend.
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
+Note that by default targets like `SPIR-V`, `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.
+.. _opencl_ext_libs:
+
**Library functionality**
If an extension adds functionality that does not modify standard language
@@ -239,7 +253,9 @@ 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.
+predefined macros (see `feature/extension preprocessor macros defined in
+opencl-c-base.h
+<https://github.com/llvm/llvm-project/blob/main/clang/lib/Headers/opencl-c-base.h>`__).
**Pragmas**
@@ -336,8 +352,9 @@ user should specify both (extension and feature) in command-line flag:
.. code-block:: console
- $ clang -cc1 -cl-std=CL3.0 -cl-ext=+cl_khr_fp64,+__opencl_c_fp64 ...
- $ clang -cc1 -cl-std=CL3.0 -cl-ext=-cl_khr_fp64,-__opencl_c_fp64 ...
+ $ clang -cl-std=CL3.0 -cl-ext=+cl_khr_fp64,+__opencl_c_fp64 ...
+ $ clang -cl-std=CL3.0 -cl-ext=-cl_khr_fp64,-__opencl_c_fp64 ...
+
OpenCL C 3.0 Implementation Status
diff --git a/clang/docs/UsersManual.rst b/clang/docs/UsersManual.rst
index 45de85d342c8..b8c468333a67 100644
--- a/clang/docs/UsersManual.rst
+++ b/clang/docs/UsersManual.rst
@@ -3065,7 +3065,7 @@ Compiling to bitcode can be done as follows:
This will produce a file `test.bc` that can be used in vendor toolchains
to perform machine code generation.
-Note that if compiled to bitcode for generic targets such as SPIR,
+Note that if compiled to bitcode for generic targets such as SPIR/SPIR-V,
portable IR is produced that can be used with various vendor
tools as well as open source tools such as `SPIRV-LLVM Translator
<https://github.com/KhronosGroup/SPIRV-LLVM-Translator>`_
@@ -3073,15 +3073,18 @@ to produce SPIR-V binary. More details are provided in `the offline
compilation from OpenCL kernel sources into SPIR-V using open source
tools
<https://github.com/KhronosGroup/OpenCL-Guide/blob/main/chapters/os_tooling.md>`_.
+From clang 14 onwards SPIR-V can be generated directly as detailed in
+:ref:`the SPIR-V support section <spir-v>`.
Clang currently supports OpenCL C language standards up to v2.0. Clang mainly
supports full profile. There is only very limited support of the embedded
profile.
-Starting from clang 9 a C++ mode is available for OpenCL (see
+From clang 9 a C++ mode is available for OpenCL (see
:ref:`C++ for OpenCL <cxx_for_opencl>`).
OpenCL v3.0 support is complete but it remains in experimental state, see more
-details about the experimental features in :doc:`OpenCLSupport` page.
+details about the experimental features and limitations in :doc:`OpenCLSupport`
+page.
OpenCL Specific Options
-----------------------
@@ -3137,7 +3140,7 @@ Example disabling double support for the 64-bit SPIR-V target:
.. code-block:: console
- $ clang -target spirv64 -cl-ext=-cl_khr_fp64 test.cl
+ $ clang -c -target spirv64 -cl-ext=-cl_khr_fp64 test.cl
Enabling all extensions except double support in R600 AMD GPU can be done using:
@@ -3214,8 +3217,6 @@ Generic Targets
however :option:`-cl-ext` flag can be used to toggle individual extensions and
features.
-
-
.. _opencl_header:
OpenCL Header
@@ -3427,6 +3428,7 @@ Example of use:
.. code-block:: console
clang -cl-std=clc++1.0 test.clcpp
+ clang -cl-std=clc++ -c -target spirv64 test.cl
By default, files with ``.clcpp`` extension are compiled with the C++ for
@@ -3640,7 +3642,7 @@ To generate SPIR-V binaries, Clang uses the external ``llvm-spirv`` tool from th
Prior to the generation of SPIR-V binary with Clang, ``llvm-spirv``
should be built or installed. Please refer to `the following instructions
<https://github.com/KhronosGroup/SPIRV-LLVM-Translator#build-instructions>`_
-for more details. Clang will expects the ``llvm-spirv`` executable to
+for more details. Clang will expect the ``llvm-spirv`` executable to
be present in the ``PATH`` environment variable. Clang uses ``llvm-spirv``
with `the widely adopted assembly syntax package
<https://github.com/KhronosGroup/SPIRV-LLVM-Translator/#build-with-spirv-tools>`_.
@@ -3692,6 +3694,10 @@ installation instructions
$ clang -target spirv64 test1.cl test2.cl
+More information about the SPIR-V target settings and supported versions of SPIR-V
+format can be found in `the SPIR-V target guide
+<https://llvm.org/docs/SPIRVUsage.html>`__.
+
.. _clang-cl:
clang-cl
More information about the cfe-commits
mailing list