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
================
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
: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**
.. 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
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>`_
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
-----------------------
.. 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:
however :option:`-cl-ext` flag can be used to toggle individual extensions and
features.
-
-
.. _opencl_header:
OpenCL Header
.. 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
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>`_.
$ 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