Anastasia created this revision. Anastasia added a reviewer: svenvh. Herald added subscribers: ebevhan, yaxunl. Anastasia requested review of this revision.
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. https://reviews.llvm.org/D95061 Files: clang/docs/OpenCLSupport.rst clang/docs/UsersManual.rst
Index: clang/docs/UsersManual.rst =================================================================== --- clang/docs/UsersManual.rst +++ clang/docs/UsersManual.rst @@ -2887,56 +2887,7 @@ In this example it is assumed that the kernel code contains ``#include <opencl-c.h>`` 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=<(['-'|'+']<extension>[,])+>``, where extensions -can be either one of `the OpenCL published extensions -<https://www.khronos.org/registry/OpenCL>`_ -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 <opencl_addrsp>`). - - .. 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 -------------- @@ -3001,10 +2952,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 <opencl_cl_ext>` -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 <opencl_cl_ext>` for more details). .. code-block:: console @@ -3063,27 +3014,6 @@ Extensions Documentation <https://github.com/KhronosGroup/Khronosdotorg/blob/master/api/opencl/assets/OpenCL_LangExt.pdf>`_. -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 -<https://www.khronos.org/registry/OpenCL/specs/opencl-1.2.pdf#167>`_ -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 -<https://www.khronos.org/registry/spir/specs/spir_spec-2.0.pdf#18>`_ - OpenCL-Specific Attributes -------------------------- @@ -3185,48 +3115,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 - <https://www.khronos.org/registry/cl/specs/opencl-2.0-openclc.pdf#160>`_ of - the OpenCL v2.0 kernel language specification. ` - -- Address space qualifier conversion functions ``to_global``/``to_local``/``to_private`` - from `section 6.13.9 - <https://www.khronos.org/registry/cl/specs/opencl-2.0-openclc.pdf#101>`_. - -- All the ``enqueue_kernel`` functions from `section 6.13.17.1 - <https://www.khronos.org/registry/cl/specs/opencl-2.0-openclc.pdf#164>`_ and - enqueue query functions from `section 6.13.17.5 - <https://www.khronos.org/registry/cl/specs/opencl-2.0-openclc.pdf#171>`_. - .. _cxx_for_opencl: C++ for OpenCL Index: clang/docs/OpenCLSupport.rst =================================================================== --- clang/docs/OpenCLSupport.rst +++ clang/docs/OpenCLSupport.rst @@ -28,6 +28,136 @@ For general issues and bugs with OpenCL in clang refer to `Bugzilla <https://bugs.llvm.org/buglist.cgi?component=OpenCL&list_id=172679&product=clang&resolution=--->`__. +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 +<https://www.khronos.org/registry/OpenCL/specs/opencl-1.2.pdf#167>`_ +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 +<https://www.khronos.org/registry/spir/specs/spir_spec-2.0.pdf#18>`_ + +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=<(['-'|'+']<extension>[,])+>``, where extensions +can be either one of `the OpenCL published extensions +<https://www.khronos.org/registry/OpenCL>`_ +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 <opencl_addrsp>`). + + .. 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. + +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 + <https://www.khronos.org/registry/cl/specs/opencl-2.0-openclc.pdf#160>`_ of + the OpenCL v2.0 kernel language specification. ` + +- Address space qualifier conversion functions ``to_global``/``to_local``/``to_private`` + from `section 6.13.9 + <https://www.khronos.org/registry/cl/specs/opencl-2.0-openclc.pdf#101>`_. + +- All the ``enqueue_kernel`` functions from `section 6.13.17.1 + <https://www.khronos.org/registry/cl/specs/opencl-2.0-openclc.pdf#164>`_ and + enqueue query functions from `section 6.13.17.5 + <https://www.khronos.org/registry/cl/specs/opencl-2.0-openclc.pdf#171>`_. + +.. _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
_______________________________________________ cfe-commits mailing list cfe-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
