Skip to content

Commit 3087afb

Browse files
author
Anastasia Stulova
committed
[OpenCL][Doc] Misc improvements related to SPIR-V support.
1 parent ec0ef68 commit 3087afb

File tree

2 files changed

+38
-15
lines changed

2 files changed

+38
-15
lines changed

clang/docs/OpenCLSupport.rst

Lines changed: 25 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -25,9 +25,19 @@ Clang also supports :ref:`the C++ for OpenCL kernel language <cxx_for_opencl_imp
2525
There are also other :ref:`new and experimental features <opencl_experimenal>`
2626
available.
2727

28-
For general issues and bugs with OpenCL in clang refer to `the GitHub issue
29-
list
30-
<https://github.com/llvm/llvm-project/issues?q=is%3Aopen+is%3Aissue+label%3Aopencl>`__.
28+
29+
30+
Missing features or with limited support
31+
========================================
32+
33+
- For general issues and bugs with OpenCL in clang refer to `the GitHub issue
34+
list
35+
<https://github.com/llvm/llvm-project/issues?q=is%3Aopen+is%3Aissue+label%3Aopencl>`__.
36+
37+
- Command-line flag :ref:`-cl-ext <opencl_cl_ext>` (used to override extensions/
38+
features supported by a target) is missing support of some functionality i.e. that is
39+
implemented fully through libraries (see :ref:`library-based features and
40+
extensions <opencl_ext_libs>`).
3141

3242
Internals Manual
3343
================
@@ -213,18 +223,22 @@ indicating the presence of the extension should be added to clang.
213223

214224
The default flow for adding a new extension into the frontend is to
215225
modify `OpenCLExtensions.def
216-
<https://github.com/llvm/llvm-project/blob/main/clang/include/clang/Basic/OpenCLExtensions.def>`_
226+
<https://github.com/llvm/llvm-project/blob/main/clang/include/clang/Basic/OpenCLExtensions.def>`__,
227+
containing the list of all extensions and optional features supported by
228+
the frontend.
217229

218230
This will add the macro automatically and also add a field in the target
219231
options ``clang::TargetOptions::OpenCLFeaturesMap`` to control the exposure
220232
of the new extension during the compilation.
221233

222-
Note that by default targets like `SPIR` or `X86` expose all the OpenCL
234+
Note that by default targets like `SPIR-V`, `SPIR` or `X86` expose all the OpenCL
223235
extensions. For all other targets the configuration has to be made explicitly.
224236

225237
Note that the target extension support performed by clang can be overridden
226238
with :ref:`-cl-ext <opencl_cl_ext>` command-line flags.
227239

240+
.. _opencl_ext_libs:
241+
228242
**Library functionality**
229243

230244
If an extension adds functionality that does not modify standard language
@@ -239,7 +253,9 @@ for more details refer to
239253
:ref:`the section on the OpenCL Header <opencl_header>`. The macros indicating
240254
the presence of such extensions can be added in the standard header files
241255
conditioned on target specific predefined macros or/and language version
242-
predefined macros.
256+
predefined macros (see `feature/extension preprocessor macros defined in
257+
opencl-c-base.h
258+
<https://github.com/llvm/llvm-project/blob/main/clang/lib/Headers/opencl-c-base.h>`__).
243259

244260
**Pragmas**
245261

@@ -336,8 +352,9 @@ user should specify both (extension and feature) in command-line flag:
336352

337353
.. code-block:: console
338354
339-
$ clang -cc1 -cl-std=CL3.0 -cl-ext=+cl_khr_fp64,+__opencl_c_fp64 ...
340-
$ clang -cc1 -cl-std=CL3.0 -cl-ext=-cl_khr_fp64,-__opencl_c_fp64 ...
355+
$ clang -cl-std=CL3.0 -cl-ext=+cl_khr_fp64,+__opencl_c_fp64 ...
356+
$ clang -cl-std=CL3.0 -cl-ext=-cl_khr_fp64,-__opencl_c_fp64 ...
357+
341358
342359
343360
OpenCL C 3.0 Implementation Status

