diff --git a/clang/docs/OpenCLSupport.rst b/clang/docs/OpenCLSupport.rst --- a/clang/docs/OpenCLSupport.rst +++ b/clang/docs/OpenCLSupport.rst @@ -28,6 +28,133 @@ For general issues and bugs with OpenCL in clang refer to `Bugzilla `__. +Internals Manual +================ + +This section acts as internal documentation for OpenCL features design +as well as some important implementation aspects. It is primarily targeted +at the advanced users and the toolchain developers integrating frontend +functionality as a component. + +OpenCL Metadata +--------------- + +Clang uses metadata to provide additional OpenCL semantics in IR needed for +backends and OpenCL runtime. + +Each kernel will have function metadata attached to it, specifying the arguments. +Kernel argument metadata is used to provide source level information for querying +at runtime, for example using the `clGetKernelArgInfo +`_ +call. + +Note that ``-cl-kernel-arg-info`` enables more information about the original +kernel code to be added e.g. kernel parameter names will appear in the OpenCL +metadata along with other information. + +The IDs used to encode the OpenCL's logical address spaces in the argument info +metadata follows the SPIR address space mapping as defined in the SPIR +specification `section 2.2 +`_ + +OpenCL Specific Options +----------------------- + +In addition to the options described in :doc:`UsersManual` there are the +following options specific to the OpenCL frontend. + +.. _opencl_cl_ext: + +.. option:: -cl-ext + +Disables support of OpenCL extensions. All OpenCL targets provide a list +of extensions that they support. Clang allows to amend this using the ``-cl-ext`` +flag with a comma-separated list of extensions prefixed with ``'+'`` or ``'-'``. +The syntax: ``-cl-ext=<(['-'|'+'][,])+>``, where extensions +can be either one of `the OpenCL published extensions +`_ +or any vendor extension. Alternatively, ``'all'`` can be used to enable +or disable all known extensions. + +Note that this is a frontend-only flag and therefore it requires the use of +flags that forward options to the frontend e.g. ``-cc1`` or ``-Xclang``. + +Example disabling double support for the 64-bit SPIR target: + + .. code-block:: console + + $ clang -cc1 -triple spir64-unknown-unknown -cl-ext=-cl_khr_fp64 test.cl + +Enabling all extensions except double support in R600 AMD GPU can be done using: + + .. code-block:: console + + $ clang -cc1 -triple r600-unknown-unknown -cl-ext=-all,+cl_khr_fp16 test.cl + +.. _opencl_fake_address_space_map: + +.. option:: -ffake-address-space-map + +Overrides the target address space map with a fake map. +This allows adding explicit address space IDs to the bitcode for non-segmented +memory architectures that do not have separate IDs for each of the OpenCL +logical address spaces by default. Passing ``-ffake-address-space-map`` will +add/override address spaces of the target compiled for with the following values: +``1-global``, ``2-constant``, ``3-local``, ``4-generic``. The private address +space is represented by the absence of an address space attribute in the IR (see +also :ref:`the section on the address space attribute `). + + .. code-block:: console + + $ clang -cc1 -ffake-address-space-map test.cl + +Note that this is a frontend-only flag and therefore it requires the use of +flags that forward options to the frontend e.g. ``-cc1`` or ``-Xclang``. + +OpenCL builtins +--------------- + +There are some standard OpenCL functions that are implemented as Clang builtins: + +- All pipe functions from `section 6.13.16.2/6.13.16.3 + `_ of + the OpenCL v2.0 kernel language specification. ` + +- Address space qualifier conversion functions ``to_global``/``to_local``/``to_private`` + from `section 6.13.9 + `_. + +- All the ``enqueue_kernel`` functions from `section 6.13.17.1 + `_ and + enqueue query functions from `section 6.13.17.5 + `_. + +.. _opencl_addrsp: + +Address spaces attribute +------------------------ + +Clang has arbitrary address space support using the ``address_space(N)`` +attribute, where ``N`` is an integer number in the range specified in the +Clang source code. This addresses spaces can be used along with the OpenCL +address spaces however when such addresses spaces converted to/from OpenCL +address spaces the behavior is not governed by OpenCL specification. + +An OpenCL implementation provides a list of standard address spaces using +keywords: ``private``, ``local``, ``global``, and ``generic``. In the AST and +in the IR each of the address spaces will be represented by unique number +provided in the Clang source code. The specific IDs for an address space do not +have to match between the AST and the IR. Typically in the AST address space +numbers represent logical segments while in the IR they represent physical +segments. +Therefore, machines with flat memory segments can map all AST address space +numbers to the same physical segment ID or skip address space attribute +completely while generating the IR. However, if the address space information +is needed by the IR passes e.g. to improve alias analysis, it is recommended +to keep it and only lower to reflect physical memory segments in the late +machine passes. The mapping between logical and target address spaces is +specified in the Clang's source code. + .. _cxx_for_opencl_impl: C++ for OpenCL Implementation Status diff --git a/clang/docs/UsersManual.rst b/clang/docs/UsersManual.rst --- a/clang/docs/UsersManual.rst +++ b/clang/docs/UsersManual.rst @@ -2914,6 +2914,10 @@ $ clang -cl-std=CL2.0 -cl-single-precision-constant test.cl + +Many flags used for the compilation for C sources can also be passed while +compiling for OpenCL, examples: ``-c``, ``-O<1-4|s>``, ``-o``, ``-emit-llvm``, etc. + Some extra options are available to support special OpenCL features. .. option:: -finclude-default-header @@ -2944,56 +2948,7 @@ In this example it is assumed that the kernel code contains ``#include `` just as a regular C include. -.. _opencl_cl_ext: - -.. option:: -cl-ext - -Disables support of OpenCL extensions. All OpenCL targets provide a list -of extensions that they support. Clang allows to amend this using the ``-cl-ext`` -flag with a comma-separated list of extensions prefixed with ``'+'`` or ``'-'``. -The syntax: ``-cl-ext=<(['-'|'+'][,])+>``, where extensions -can be either one of `the OpenCL published extensions -`_ -or any vendor extension. Alternatively, ``'all'`` can be used to enable -or disable all known extensions. - -Note that this is a frontend-only flag and therefore it requires the use of -flags that forward options to the frontend e.g. ``-cc1`` or ``-Xclang``. - -Example disabling double support for the 64-bit SPIR target: - - .. code-block:: console - - $ clang -cc1 -triple spir64-unknown-unknown -cl-ext=-cl_khr_fp64 test.cl - -Enabling all extensions except double support in R600 AMD GPU can be done using: - - .. code-block:: console - - $ clang -cc1 -triple r600-unknown-unknown -cl-ext=-all,+cl_khr_fp16 test.cl - -.. _opencl_fake_address_space_map: - -.. option:: -ffake-address-space-map - -Overrides the target address space map with a fake map. -This allows adding explicit address space IDs to the bitcode for non-segmented -memory architectures that do not have separate IDs for each of the OpenCL -logical address spaces by default. Passing ``-ffake-address-space-map`` will -add/override address spaces of the target compiled for with the following values: -``1-global``, ``2-constant``, ``3-local``, ``4-generic``. The private address -space is represented by the absence of an address space attribute in the IR (see -also :ref:`the section on the address space attribute `). - - .. code-block:: console - - $ clang -cc1 -ffake-address-space-map test.cl - -Note that this is a frontend-only flag and therefore it requires the use of -flags that forward options to the frontend e.g. ``-cc1`` or ``-Xclang``. - -Some other flags used for the compilation for C can also be passed while -compiling for OpenCL, examples: ``-c``, ``-O<1-4|s>``, ``-o``, ``-emit-llvm``, etc. +More options are documented in :doc:`OpenCLSupport`. OpenCL Targets -------------- @@ -3058,10 +3013,10 @@ ------------- By default Clang will not include standard headers and therefore OpenCL builtin -functions and some types (i.e. vectors) are unknown. The default CL header is, -however, provided in the Clang installation and can be enabled by passing the -``-finclude-default-header`` flag (see :ref:`flags description ` -for more details). +functions and some types (i.e. vectors) are unknown during compilation. The +default CL header is, however, provided in the Clang installation and can be +enabled by passing the ``-finclude-default-header`` flag (see :ref:`flags +description ` for more details). .. code-block:: console @@ -3125,27 +3080,6 @@ Extensions Documentation `_. -OpenCL Metadata ---------------- - -Clang uses metadata to provide additional OpenCL semantics in IR needed for -backends and OpenCL runtime. - -Each kernel will have function metadata attached to it, specifying the arguments. -Kernel argument metadata is used to provide source level information for querying -at runtime, for example using the `clGetKernelArgInfo -`_ -call. - -Note that ``-cl-kernel-arg-info`` enables more information about the original CL -code to be added e.g. kernel parameter names will appear in the OpenCL metadata -along with other information. - -The IDs used to encode the OpenCL's logical address spaces in the argument info -metadata follows the SPIR address space mapping as defined in the SPIR -specification `section 2.2 -`_ - OpenCL-Specific Attributes -------------------------- @@ -3247,48 +3181,6 @@ ``noduplicate`` is kept for backwards compatibility only and it considered to be deprecated for future uses. -.. _opencl_addrsp: - -address_space -^^^^^^^^^^^^^ - -Clang has arbitrary address space support using the ``address_space(N)`` -attribute, where ``N`` is an integer number in the range ``0`` to ``16777215`` -(``0xffffffu``). - -An OpenCL implementation provides a list of standard address spaces using -keywords: ``private``, ``local``, ``global``, and ``generic``. In the AST and -in the IR local, global, or generic will be represented by the address space -attribute with the corresponding unique number. Note that private does not have -any corresponding attribute added and, therefore, is represented by the absence -of an address space number. The specific IDs for an address space do not have to -match between the AST and the IR. Typically in the AST address space numbers -represent logical segments while in the IR they represent physical segments. -Therefore, machines with flat memory segments can map all AST address space -numbers to the same physical segment ID or skip address space attribute -completely while generating the IR. However, if the address space information -is needed by the IR passes e.g. to improve alias analysis, it is recommended -to keep it and only lower to reflect physical memory segments in the late -machine passes. - -OpenCL builtins ---------------- - -There are some standard OpenCL functions that are implemented as Clang builtins: - -- All pipe functions from `section 6.13.16.2/6.13.16.3 - `_ of - the OpenCL v2.0 kernel language specification. ` - -- Address space qualifier conversion functions ``to_global``/``to_local``/``to_private`` - from `section 6.13.9 - `_. - -- All the ``enqueue_kernel`` functions from `section 6.13.17.1 - `_ and - enqueue query functions from `section 6.13.17.5 - `_. - .. _cxx_for_opencl: C++ for OpenCL