Skip to content

Commit d7cc3a0

Browse files
author
Anastasia Stulova
committed
[OpenCL][Docs] Moved info from UsersManual into OpenCLSupport.
Moved information detailing the implementation from UsersManual into OpenCLSupport page as it is not relevant to the user's of clang but primarily needed for the compiler developers. Tags: #clang Differential Revision: https://reviews.llvm.org/D95061
1 parent 3e206a5 commit d7cc3a0

File tree

2 files changed

+136
-117
lines changed

2 files changed

+136
-117
lines changed

‎clang/docs/OpenCLSupport.rst

Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,133 @@ There are also other :ref:`new and experimental features <opencl_experimenal>` a
2828
For general issues and bugs with OpenCL in clang refer to `Bugzilla
2929
<https://bugs.llvm.org/buglist.cgi?component=OpenCL&list_id=172679&product=clang&resolution=--->`__.
3030

31+
Internals Manual
32+
================
33+
34+
This section acts as internal documentation for OpenCL features design
35+
as well as some important implementation aspects. It is primarily targeted
36+
at the advanced users and the toolchain developers integrating frontend
37+
functionality as a component.
38+
39+
OpenCL Metadata
40+
---------------
41+
42+
Clang uses metadata to provide additional OpenCL semantics in IR needed for
43+
backends and OpenCL runtime.
44+
45+
Each kernel will have function metadata attached to it, specifying the arguments.
46+
Kernel argument metadata is used to provide source level information for querying
47+
at runtime, for example using the `clGetKernelArgInfo
48+
<https://www.khronos.org/registry/OpenCL/specs/opencl-1.2.pdf#167>`_
49+
call.
50+
51+
Note that ``-cl-kernel-arg-info`` enables more information about the original
52+
kernel code to be added e.g. kernel parameter names will appear in the OpenCL
53+
metadata along with other information.
54+
55+
The IDs used to encode the OpenCL's logical address spaces in the argument info
56+
metadata follows the SPIR address space mapping as defined in the SPIR
57+
specification `section 2.2
58+
<https://www.khronos.org/registry/spir/specs/spir_spec-2.0.pdf#18>`_
59+
60+
OpenCL Specific Options
61+
-----------------------
62+
63+
In addition to the options described in :doc:`UsersManual` there are the
64+
following options specific to the OpenCL frontend.
65+
66+
.. _opencl_cl_ext:
67+
68+
.. option:: -cl-ext
69+
70+
Disables support of OpenCL extensions. All OpenCL targets provide a list
71+
of extensions that they support. Clang allows to amend this using the ``-cl-ext``
72+
flag with a comma-separated list of extensions prefixed with ``'+'`` or ``'-'``.
73+
The syntax: ``-cl-ext=<(['-'|'+']<extension>[,])+>``, where extensions
74+
can be either one of `the OpenCL published extensions
75+
<https://www.khronos.org/registry/OpenCL>`_
76+
or any vendor extension. Alternatively, ``'all'`` can be used to enable
77+
or disable all known extensions.
78+
79+
Note that this is a frontend-only flag and therefore it requires the use of
80+
flags that forward options to the frontend e.g. ``-cc1`` or ``-Xclang``.
81+
82+
Example disabling double support for the 64-bit SPIR target:
83+
84+
.. code-block:: console
85+
86+
$ clang -cc1 -triple spir64-unknown-unknown -cl-ext=-cl_khr_fp64 test.cl
87+
88+
Enabling all extensions except double support in R600 AMD GPU can be done using:
89+
90+
.. code-block:: console
91+
92+
$ clang -cc1 -triple r600-unknown-unknown -cl-ext=-all,+cl_khr_fp16 test.cl
93+
94+
.. _opencl_fake_address_space_map:
95+
96+
.. option:: -ffake-address-space-map
97+
98+
Overrides the target address space map with a fake map.
99+
This allows adding explicit address space IDs to the bitcode for non-segmented
100+
memory architectures that do not have separate IDs for each of the OpenCL
101+
logical address spaces by default. Passing ``-ffake-address-space-map`` will
102+
add/override address spaces of the target compiled for with the following values:
103+
``1-global``, ``2-constant``, ``3-local``, ``4-generic``. The private address
104+
space is represented by the absence of an address space attribute in the IR (see
105+
also :ref:`the section on the address space attribute <opencl_addrsp>`).
106+
107+
.. code-block:: console
108+
109+
$ clang -cc1 -ffake-address-space-map test.cl
110+
111+
Note that this is a frontend-only flag and therefore it requires the use of
112+
flags that forward options to the frontend e.g. ``-cc1`` or ``-Xclang``.
113+
114+
OpenCL builtins
115+
---------------
116+
117+
There are some standard OpenCL functions that are implemented as Clang builtins:
118+
119+
- All pipe functions from `section 6.13.16.2/6.13.16.3
120+
<https://www.khronos.org/registry/cl/specs/opencl-2.0-openclc.pdf#160>`_ of
121+
the OpenCL v2.0 kernel language specification. `
122+
123+
- Address space qualifier conversion functions ``to_global``/``to_local``/``to_private``
124+
from `section 6.13.9
125+
<https://www.khronos.org/registry/cl/specs/opencl-2.0-openclc.pdf#101>`_.
126+
127+
- All the ``enqueue_kernel`` functions from `section 6.13.17.1
128+
<https://www.khronos.org/registry/cl/specs/opencl-2.0-openclc.pdf#164>`_ and
129+
enqueue query functions from `section 6.13.17.5
130+
<https://www.khronos.org/registry/cl/specs/opencl-2.0-openclc.pdf#171>`_.
131+
132+
.. _opencl_addrsp:
133+
134+
Address spaces attribute
135+
------------------------
136+
137+
Clang has arbitrary address space support using the ``address_space(N)``
138+
attribute, where ``N`` is an integer number in the range specified in the
139+
Clang source code. This addresses spaces can be used along with the OpenCL
140+
address spaces however when such addresses spaces converted to/from OpenCL
141+
address spaces the behavior is not governed by OpenCL specification.
142+
143+
An OpenCL implementation provides a list of standard address spaces using
144+
keywords: ``private``, ``local``, ``global``, and ``generic``. In the AST and
145+
in the IR each of the address spaces will be represented by unique number
146+
provided in the Clang source code. The specific IDs for an address space do not
147+
have to match between the AST and the IR. Typically in the AST address space
148+
numbers represent logical segments while in the IR they represent physical
149+
segments.
150+
Therefore, machines with flat memory segments can map all AST address space
151+
numbers to the same physical segment ID or skip address space attribute
152+
completely while generating the IR. However, if the address space information
153+
is needed by the IR passes e.g. to improve alias analysis, it is recommended
154+
to keep it and only lower to reflect physical memory segments in the late
155+
machine passes. The mapping between logical and target address spaces is
156+
specified in the Clang's source code.
157+
31158
.. _cxx_for_opencl_impl:
32159

