[OpenCL][Doc] Misc improvements related to SPIR-V support.

Author: Anastasia Stulova

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

clang/docs/UsersManual.rst

@@ -3065,23 +3065,26 @@ 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>`_
 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