clang/docs/UsersManual.rst

Lines changed: 13 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -3065,23 +3065,26 @@ Compiling to bitcode can be done as follows:
30653065
This will produce a file `test.bc` that can be used in vendor toolchains
30663066
to perform machine code generation.
30673067

3068-
Note that if compiled to bitcode for generic targets such as SPIR,
3068+
Note that if compiled to bitcode for generic targets such as SPIR/SPIR-V,
30693069
portable IR is produced that can be used with various vendor
30703070
tools as well as open source tools such as `SPIRV-LLVM Translator
30713071
<https://github.com/KhronosGroup/SPIRV-LLVM-Translator>`_
30723072
to produce SPIR-V binary. More details are provided in `the offline
30733073
compilation from OpenCL kernel sources into SPIR-V using open source
30743074
tools
30753075
<https://github.com/KhronosGroup/OpenCL-Guide/blob/main/chapters/os_tooling.md>`_.
3076+
From clang 14 onwards SPIR-V can be generated directly as detailed in
3077+
:ref:`the SPIR-V support section <spir-v>`.
30763078

30773079
Clang currently supports OpenCL C language standards up to v2.0. Clang mainly
30783080
supports full profile. There is only very limited support of the embedded
30793081
profile.
3080-
Starting from clang 9 a C++ mode is available for OpenCL (see
3082+
From clang 9 a C++ mode is available for OpenCL (see
30813083
:ref:`C++ for OpenCL <cxx_for_opencl>`).
30823084

30833085
OpenCL v3.0 support is complete but it remains in experimental state, see more
3084-
details about the experimental features in :doc:`OpenCLSupport` page.
3086+
details about the experimental features and limitations in :doc:`OpenCLSupport`
3087+
page.
30853088

30863089
OpenCL Specific Options
30873090
-----------------------
@@ -3137,7 +3140,7 @@ Example disabling double support for the 64-bit SPIR-V target:
31373140

31383141
.. code-block:: console
31393142
3140-
$ clang -target spirv64 -cl-ext=-cl_khr_fp64 test.cl
3143+
$ clang -c -target spirv64 -cl-ext=-cl_khr_fp64 test.cl
31413144
31423145
Enabling all extensions except double support in R600 AMD GPU can be done using:
31433146

@@ -3214,8 +3217,6 @@ Generic Targets
32143217
however :option:`-cl-ext` flag can be used to toggle individual extensions and
32153218
features.
32163219

3217-
3218-
32193220
.. _opencl_header:
32203221

32213222
OpenCL Header
@@ -3427,6 +3428,7 @@ Example of use:
34273428
.. code-block:: console
34283429
34293430
clang -cl-std=clc++1.0 test.clcpp
3431+
clang -cl-std=clc++ -c -target spirv64 test.cl
34303432
34313433
34323434
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
36403642
Prior to the generation of SPIR-V binary with Clang, ``llvm-spirv``
36413643
should be built or installed. Please refer to `the following instructions
36423644
<https://github.com/KhronosGroup/SPIRV-LLVM-Translator#build-instructions>`_
3643-
for more details. Clang will expects the ``llvm-spirv`` executable to
3645+
for more details. Clang will expect the ``llvm-spirv`` executable to
36443646
be present in the ``PATH`` environment variable. Clang uses ``llvm-spirv``
36453647
with `the widely adopted assembly syntax package
36463648
<https://github.com/KhronosGroup/SPIRV-LLVM-Translator/#build-with-spirv-tools>`_.
@@ -3692,6 +3694,10 @@ installation instructions
36923694
36933695
$ clang -target spirv64 test1.cl test2.cl
36943696
3697+
More information about the SPIR-V target settings and supported versions of SPIR-V
3698+
format can be found in `the SPIR-V target guide
3699+
<https://llvm.org/docs/SPIRVUsage.html>`__.
3700+
36953701
.. _clang-cl:
36963702

36973703
clang-cl

0 commit comments

Comments
 (0)