33160
C++ for OpenCL Implementation Status

‎clang/docs/UsersManual.rst

Lines changed: 9 additions & 117 deletions
Original file line numberDiff line numberDiff line change
@@ -2914,6 +2914,10 @@ Examples:
29142914
29152915
$ clang -cl-std=CL2.0 -cl-single-precision-constant test.cl
29162916
2917+
2918+
Many flags used for the compilation for C sources can also be passed while
2919+
compiling for OpenCL, examples: ``-c``, ``-O<1-4|s>``, ``-o``, ``-emit-llvm``, etc.
2920+
29172921
Some extra options are available to support special OpenCL features.
29182922

29192923
.. option:: -finclude-default-header
@@ -2944,56 +2948,7 @@ installation directory.
29442948
In this example it is assumed that the kernel code contains
29452949
``#include <opencl-c.h>`` just as a regular C include.
29462950

2947-
.. _opencl_cl_ext:
2948-
2949-
.. option:: -cl-ext
2950-
2951-
Disables support of OpenCL extensions. All OpenCL targets provide a list
2952-
of extensions that they support. Clang allows to amend this using the ``-cl-ext``
2953-
flag with a comma-separated list of extensions prefixed with ``'+'`` or ``'-'``.
2954-
The syntax: ``-cl-ext=<(['-'|'+']<extension>[,])+>``, where extensions
2955-
can be either one of `the OpenCL published extensions
2956-
<https://www.khronos.org/registry/OpenCL>`_
2957-
or any vendor extension. Alternatively, ``'all'`` can be used to enable
2958-
or disable all known extensions.
2959-
2960-
Note that this is a frontend-only flag and therefore it requires the use of
2961-
flags that forward options to the frontend e.g. ``-cc1`` or ``-Xclang``.
2962-
2963-
Example disabling double support for the 64-bit SPIR target:
2964-
2965-
.. code-block:: console
2966-
2967-
$ clang -cc1 -triple spir64-unknown-unknown -cl-ext=-cl_khr_fp64 test.cl
2968-
2969-
Enabling all extensions except double support in R600 AMD GPU can be done using:
2970-
2971-
.. code-block:: console
2972-
2973-
$ clang -cc1 -triple r600-unknown-unknown -cl-ext=-all,+cl_khr_fp16 test.cl
2974-
2975-
.. _opencl_fake_address_space_map:
2976-
2977-
.. option:: -ffake-address-space-map
2978-
2979-
Overrides the target address space map with a fake map.
2980-
This allows adding explicit address space IDs to the bitcode for non-segmented
2981-
memory architectures that do not have separate IDs for each of the OpenCL
2982-
logical address spaces by default. Passing ``-ffake-address-space-map`` will
2983-
add/override address spaces of the target compiled for with the following values:
2984-
``1-global``, ``2-constant``, ``3-local``, ``4-generic``. The private address
2985-
space is represented by the absence of an address space attribute in the IR (see
2986-
also :ref:`the section on the address space attribute <opencl_addrsp>`).
2987-
2988-
.. code-block:: console
2989-
2990-
$ clang -cc1 -ffake-address-space-map test.cl
2991-
2992-
Note that this is a frontend-only flag and therefore it requires the use of
2993-
flags that forward options to the frontend e.g. ``-cc1`` or ``-Xclang``.
2994-
2995-
Some other flags used for the compilation for C can also be passed while
2996-
compiling for OpenCL, examples: ``-c``, ``-O<1-4|s>``, ``-o``, ``-emit-llvm``, etc.
2951+
More options are documented in :doc:`OpenCLSupport`.
29972952

