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 _______________________________________________ cfe-commits mailing list cfe-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