29982953
OpenCL Targets
29992954
--------------
@@ -3058,10 +3013,10 @@ OpenCL Header
30583013
-------------
30593014

30603015
By default Clang will not include standard headers and therefore OpenCL builtin
3061-
functions and some types (i.e. vectors) are unknown. The default CL header is,
3062-
however, provided in the Clang installation and can be enabled by passing the
3063-
``-finclude-default-header`` flag (see :ref:`flags description <opencl_cl_ext>`
3064-
for more details).
3016+
functions and some types (i.e. vectors) are unknown during compilation. The
3017+
default CL header is, however, provided in the Clang installation and can be
3018+
enabled by passing the ``-finclude-default-header`` flag (see :ref:`flags
3019+
description <opencl_cl_ext>` for more details).
30653020

30663021
.. code-block:: console
30673022
@@ -3125,27 +3080,6 @@ Clang also supports language extensions documented in `The OpenCL C Language
31253080
Extensions Documentation
31263081
<https://github.com/KhronosGroup/Khronosdotorg/blob/master/api/opencl/assets/OpenCL_LangExt.pdf>`_.
31273082

3128-
OpenCL Metadata
3129-
---------------
3130-
3131-
Clang uses metadata to provide additional OpenCL semantics in IR needed for
3132-
backends and OpenCL runtime.
3133-
3134-
Each kernel will have function metadata attached to it, specifying the arguments.
3135-
Kernel argument metadata is used to provide source level information for querying
3136-
at runtime, for example using the `clGetKernelArgInfo
3137-
<https://www.khronos.org/registry/OpenCL/specs/opencl-1.2.pdf#167>`_
3138-
call.
3139-
3140-
Note that ``-cl-kernel-arg-info`` enables more information about the original CL
3141-
code to be added e.g. kernel parameter names will appear in the OpenCL metadata
3142-
along with other information.
3143-
3144-
The IDs used to encode the OpenCL's logical address spaces in the argument info
3145-
metadata follows the SPIR address space mapping as defined in the SPIR
3146-
specification `section 2.2
3147-
<https://www.khronos.org/registry/spir/specs/spir_spec-2.0.pdf#18>`_
3148-
31493083
OpenCL-Specific Attributes
31503084
--------------------------
31513085

@@ -3247,48 +3181,6 @@ CFG that modify semantics of the original program.
32473181
``noduplicate`` is kept for backwards compatibility only and it considered to be
32483182
deprecated for future uses.
32493183

3250-
.. _opencl_addrsp:
3251-
3252-
address_space
3253-
^^^^^^^^^^^^^
3254-
3255-
Clang has arbitrary address space support using the ``address_space(N)``
3256-
attribute, where ``N`` is an integer number in the range ``0`` to ``16777215``
3257-
(``0xffffffu``).
3258-
3259-
An OpenCL implementation provides a list of standard address spaces using
3260-
keywords: ``private``, ``local``, ``global``, and ``generic``. In the AST and
3261-
in the IR local, global, or generic will be represented by the address space
3262-
attribute with the corresponding unique number. Note that private does not have
3263-
any corresponding attribute added and, therefore, is represented by the absence
3264-
of an address space number. The specific IDs for an address space do not have to
3265-
match between the AST and the IR. Typically in the AST address space numbers
3266-
represent logical segments while in the IR they represent physical segments.
3267-
Therefore, machines with flat memory segments can map all AST address space
3268-
numbers to the same physical segment ID or skip address space attribute
3269-
completely while generating the IR. However, if the address space information
3270-
is needed by the IR passes e.g. to improve alias analysis, it is recommended
3271-
to keep it and only lower to reflect physical memory segments in the late
3272-
machine passes.
3273-
3274-
OpenCL builtins
3275-
---------------
3276-
3277-
There are some standard OpenCL functions that are implemented as Clang builtins:
3278-
3279-
- All pipe functions from `section 6.13.16.2/6.13.16.3
3280-
<https://www.khronos.org/registry/cl/specs/opencl-2.0-openclc.pdf#160>`_ of
3281-
the OpenCL v2.0 kernel language specification. `
3282-
3283-
- Address space qualifier conversion functions ``to_global``/``to_local``/``to_private``
3284-
from `section 6.13.9
3285-
<https://www.khronos.org/registry/cl/specs/opencl-2.0-openclc.pdf#101>`_.
3286-
3287-
- All the ``enqueue_kernel`` functions from `section 6.13.17.1
3288-
<https://www.khronos.org/registry/cl/specs/opencl-2.0-openclc.pdf#164>`_ and
3289-
enqueue query functions from `section 6.13.17.5
3290-
<https://www.khronos.org/registry/cl/specs/opencl-2.0-openclc.pdf#171>`_.
3291-
32923184
.. _cxx_for_opencl:
32933185

32943186
C++ for OpenCL

0 commit comments

Comments
 (0)